docs/USAGE.md

Usage guide

Install

The interactive application includes all optional runtime dependencies:

python -m pip install -r requirements.txt
python app.py

For the library and command-line inspector only:

python -m pip install -e .
python -m pip install -e '.[symmetry,paths]'

The second command adds spglib for symmetry expansion and seekpath for standard high-symmetry paths. Run tests with PYTHONPATH=src pytest -q.

Prepare an UppASD input set

The loader uses the literal UppASD ordered-pair convention H = -sum_(i != j) Jij e_i·e_j. Do not halve or double values from a pair-complete jfile. Conversion helpers for other Hamiltonian conventions are available as convert_exchange_to_uppasd at the Python API boundary.

The loader starts from inpsd.dat, which must name the position, moment, and exchange files and provide the cell for reciprocal-space work:

simid     FePtFM25
ncell     12 12 12
BC        P P P
cell      1.0 0.0 0.0
          0.5 0.5 0.0
          0.0 0.0 0.9525
alat      2.87e-10
posfile   ./posfile
exchange  ./jfile
momfile   ./momfile

Paths are resolved relative to inpsd.dat. Canonical UppASD keywords are posfile, momfile, and exchange; positions, moments, and jfile are accepted as fallback aliases.

posfile stores a basis-site number, atom type, and position. By default the three position values are Cartesian (posfiletype C). With posfiletype D, they are direct/fractional coordinates and are converted using the cell:

posfiletype D

# site atom_type x y z
1 1 0.0 0.0 0.0

The jfile vector convention is selected with maptype (default 1):

• maptype 1: the vector is already a bond vector; it is Cartesian for posfiletype C and direct/fractional for posfiletype D.
• maptype 2: the vector contains lattice-translation coefficients and the folded basis-position difference is added.
• maptype 3: the vector contains lattice-translation coefficients and the raw, pre-folded basis-position difference is added.

For maptypes 2 and 3, ncell N1 N2 N3 and BC P/F P/F P/F optionally enable periodic offset reduction or free-boundary range checks. Cell vectors are rows and all mapped exchange vectors are stored as Cartesian vectors internally.

The input readers consume the required leading fields and ignore trailing columns or text. This applies to recognized inpsd.dat records, posfile, momfile, and jfile rows. inpsd.dat keywords not used by this package are also silently ignored, so a deck may retain settings intended for other UppASD executables.

momfile stores the reference moment in mu_B, optionally followed by a spin direction:

# site moment_field moment [sx sy sz]
1 1 2.9913824 0.0 0.0 1.0

The atom type in posfile identifies species for symmetry handling. The second momfile field is UppASD metadata, not a species identifier.

The exchange file stores scalar isotropic exchange:

# i j rx ry rz Jij [distance]
1 1 0.5 0.5 0.0 12.5 0.70710678

The displacement is used exactly as supplied. The optional distance is checked only as a diagnostic.

Use the web application

1. Run python app.py and open the local address printed by Gradio.
2. In Input, choose a bundled example or upload inpsd.dat plus its referenced files. Browser uploads are matched by basename; inspect and correct the mapping if needed.
3. Confirm the input energy unit. Choose symmetry-reduced only when the exchange file contains orbit representatives rather than all neighbours.
4. Review the proposed robust/induced sites and change them to match your physical model. The moment-size suggestion is not a physical conclusion.
5. Run the analysis. The tabs show raw exchange, induced response, dressed exchange, and FM magnon diagnostics; all successful-analysis data can be downloaded from the application.

Warnings are part of the result. In particular, address unresolved files, asymmetric reciprocal bonds, ill-conditioned induced response, and a path-restricted ordering candidate before drawing physical conclusions.

Inspect input on the command line

induced-exchange-uppasd examples/fept_style/inpsd.dat

Specify units or expand a symmetry-reduced exchange file explicitly:

induced-exchange-uppasd examples/uppasd_style/inpsd.dat \
  --energy-unit meV --expand-symmetry

Python workflow

from induced_exchange import (
    InducedExchangeDownfolding,
    InducedMomentResponse,
    exchange_eigensystem,
    fm_magnon_spectrum,
    high_symmetry_path,
    load_uppasd,
)

loaded = load_uppasd("examples/fept_style/inpsd.dat", energy_unit="mRy")
model = loaded.model

path = high_symmetry_path(model, n_per_segment=16)
raw = exchange_eigensystem(model, path.q_fractional, coordinates="fractional")

response = InducedMomentResponse(
    model,
    robust_sites=[1],
    induced_sites=[2],
    mode="j_weighted",
    x={2: 0.12},  # or leave unset and inspect response.infer_x()
)
downfolded = InducedExchangeDownfolding(response).evaluate(
    path.q_fractional, coordinates="fractional"
)
magnons = fm_magnon_spectrum(
    downfolded,
    model="mryasov",
    moment_magnitudes=[model.site_by_index[1].moment],
    input_energy_unit=model.units.energy,
)

Use real site indices from the input, not zero-based array offsets. Read the warnings and conditioning fields on returned objects. For a complete ordering search, replace the path with regular_q_mesh(model, (16, 16, 16), coordinates="fractional").

Compare datasets

To compare two exchange models sharing the same structure:

from induced_exchange import ExchangeDataset, compare_exchange_datasets

a = ExchangeDataset(model_a, label="dataset A", robust_sites=[1], induced_sites=[2], x=0.12)
b = ExchangeDataset(model_b, label="dataset B", robust_sites=[1], induced_sites=[2], x=0.12)
result = compare_exchange_datasets(a, b, path.q_fractional, include_magnons=True)
result.export("results", prefix="a_vs_b")

Compatibility checks deliberately distinguish incompatible geometry/site layouts from expected differences in exchange values. The comparison is a diagnostic; it does not assign causal blame to either input dataset.