docs/USAGE.md

# Usage guide

## Install

The interactive application includes all optional runtime dependencies:

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

For the library and command-line inspector only:

```bash
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:

```text
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:

```text
posfiletype D
```

```text
# 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:

```text
# 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:

```text
# 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

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

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

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

## Python workflow

```python
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:

```python
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.