AbsoluteMagnetometry

Copyright (c) 2026 Y. del Castillo.

Physics-informed on-tip ESR-STM magnetometry for finite Haldane chains.

Workflow overview

Scientific motivation

This repository extends the ESR-STM inverse strategy introduced in
Phys. Rev. B 110, 045145 (2024),
and targets the on-tip sensing geometry demonstrated experimentally in
Esat et al., Nature Nanotechnology (2024).

The objective is not only signature detection but quantitative inference under realistic acquisition constraints:
sparse sensor sampling, finite frequency resolution, and geometric disorder.

The benchmark problem is finite Haldane chains (N=50..100), but the same inference scaffold can be reused for other surface-spin models by changing the reference-profile generator and geometry prior. This includes dimerized spin-1/2 chains in the Haldane phase and, in a straightforward extension, two-dimensional engineered spin arrays.

Inverse problem and outputs

For each sample, the model receives sparse ESR shifts and predicts:

• state sector (up_up, down_down, up_down, down_up),
• beta (edge-decay parameter),
• M_total,
• M_left,
• M_right.

Measurement model

The forward model is

y = A m + epsilon

where:

• m is the vector of effective spin moments,
• A is the geometry-dependent dipolar coupling matrix,
• epsilon combines additive noise and frequency quantization.

For sensor j and spin i, the coupling uses the full dipolar tensor projection:

A_ji ~ n^T [ (3 r r^T - r^2 I) / r^5 ] u

with r = R_j - r_i, sensor readout axis n, and moment axis u.

In the common collinear case (n || u || z), this reduces to the familiar scalar kernel proportional to (3 dz^2 - r^2)/r^5.

flowchart LR
    A["Surface chain geometry (r_i)"] --> C["3D dipolar forward model (A)"]
    B["Tip sensor coordinates (R_j)"] --> C
    D["Effective moments (m_i)"] --> C
    C --> E["Predicted shifts (Delta f_j)"]
    E --> F["Noisy and quantized ESR readout (y_j)"]
    F --> G["Inverse model"]
    G --> H["beta, M_total, M_left, M_right, state sector"]

Why Tikhonov + Transformer

The inverse stack is intentionally hybrid.

1. Physics baseline (Tikhonov regularization):

m_0 = argmin_m ||A m - y||_2^2 + lambda ||m||_2^2

m_0 = (A^T A + lambda I)^(-1) A^T y

This provides a stable first estimate for noisy or partially underdetermined settings.

2. Learned correction (masked TransformerEncoder):

The Transformer receives variable-length sparse sensor tokens (y_j and coupling features), applies sensor masking, and corrects the baseline toward the global observables.

The gain over pure direct inversion is practical: it captures non-ideal effects induced by sparse sampling, geometry variability, and quantization, while preserving an explicit physics anchor.

Reference for Tikhonov regularization:
A. N. Tikhonov and V. Y. Arsenin, Solutions of Ill-Posed Problems, Wiley (1977).

End-to-end workflow

1. Load N=100 reference profiles from data/spin_profiles.csv.
2. Build variable-size chains (N=50..100) by edge-preserving center reduction.
3. Interpolate profiles over dense beta support.
4. Generate irregular chain geometry and sparse on-tip sensor coordinates.
5. Compute ESR-like measurements with the dipolar forward model, additive noise, and resolution quantization.
6. Train the hybrid inverse model (Tikhonov baseline + Transformer correction).
7. Evaluate metrics vs beta, chain size, and sensor count.

Sensor placement is edge-biased by construction: at least four sensors per edge are always enforced, then additional sensors are distributed along the interior.

Benchmark summary (1 nm spin spacing)

Representative benchmark cases with matched noise and spectral resolution:

Observed degradation from 1 MHz to 5 MHz:

• beta MAE increases by about 116% (0.0140 -> 0.0301),
• M_total MAE increases by about 47% (0.0821 -> 0.1206),
• half-chain MAEs increase by about 45-48%.

State-sector identification remains robust, while quantitative regression degrades with reduced effective SNR.

Figure of merit example

The figure reports:

• a 3D irregular chain with elevated on-tip sensor positions,
• a representative sparse readout at 1 MHz / 1 MHz,
• beta-resolved percentage errors for all four observables at 1 MHz / 1 MHz (main case),
• the same beta-resolved errors at 5 MHz / 5 MHz (stress case).

Minimal workflow

1. Validate chain-size transfer (N=100 -> N=50..100): notebooks/Chain50to100_Validation.ipynb
2. Generate synthetic variable-geometry data: notebooks/VariableChainGeneration_50to100.ipynb
3. Train and evaluate inverse prediction: notebooks/TrainAndPredict_50to100.ipynb

Programmatic entry point:

from src.workflow import EndToEndConfig, run_end_to_end

summary = run_end_to_end(
    csv_path="data/spin_profiles.csv",
    cfg=EndToEndConfig(),
    return_artifacts=False,
)
print(summary["model_metrics"])
print(summary["state_accuracy"])

Repository structure

• data/spin_profiles.csv: reference profile table.
• src/: geometry, forward physics, dataset generation, training, inference.
• src/workflow.py: compact end-to-end orchestration.
• notebooks/: validation, generation, and training/evaluation workflows.
• docs/: method, data protocol, and numerics checks.
• assets/: figures used in this README.

Documentation map

• docs/Method.md: full method description (physics, model, training, outputs).
• docs/Data_and_Benchmarks.md: data contract, generation protocol, benchmark checklist.
• docs/Physics_and_Numerics_Checks.md: invariants, guards, and corner-case tests.

Environment

Install dependencies:

pip install -r requirements.txt

Run automated tests:

PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest

Continuous integration is configured in .github/workflows/tests.yml.

Current scope

• Chain sizes: N=50..100.
• Sparse ESR sensing with 3D sensor coordinates above a surface-anchored chain.
• Schema-adaptive profile loader (beta, spin_0..spin_N).

The same architecture can be re-parameterized for dimerized spin-1/2 chains in the Haldane phase by replacing beta with delta (e.g., J1 = 1 + delta, J2 = 1 - delta) and providing the corresponding profile table.

References

• Y. del Castillo and J. Fernandez-Rossier, Probing spin fractionalization with electron spin resonance based on scanning tunneling microscopy, Phys. Rev. B 110, 045145 (2024). DOI, APS page
• T. Esat et al., A quantum sensor for atomic-scale electric and magnetic fields, Nature Nanotechnology (2024). DOI
• Y. del Castillo, A. Ferron, and J. Fernandez-Rossier, Remote spin control in Haldane spin chains, arXiv:2508.21544 (2025). arXiv, DOI
• A. N. Tikhonov and V. Y. Arsenin, Solutions of Ill-Posed Problems, Wiley (1977).

Citation

Software citation metadata is available in CITATION.cff.