Pharos Project · SPM-Kit instrument · Alpha
Inspect the computation, not just the picture.
SPM-Kit is the open numerical engine for AFM, KPFM and force-spectroscopy data. Fathom is the interactive scientific workspace over that same core. Together they keep the route from instrument file to reported result visible.
Why this exists¶
AFM/SPM analysis often crosses proprietary formats, hidden preprocessing, manual exports and software-specific defaults. A plausible image is easy to produce; an inspectable chain of calibrated data, declared operations and preserved evidence is harder.
SPM-Kit separates that chain into explicit responsibilities:
- readers inspect instrument files and construct calibrated domain models;
- pure Core functions perform numerical analysis without GUI state;
- the Python API and CLI support notebooks, batch jobs, servers and CI;
- Fathom operates the same functions through task-oriented perspectives;
- exports preserve results and available provenance;
- independent companion repositories discover evidence, define synthetic truth and execute external validation campaigns.
The project is independently created, authored and led by José Labarca Baeza. It is alpha software: useful, testable and open to inspection, but not a certified metrology system.
What it computes¶
Image metrology
Plane, polynomial and row leveling; Sa, Sq, Sz, Ssk and Sku; profiles, grain statistics, radial PSD, Hurst exponent and correlation length.
Force spectroscopy
Baseline and contact detection, Hertz, Sneddon, DMT and experimental JKR fitting, adhesion, dissipation, force-volume property maps and reports.
KPFM
Contact-potential statistics and sample work-function calculation when a calibrated tip work function is supplied.
SMFS
Retract-curve baseline correction, event detection, WLC/FJC chain fitting and per-event result inspection.
Resonance
Thermal spectrum extraction, SHO fitting, effective mass, frequency-shift mass sensing and declared evaporation models.
Reporting and provenance
CSV, JSON, figures, HTML/PDF reports, recipes, project files, hashes and traceability records where the workflow exposes them.
One numerical core, two operating surfaces¶
instrument file
↓
reader inspection → calibrated SPMData / ForceCurve / ForceVolume
↓
SPM-Kit Core → typed numerical result
↓
Python API ───────── CLI ───────── Fathom
↓ ↓ ↓
notebook/batch artifacts interactive inspection
└──────────────┴──────────────┘
exports · reports · provenance
The boundary is deliberate. src/spmkit/core/ contains the parsers, domain
models and analysis. src/spmkit/cli/ and src/spmkit/gui/ orchestrate public
Core APIs. Fathom is not a second numerical implementation.
Read the architecture reference · Use the Python API · Inspect the CLI
Scientific evidence, in scope¶
The strongest retained public evidence is narrow and named. Numbers below are campaign results, not universal software scores.
| Capability | Retained result | Evidence | Boundary |
|---|---|---|---|
| Sa, Sq and Sz on 48 frozen synthetic matrices | 144/144 comparisons within the frozen threshold against Gwyddion 2.71 | CROSS_VALIDATED | Shared matrices; no physical acquisition or universal equivalence |
| Sa, Sq and Sz on 12 public experimental GWY records | 36/36 shared-matrix comparisons within threshold | CROSS_VALIDATED for the shared-matrix metric route | Public data are not physical ground truth; parser tracks were observational |
| Limited Nanoscope III parser scope | 18/18 roughness comparisons within threshold; zero reported pixel delta on six demonstrated files | NUMERICALLY_VERIFIED | Accidental pre-freeze unblinding; no blind holdout or family-wide claim |
| Physical models and numerical paths | deterministic synthetic recovery and software tests | capability-specific SOFTWARE_VERIFIED or NUMERICALLY_VERIFIED | Synthetic recovery is not physical validation |
No retained campaign establishes general physical validation (LEVEL 4) or
interlaboratory reproducibility (LEVEL 5). Read the scientific status
and campaign evidence.
The ecosystem¶
Data Hunter
Discovers and classifies candidate public evidence.
Phantoms
Creates controlled arrays with declared numerical truth.
Validation
Invokes the installed package through public interfaces.
SPM-Kit Core
Performs the analysis under evaluation.
Fathom
Lets researchers inspect and operate the same Core interactively.
Find the evidence → define the truth → test the system externally → preserve the result. The order is explanatory, not an automatic data pipeline. Human review separates discovery from validation, Phantoms stays independent from the analyzer, and Validation records reference independence campaign by campaign.
Start with the task, not the repository¶
| I need to… | Start here |
|---|---|
| Inspect and analyze a file interactively | Fathom quick start |
| Run reproducible Python or cluster analysis | SPM-Kit Core |
| Learn the physics behind the computation | Theory portal |
| Reproduce a documented analysis | Workflow tutorials |
| Evaluate a metric against known truth | Phantoms then Validation |
| Find a public native-format fixture | Data Hunter |
| Audit the evidence behind a claim | Scientific evidence |
| Add a reader or scientific capability | Extending SPM-Kit |
Install without ambiguity¶
The current source tree is 0.1.5.dev0. The latest GitHub release is 0.1.4,
while PyPI currently serves 0.1.2; therefore pip install spmkit does not
install the latest GitHub release. Use the development install below when you
need the documented portal surface:
python -m pip install "spmkit[gui] @ git+https://github.com/kegouro/spmkit@main"
spmkit --version
spmkit gui
See the installation guide for reproducible
Git tags, editable development installs, extras and platform notes. Companion
repositories have separate packages and are not installed by spmkit.
Honest scope¶
What this site does not claim
- SPM-Kit is alpha software and APIs may change before 1.0.
- It is not a certified instrument-control or metrological-traceability system.
- A supported parser is not automatically validated for every instrument variant.
- Synthetic recovery does not replace calibrated physical reference materials.
- A public dataset is a lead, not automatically a reference.
- Black-box execution separates processes; reference independence still requires an explicit argument.
- Not every feature has the same evidence level. Read the status beside the capability you use.
Citation and acknowledgement¶
José Labarca Baeza is the creator, author and lead developer of SPM-Kit and
Fathom. Cite the
software using CITATION.cff
and the guidance on the citation page.
Tomás Corrales and the SPM Lab at Universidad Técnica Federico Santa María provided selected experimental datasets and laboratory context during the development and evaluation of SPM-Kit.
María Saavedra Fredes and Benjamin Schleyer helped locate and share candidate datasets for the validation campaigns.
These contributions are acknowledgements, not software authorship, institutional ownership or an assertion that every located dataset was used, accepted, redistributable or scientifically suitable.