Tanabe–Sugano calculator for 3d transition-metal ions

Four canonical Jupyter notebooks and a Python package (tanabe_sugano/) that build publication-quality Tanabe–Sugano diagrams for an arbitrary 3d ion in cubic symmetry, with edrixs as the atomic-data and many-body operator backend:

Notebook	What it computes
notebooks/SingleIon_TanabeSugano.ipynb	Pure single-ion ED on the d-shell (V = 0, no bath). Direct diagonalisation of the 252-state d⁵ subspace gives the canonical atomic Tanabe–Sugano with explicit ⟨S²⟩, ⟨L²⟩ labels and the high-spin → low-spin crossover.
notebooks/SIAM_TanabeSugano.ipynb	Full Single-Impurity Anderson Model with a charge-transfer bath. Sₓ-blocked exact diagonalisation of the 15 504-state Fock space yields true eigenvectors and total ⟨S²⟩ per state. Includes separate cells for sweeping 10Dq, V_eg, or Δ.
notebooks/TS_Progression.ipynb	Atomic → +Δ → +V_eg three-panel progression that disentangles the contributions of the charge-transfer energy and the hybridisation. Panels (a) and (b) cross-validate each other (V = 0 ⇒ d-character SIAM states sit at the atomic energies exactly); panel (c) shows the CT-renormalised SIAM.
notebooks/SIAM_with_Experiment.ipynb	Zoomed SIAM ladder with experimental dd peaks drawn as horizontal FWHM bands. Reads your dd-fit CSV, runs a SIAM 10Dq sweep over the dd-excitation window, and overlays both — direct visual check of which theory states fall inside each experimental linewidth.

Both notebooks live in notebooks/ and produce CSVs in csv_data/ plus PDF/PNG figures in figures/ (relative to wherever you launch Jupyter). Every output gets tagged with the input parameters so different runs don't overwrite each other.

The intended user is a working spectroscopist or solid-state theorist who wants to scan parameter space and connect a measured dd-excitation ladder to a quantitative model — either the bare atomic spectrum (for sanity-checking) or the CT-renormalised SIAM (for materials with significant ligand hybridisation, e.g. α-MnTe at the Mn L-edge).

A parallel set of Cr³⁺ worked examples (single-ion, SIAM, three-panel progression, and CAPS/CCPS experiment overlays) lives in notebooks_Cr3/, with their CSV and figure outputs alongside.

---

Quickstart

Python API (5 lines)

import numpy as np
from tanabe_sugano import load_params, solve_siam, ts_4panel_plot

params = load_params('params/bo_champion.json')
df = solve_siam(params, dq_grid=np.linspace(0, 4, 50))
fig = ts_4panel_plot(df, params, savepath='figures/my_run')

Parameter sets are stored as JSON files in params/. The load_params function accepts either a file path or a plain dict — you can also build parameters inline:

from tanabe_sugano import load_params, solve_atomic_d5
params = load_params({'ION': 'Mn', 'NELEC_D': 5, 'KAPPA_DD': 0.7,
                      'U_DD': 7.18, 'ZETA_3D': None})
df = solve_atomic_d5(params, dq_grid=np.linspace(0, 3, 40))

Notebooks

# Activate an environment that has edrixs, scipy, pandas, matplotlib
conda activate edrixs_run    # or your equivalent

# From the package root:
jupyter lab notebooks/SingleIon_TanabeSugano.ipynb
# or
jupyter lab notebooks/SIAM_TanabeSugano.ipynb

In each notebook the only cell you need to touch is § 1 Inputs. Run all cells (Run → Run All Cells) and the figures + CSVs are written to disk under tags built from the parameter choice.

Requirements are in requirements.txt; installation notes in docs/installation.md.

---

Conventions

Basis: complex-harmonic Fock space (EG_CPLX / T2G_CPLX)

All single-particle operators — the crystal field (CF), spin-orbit coupling (SOC), hybridisation, and the S²/L² diagnostics — are constructed in the complex-spherical-harmonic Fock basis produced by edrixs get_fock_bin_by_N. Orbital indices within the 10-state d-shell are:

index  0  1  2  3  4  5  6  7  8  9
m_l   -2 -2 -1 -1  0  0 +1 +1 +2 +2
spin   ↑  ↓  ↑  ↓  ↑  ↓  ↑  ↓  ↑  ↓

In Oh cubic symmetry the symmetry-adapted subsets are:

• e_g (EG_CPLX): m = ±2 → indices [0, 1, 8, 9]
• t₂g (T2G_CPLX): m = -1, 0, +1 → indices [2, 3, 4, 5, 6, 7]

These are exported as tanabe_sugano.EG_CPLX and tanabe_sugano.T2G_CPLX.

Critical for forkers: edrixs cf_cubic_d and atom_hsoc both output matrices in this complex-harmonic basis — no cb_op rotation should be applied before assembling the many-body Hamiltonian. A previous basis-mismatch bug (rotating CF/SOC into the real-cubic basis before passing to build_opers) shifted the ⁴T₁(G) energy by ~197 meV and is now documented in CHANGELOG.md.

---

Tests

cd TanabeSugano
conda activate edrixs_run
pytest tests/ -v

The suite (13 tests) covers:

• Atomic d⁵ spectrum vs exact-diagonalisation reference values
• Linear κ-scaling of term energies
• V = 0 SIAM fast-path equals atomic d⁵ exactly
• Per-state observable checks (S², L², multiplicity)
• Regression tests for the basis-mismatch fix (pre-fix: 2243 meV, post-fix: 2440 meV for ⁴T₁(G) at ten_dq = 0.5 eV, κ = 0.7)

The slow SIAM tests (~75 s) run build_static_caches + ARPACK; the fast tests (atomic-limit only) take ~10 s.

---

Adding a new candidate

1. Create params/my_candidate.json following the schema in any existing file. The _metadata block is optional but recommended.
2. Load and validate: load_params('params/my_candidate.json') — raises ValueError if required keys are missing.
3. Run the standard sweep:

   params = load_params('params/my_candidate.json')
   df = solve_siam(params, dq_grid=np.linspace(0, 4, 50))
   fig = ts_4panel_plot(df, params)

Required keys for single-ion (no bath): ION, NELEC_D, KAPPA_DD, U_DD, ZETA_3D. Add NBATH_ORB, DELTA, VEG for SIAM mode. See docs/parameters.md for units and ranges.

---

Example outputs

Single-ion d⁵ Tanabe–Sugano (Mn²⁺, κ_dd = 0.70)

Four panels: full ladder E vs 10Dq, dimensionless E/B vs 10Dq/B, ground-state ⟨S⟩ (the HS→LS step at 10Dq/B ≈ 24), and the term spectrum at the fitted 10Dq. Spin coloured from ⟨S²⟩ of each eigenvector.

Full SIAM Tanabe–Sugano (α-MnTe best-fit, V_eg = 1.25 eV, Δ = 3.20 eV)

Same four panels as the single-ion notebook, but every state is now an eigenvector of the full (impurity + bath + CT mixing) Hamiltonian. The GS-spin step has moved to 10Dq* ≈ 1.84 eV (10Dq/B ≈ 19) — the SIAM HS→LS crossover is earlier than the single-ion one because charge transfer stabilises the LS configuration.

V_eg sweep at fixed 10Dq — the CT mixing bridge

V_eg = 0 reproduces the single-ion result; turning on V_eg up to the fit value pulls the lowest quartet ladder down through the experimental peaks and grows GS n_d from 5.00 to 5.23 (d⁵ ↔ d⁶L̄ admixture).

Δ sweep at fixed 10Dq, V_eg

GS n_d slides monotonically from 5.36 (Δ = 1 eV, strong CT) to 5.10 (Δ = 5 eV, near-atomic). GS stays HS throughout this parameter range.

Atomic → +Δ → +V_eg three-panel progression

Why this matters: setting V_eg = 0 in the SIAM is not the atomic limit — it's "d-shell + bath, decoupled", and the bath contributes eigenvalues at ±Δ that have no analogue in the single-ion calculation. Panel (b) shows the d-character branches (solid) sitting exactly on the pure-atomic energies of panel (a), while bath-character bands (dashed) appear at ±Δ. Turning V_eg on (panel c) hybridises everything; the lowest "⁴T₁(G)-like" multiplet drops from ~2.5 eV (a, b) to ~1.7 eV (c), matching the experimental E₁ = 1.78 eV. See docs/atomic_limit_caveat.md for the full discussion.

SIAM ladder with experimental dd peaks + exciton (FWHM bands)

Zoom of the full SIAM Tanabe-Sugano (panel c of the progression) restricted to the dd-excitation window. Each pastel band is one experimentally measured feature from the MnTe/GaAs Voigt fits: the horizontal extent is the angle-averaged FWHM, the bold line is the central energy.

Feature	Centre	FWHM	Best d-dominant SIAM match	S
Ex. (CT exciton)	1.81 eV	245 meV	1.79 eV (⁴T₁(G)-like)	1.50
dd₁	2.10 eV	245 meV	2.13 eV	1.50
dd₂	2.41 eV	257 meV	2.43 eV	1.50
dd₃ₐ	2.68 eV	300 meV	2.68 eV	1.50
dd₃ᵦ	2.97 eV	300 meV	2.95 eV	1.49
dd₄	3.33 eV	422 meV	3.40 eV	0.53
dd₅	3.75 eV	383 meV	3.78 eV	0.50

Two physics points to flag: (i) the lowest "⁴T₁(G)-like" quartet in the SIAM lands inside the exciton band, not the dd₁ band — worth checking whether the previous E₁ assignment was conflating the two features; (ii) dd₄ and dd₅ are matched by doublet (S = 1/2) states in this SIAM, not quartets — a non-trivial assignment that the RIXS angular dependence may be able to discriminate.

---

Documentation

Document	Read this when…
docs/methodology.md	…you want the physics and math behind the code: the Hamiltonian, the S²-from-eigenvectors trick, the Sz-block decomposition, the threading scheme.
docs/usage_guide.md	…you're running the notebook for the first time, debugging a parameter combination, or porting to a different ion. Walk-through of every cell.
docs/parameters.md	…you need a glossary of all input variables, units, and physically reasonable ranges.
docs/outputs.md	…you want to know what every column of the CSVs means and how the figures are laid out.
docs/installation.md	…Python environment, edrixs install, MPI requirements.
docs/atomic_limit_caveat.md	…what "atomic limit" means in the SIAM context; how to identify d-character vs ligand-character eigenstates; why V_eg = 0 is not the same as the single-ion notebook.
docs/SIAM_model.tex / .pdf	…LaTeX reference document for talks: full Hamiltonian, parameter glossary table with α-MnTe values, ⟨S²⟩-from-eigenvectors derivation, numerical scheme.

---

Citation

These notebooks build on the edrixs library (Y. Wang, G. Fabbris, M. P. M. Dean, Comput. Phys. Commun. 243, 151 (2019), doi:10.1016/j.cpc.2019.04.018). If you use the SIAM machinery please also cite the fedrixs Fortran backend even though here we use the Python-side direct ED.

The methodology — direct ED with explicit ⟨S²⟩ from $|\hat S_-|\psi\rangle|^2 + S_z(S_z-1)$, Sz-blocked Fock basis, and per-state DM diagnostics — is standard material in any many-body textbook; the implementation here is original to this package.

If these notebooks help your paper, please cite this repository and the edrixs paper above. A CITATION.cff is included.

---

Licence

MIT — see LICENSE. edrixs is BSD-3.