SPRKKR Magnon Workflow

TB2J can read the SPRKKR RuO2 reference format and convert it into the existing SpinIO -> Magnon.load_from_io() workflow. The first supported input contract is the file set used in Refs/SPRKKR_RuO2: RuO2.str, RuO2_JXC_Jij.dat, and the full-table variant RuO2_JXC_XCPLTEN_Jij.dat for parsing/filtering checks.

The MVP does not require shells.dat, Jijatom.*, potential files, or shape function sidecars. The exchange table columns are interpreted as IT IQ JT JQ N1 N2 N3 DRX DRY DRZ DR J_xx J_yy J_xy J_yx; DRX, DRY, DRZ, and DR are Cartesian quantities in units of the SPRKKR lattice parameter A. Exchange values are read in meV and converted to the eV convention used by the TB2J magnon path.

The reference README states the LKAG convention with prefactor c = 1, unit spin direction vectors, and Ru moment 0.5674 mu_B. Pass the moment explicitly so the magnon normalization is visible in scripts and command lines.

Python API

from TB2J.interfaces import (
    magnon_from_sprkkr,
    read_sprkkr_exchange,
    write_sprkkr_tb2j_results,
)

data = read_sprkkr_exchange(
    structure_file="Refs/SPRKKR_RuO2/RuO2.str",
    exchange_file="Refs/SPRKKR_RuO2/RuO2_JXC_Jij.dat",
    magnetic_species=["Ru"],
    moment=[0.5674, -0.5674],
)

magnon = magnon_from_sprkkr(
    structure_file="Refs/SPRKKR_RuO2/RuO2.str",
    exchange_file="Refs/SPRKKR_RuO2/RuO2_JXC_Jij.dat",
    magnetic_species=["Ru"],
    moment=[0.5674, -0.5674],
    tensor_policy="isotropic",
)

spinio = write_sprkkr_tb2j_results(
    structure_file="Refs/SPRKKR_RuO2/RuO2.str",
    exchange_file="Refs/SPRKKR_RuO2/RuO2_JXC_Jij.dat",
    output_path="TB2J_results",
    magnetic_species=["Ru"],
    moment=[0.5674, -0.5674],
)

labels, bands, xcoords = magnon.get_magnon_bands(path="GX", npoints=20)

write_sprkkr_tb2j_results() converts SPRKKR inputs into SpinIO, writes a full TB2J result directory including TB2J.pickle, exchange.out, structure.vasp, and Multibinit/exchange.xml, and returns the in-memory SpinIO for immediate use or further inspection. A complete runnable example is available at examples/magnon/sprkkr_ruo2_tb2j_results.py.

moment can be a single scalar, which is broadcast to all selected magnetic sites, N signed scalar values for N selected magnetic sites, or 3N values for explicit moment vectors. Scalar values are placed along the z direction. Values follow the selected SPRKKR magnetic site order. For two Ru sites, use moment=[0.5674, -0.5674]; the equivalent explicit-vector form is moment=[0, 0, 0.5674, 0, 0, -0.5674].

Use tensor_policy="transverse-block" to place J_xx, J_yy, J_xy, and J_yx into the transverse block of a 3x3 tensor with unavailable z-couplings set to zero. Use tensor_policy="isotropic" to use (J_xx + J_yy) / 2 as the scalar exchange. Use tensor_policy="transverse-block-jzz" to keep the transverse block and set J_zz = (J_xx + J_yy) / 2; all other unavailable entries remain zero. Requests for a full tensor are rejected because the reference files do not contain all tensor components.

CLI

sprkkr2magnon.py \
  -s Refs/SPRKKR_RuO2/RuO2.str \
  -e Refs/SPRKKR_RuO2/RuO2_JXC_Jij.dat \
  -S Ru \
  -m 0.5674 -0.5674 \
  -t isotropic \
  -b \
  -k GX \
  -n 20 \
  --qpoints "G:0,0,0,X:0.5,0,0" \
  -o ruo2_sprkkr_magnon.png

The short aliases above are equivalent to --structure, --exchange, --magnetic-species, --moment, --tensor-policy, --bands, --kpath, --npoints, and --output.

Use --qpoints to override high-symmetry point coordinates with the same name:x,y,z comma-separated format as TB2J_magnon.py.

The command writes the plot path and a matching JSON file with the same stem. To write a full TB2J-compatible result directory for later reuse, use:

sprkkr2magnon.py \
  -s Refs/SPRKKR_RuO2/RuO2.str \
  -e Refs/SPRKKR_RuO2/RuO2_JXC_Jij.dat \
  -S Ru \
  -m 0.5674 -0.5674 \
  -w TB2J_sprkkr_results