# GURU — `guru-iso-fit` Manual (EN)

**Purpose.** From thermo TSVs (typically produced by `guru-thermo`) or from a rectangular EOS grid, construct curves and evaluate or reconstruct:
- **isotherm** (const `T`) and **isochor** (const `ρ`) — polynomial fit over points, or interpolation over grid;
- **isobar** (const `P`) — reconstructed path `(T,ρ,E)` from points (bivariate smoothing splines) or from grid (interpolation).

---

## Synopsis
```bash
# Points (TSV-rich/compact) — isotherm/isochor
guru-iso-fit --mode {isotherm|isochor} --degree {1,2,3} \
             --pressure P* -i file1.tsv [file2.tsv ...] \
             -o state.tsv [--tol-T dT] [--tol-rho dRho] [--on-outliers {ignore,fail}] \
             [--plot] [--plot-prefix PREFIX]

# Points — isobar reconstruction (per-curve PCHIP)
guru-iso-fit --mode isobar --pressure P* \
             -i file1.tsv [file2.tsv ...] -o isobar.tsv [--isobar-n 400] \
             [--isobar-allow-extrap] [--isobar-fit-out isobar_fit.tsv] [--isobar-fit-n 200]

# Grid EOS — if --mode is omitted:
#   --grid-T => isotherm,  --grid-rho => isochor,  otherwise isobar
guru-iso-fit --grid-eos EOS.tsv --pressure P* \
             [--grid-T T0 | --grid-rho R0] [-o out.tsv] [--grid-n 400] [--extrap-frac 0.1] \
             [--plot] [--plot-prefix PREFIX]
```

**Inputs**
- One or more TSV files, **compact** (`T\tP\tE`) or **rich** (`*_mean` columns). Density `ρ` is taken from rich TSV if present.
- Rectangular EOS grid TSV (`T`, `rho`, `P`, `E/E_atom`) for grid mode.

**Key behavior**
- The script **determines representative T or ρ automatically** from the data (mean) and checks uniformity within `--tol`.
  - Default `--tol` **10 K** (isotherm) and **0.01 g/cm³** (isochor).
  - If points outside tolerance exist: with `--on-outliers ignore` they are dropped; with `fail` the script prints a clean message and exits.
- **Energy per atom** (`E_atom` / `E_atom_mean`) is used when present; otherwise `E` is treated as per-atom.

**Fitting/Interpolation**
- Isotherm: fit `E(V)` and `P(V)` vs `V = 1/ρ` with polynomial degree 1–3. Evaluate `E(V*)` at `P(V*) = P*`.
- Isochor : fit `E(T)` and `P(T)` vs `T`. Evaluate `E(T*)` at `P(T*) = P*`.
- Extrapolation is allowed but **flagged** in the output comment.

**Isobar**
- Points: group input rows into approximate isotherms (by `T` within `--tol`) and isochors (by `ρ` within `--tol`), fit PCHIP on each curve and solve `P=P*` along the curve (bracketing + `brentq`). If `--isobar-allow-extrap` is set, guarded extrapolation is attempted and such points are marked. Negative‑T extrapolated solutions are forbidden.
- Grid: use shape-preserving interpolators; for each scanned `T`, bracket the root on `ρ` grid nodes, then `brentq` to `ρ(T)`. If the base grid is non‑negative in `T`/`ρ`, lower bounds are kept ≥ 0.

**Outputs**
- For **isotherm**: one line TSV with columns `T  P  E  V  rho  mode  degree`.
- For **isochor**: one line TSV with columns `rho  P  E  T  mode  degree`.
- For **isobar** : multi-line TSV with columns `T  rho  P  E` (path points).
- With `--plot`, PNGs are produced:
  - Isotherm: **P–ρ** and **E–ρ** (data points + fitted curve, evaluated point marked).
  - Isochor : **P–T** and **E–T** (same conventions).
  - Isobar  : **T–ρ** and **E–T** along the isobar (line for grid, points/line for samples).
  - Grid extras: for grid isotherm/isochor, dedicated plots are also saved with marked target points.

**Progress**
- `--progress` / `--no-progress` toggle progress reporting on stderr. In grid mode you will see separate bars for isotherm/isochor/isobar scans; in points‑mode isobar progress is per curve.

---

## Examples
Evaluate `P=0` along an isochor assembled from two files:
```bash
guru-iso-fit --mode isochor --degree 2 --pressure 0 \
  -i rho15.tsv rho15_part2.tsv -o init_rho15.tsv --plot
```
Isotherm at ~300 K (auto-detected) with cubic polynomial:
```bash
guru-iso-fit --mode isotherm --degree 3 --pressure 200 \
  -i T300.tsv -o init_T300.tsv --plot --plot-prefix plots/T300
```

---

## Troubleshooting
- **Non-uniform data**: check `--tol`; ensure inputs correspond to the same isotherm/isochor; use `--on-outliers ignore` to drop mis-tagged rows.
- **Extrapolation**: the requested pressure lies outside the fitted range; consider adding more points.
- **No isobar points**: requested `P*` may not be attainable in the scanned range; widen bounds or use grid mode.
- **Negative temperatures**: when extrapolating from samples in isobar mode, negative‑T solutions are forbidden by design.

---

## Notes on units
- `P` in kbar, `T` in K, `E` in eV/atom, `ρ` in g/cm³ (consistent with `guru-thermo` outputs).