Import and calibrate XXZ couplings from spinq-vqe (cross-repo Hamiltonian link)

[rosspeili]

Context

The program narrative ties spintronic-qrc to spinq-vqe: the Kagome AFM Hamiltonian calibrated for Mn3Sn in Repo 1 should inform the 1D XXZ reservoir in Repo 2. reservoir.py docstring already states this intent; docs/notebooks.md mentions optional import in Notebook 01.

Constraint: pyproject.toml deliberately does not list spinq-vqe as a core dependency (no NetworkX, QuSpin, etc. copied from Repo 1). Calibration must work as:

• Path A (preferred): Pure constants / mapping function with documented Mn3Sn values (no import required)
• Path B (optional): If spinq-vqe is installed in the same venv, read J_MN3SN_MEV and D_MN3SN_MEV directly from spinq_vqe.kagome

Default behavior when spinq-vqe is absent: fall back to current J_xy=1, J_z=1, W=0.5.

Physics mapping (document in module docstring)

spinq-vqe Kagome Heisenberg AFM (kagome.py):

H_Kagome = J SUM S_i . S_j + D SUM (S_i^z)^2 + ...

spintronic-qrc open XXZ chain:

H_chain = J_xy SUM (XX + YY) + J_z SUM ZZ + disorder

Mapping for 1D strip / effective chain calibration:

spinq-vqe constant	spintronic-qrc parameter	Rule
J_MN3SN_MEV (4.0 meV)	J_xy, J_z scale	Set J_xy = J_z = 1.0 in dimensionless units; optional scale factor J_eff from kagome J_eff normalization
D_MN3SN_MEV (0.3 meV)	J_z / J_xy anisotropy	J_z = J_xy * (1 + D/J) or J_z = J_xy + anisotropy correction
VQE-validated energy scale	Optional rescale	Document only; no live VQE call in QRC

Keep the mapping simple and explicit — this is calibration metadata, not a second VQE run. Cite Nakatsuji (2022) and spinq-vqe README.

Goal

Add src/spintronic_qrc/calibration.py (or extend reservoir.py if small) that exposes:

@dataclass(frozen=True)
class CalibratedCouplings:
    J_xy: float
    J_z: float
    disorder: float
    source: str  # e.g. "default", "mn3sn_literature", "spinq-vqe-import"
    notes: str = ""

def mn3sn_couplings_from_literature() -> CalibratedCouplings: ...

def mn3sn_couplings_from_spinq_vqe() -> CalibratedCouplings: ...

def get_calibrated_couplings(
    source: Literal["default", "literature", "spinq-vqe"] = "default",
) -> CalibratedCouplings: ...

And a helper to build QRCConfig / ReservoirConfig from calibrated values:

def reservoir_config_from_couplings(
    couplings: CalibratedCouplings,
    n_sites: int = 6,
    seed: int | None = 42,
) -> ReservoirConfig: ...

Requirements

1. Literature-based calibration (always available)

Implement mn3sn_couplings_from_literature() using constants aligned with spinq-vqe/kagome.py:

• J = 4.0 meV -> dimensionless J_xy = 1.0, J_z derived from D/J ratio (D = 0.3 meV -> J_z/J_xy = 1 + D/J or equivalent documented formula)
• disorder W: keep default 0.5 unless literature justification added in notes field
• source = "mn3sn_literature"

2. Optional spinq-vqe import

def mn3sn_couplings_from_spinq_vqe() -> CalibratedCouplings:
    try:
        from spinq_vqe.kagome import J_MN3SN_MEV, D_MN3SN_MEV
    except ImportError as exc:
        raise ImportError(
            "spinq-vqe not installed. Use source='literature' or pip install spinq-vqe."
        ) from exc
    # map to J_xy, J_z

Do not add spinq-vqe to core dependencies. Optional: document in README that program workspace may have both repos editable-installed.

3. Integration points

• reservoir.py: optional use_calibrated=True flag on xxz_chain_hamiltonian OR separate factory function build_mn3sn_hamiltonian(n_sites, source=...)
• docs/notebooks.md: update Kagome parameters section with calibration API example
• docs/api.md: calibration section
• notebooks/01_xxz_dynamics.ipynb: add one optional cell (or markdown + short code) showing literature vs default couplings — only if NB01 already exists; otherwise document for NB01 author

4. Tests — tests/test_calibration.py

Test	Verifies
test_literature_couplings_finite	J_xy, J_z > 0
test_default_matches_reservoir_defaults	get_calibrated_couplings("default") consistent with J_XY_DEFAULT, J_Z_DEFAULT
test_literature_jz_anisotropy	J_z != J_xy when D > 0
test_spinq_vqe_import_skip	pytest.importorskip or mock: if spinq-vqe absent, get_calibrated_couplings("spinq-vqe") raises clear ImportError
test_reservoir_config_from_couplings	Builds valid ReservoirConfig, Hamiltonian has terms

5. Do not

• Add spinq-vqe to pyproject.toml core or required dependencies
• Call VQE or load notebook outputs at runtime
• Pull NetworkX / Kagome graph into QRC package

Acceptance criteria

• calibration.py with literature path and optional spinq-vqe import path
• get_calibrated_couplings() unified API with source switch
• tests/test_calibration.py >= 4 tests passing without spinq-vqe installed
• docs/api.md and docs/notebooks.md updated
• reservoir.py docstring cross-links calibration module
• CHANGELOG [Unreleased] one-line entry (optional, small)

Files likely touched

• src/spintronic_qrc/calibration.py (new)
• tests/test_calibration.py (new)
• docs/api.md
• docs/notebooks.md
• src/spintronic_qrc/reservoir.py (minor cross-link or factory helper)
• notebooks/01_xxz_dynamics.ipynb (optional small cell)

References

• spinq-vqe src/spinq_vqe/kagome.py — J_MN3SN_MEV, D_MN3SN_MEV
• Nakatsuji & Ishizuka (2022) Ann. Phys. 447 (REFERENCES.md P10)
• Program README cross-repo dependency: spinq-vqe -> spintronic-qrc Hamiltonian parameters

Depends on

• Issue Implement end-to-end QRC pipeline (ApproxTimeEvolution + feature matrix builder) #1 (ReservoirConfig / QRCConfig) — recommended
• spinq-vqe repo available in workspace for manual verification — not a CI dependency

Blocks

• Cross-repo narrative in OVERVIEW and program README
• Notebook 01 optional Mn3Sn-calibrated dynamics figure
• Paper methods section linking QRC reservoir to Mn3Sn exchange parameters

[rosspeili]

Amendment — cross-repo documentation and citation

Issue scope is correct for code. Add these deliverables so the spinq-vqe link is explicit and self-contained for new contributors:

1. Cross-repo mapping table

Add to docs/notebooks.md (or a short docs/cross_repo.md linked from docs/README.md):

spinq-vqe artifact	Used in spintronic-qrc	Required install
spinq_vqe.kagome.J_MN3SN_MEV	calibration.mn3sn_couplings_from_spinq_vqe() → J_xy	optional pip install -e ../spinq-vqe
spinq_vqe.kagome.D_MN3SN_MEV	J_z / J_xy anisotropy ratio	optional
data/vqe_results.csv	Not loaded at runtime — reference only for paper narrative	—
OVERVIEW.md validated VQE errors	Cited in QRC paper Methods, not pipeline input	—

2. CITATION.cff

Add a relatedResources entry (or remarks field) pointing to:

https://github.com/ARPAQLS/spinq-vqe

with text: companion repo providing Mn₃Sn Kagome Hamiltonian calibration.

3. README one-liner

In spintronic-qrc README.md Install or Docs section:

Optional: pip install -e "../spinq-vqe" for live import of kagome constants (see docs/notebooks.md).

Do not add spinq-vqe to pyproject.toml core dependencies.

Acceptance criteria additions:

• Cross-repo table in docs
• CITATION.cff mentions spinq-vqe as related software