# GURU — Isentrope (guru-isentrope)

Compute an isentropic path T(ρ) from an EOS grid P(T,ρ), E(T,ρ) and mass velocity u(P) via Riemann relations. Supports rectangular grids (exact splines) and quasi-grids (smoothing splines).

## Units and conventions

- Temperature T: K
- Density ρ: g/cm^3
- Pressure P: kbar
- Energy E: eV/atom (per atom)
- Mass velocity u: km/s
- Molar mass Ma: g/mol

## Physics and formulas

Isentropic slope in T–ρ space (per mass specific heat):

    dT/dρ |_S = (T / ρ^2) * ( (∂P/∂T)|_ρ / c_v ),
    c_v = (∂E/∂T)|_ρ · (eV→J) / m_atom,
    m_atom = Ma / N_A / 1000 (kg/atom).

Implementation uses explicit unit conversions:

- (∂P/∂T) in kbar/K is converted to Pa/K with 1 kbar = 1e8 Pa.
- c_v is computed from (∂E/∂T) in eV/atom/K to J/(kg·K).
- The result dT/dρ is returned in K per (g/cm^3).

Riemann integral for mass velocity along an isentropic release:

    du = ± ∫ dp / (ρ c) = ± ∫ (1/ρ) sqrt(∂ρ/∂p)|_S dp,

in the tool we use a practical form:

    u(P) = u0 + ∫ (1/ρ) √(max(dρ/dP, 0)) dP / √10,  with P in kbar and ρ in g/cm^3.

The √10 factor comes from 1 kbar = 1e8 Pa and unit consistency.

## Numerics

- Splines:
  - Rectangular grid: RectBivariateSpline for P(T,ρ) and E(T,ρ), exact (s=0).
  - Quasi-grid: SmoothBivariateSpline for scattered (T,ρ) points with smoothing `s ≥ 0`.
- Integration: two-stage explicit scheme (Heun/Euler–Cauchy) with parameter a=0.5 on uniform ρ steps `drho` (can be <0 for release).
- Pressure and energy are sampled from the chosen splines along the integrated path.
- Extrapolation control: integration may continue outside the base grid up to ±`extrap-frac` of the min/max T and ρ; beyond that the run stops with a message.
- Optional stop by pressure `--stop-P-le`: terminate when P ≤ threshold.

## CLI

```
guru-isentrope \
  -i EOS.tsv [EOS2.tsv ...] \
  --Ma <g/mol> \
  --T0 <K> --rho0 <g/cm^3> --drho <g/cm^3> --nmax <N> \
  -o isentrope.tsv [--out-velocity pu.tsv] [--diag-out diag.tsv]
```

Key options:

- Input and grid:
  - `-i/--input`: one or more TSV files. Accepts compact or rich TSVs. Column names are matched case-insensitively with synonyms: `T/T_mean`, `P/P_mean`, `E_atom/E_atom_mean/E/E_mean`, `rho/density_g_cm3/d`.
  - `--grid-mode {rect,quasi}`: rectangular exact splines (default) or smoothing splines over scattered points.
  - `--smooth-s <float>`: smoothing factor for quasi mode (0 = interpolation).
- Initial state and stepping:
  - `--T0`, `--rho0`, `--drho` (negative for release), `--nmax` steps.
  - `--extrap-frac <frac>`: allow extrapolation beyond grid bounds by this fraction (default 0.10 = 10%).
  - `--stop-P-le <kbar>`: stop when P ≤ threshold.
- Outputs:
  - `-o/--out`: isentrope TSV with columns `T  rho  P  E_atom`.
  - `--out-velocity`: mass velocity TSV `P[kbar]  u[km/s]`.
  - `--u0 <km/s>`: initial mass velocity.
  - `--vel-mode {path,grid}`: compute u(P) at path points or on a uniform P-grid.
  - `--vel-dp <kbar>`, `--vel-Pmin <kbar>`: P-grid step and stop for grid mode.
  - `--diag-out`: diagnostics TSV with `T  rho  P  c[km/s]  rho_c`.
  - Plots: `--plot` saves PNG figures; `--plot-prefix` sets filename prefix.
    - Saved plots:
      - `<prefix>_P_rho.png` — P vs rho
      - `<prefix>_P_T.png` — P vs T
      - `<prefix>_T_rho.png` — T vs rho
      - `<prefix>_P_u.png` — P vs u (only if `--out-velocity` was computed)
- QoL:
  - `--progress/--no-progress`: progress bar.
  - `--no-log`: disable appending the CLI invocation to `guru.log` near outputs.

## Examples

Rectangular grid, release, stop at P≤0, diagnostics and u(P) at path points:

```
guru-isentrope -i N2_rect.tsv --Ma 28 \
  --T0 300 --rho0 0.8 --drho -0.01 --nmax 600 \
  --stop-P-le 0 --extrap-frac 0.1 \
  -o iso.tsv --out-velocity pu.tsv --u0 1.0 --vel-mode path \
  --diag-out diag.tsv --plot --plot-prefix iso_run
```

Quasi-grid with smoothing spline, diagnostics only:

```
guru-isentrope -i EOS_scattered.tsv --Ma 63.5 \
  --grid-mode quasi --smooth-s 2.0 \
  --T0 500 --rho0 5.0 --drho -0.02 --nmax 400 \
  -o Cu_iso.tsv --diag-out Cu_diag.tsv --plot --plot-prefix Cu_iso
```

## Outputs

- `iso.tsv`:

```
T	
ho	P	E_atom
300	0.8	... 	...
...
```

- `pu.tsv` (path mode):

```
P[kbar]	u[km/s]
P0	u0
...
```

- `diag.tsv`:

```
T[K]	rho[g/cm^3]	P[kbar]	c[km/s]	rho_c[g/cm^3*km/s]
...
```

- Plots when `--plot` is set:
  - `iso_run_P_rho.png`, `iso_run_P_T.png`, `iso_run_T_rho.png`
  - `iso_run_P_u.png` (only if u(P) was computed)

## Notes and tips

- Provide energy per atom whenever possible (`E_atom`), not total energy.
- For quasi grids, adjust `--smooth-s` to balance noise and fidelity.
- Release paths typically use negative `drho` and `--u0` from the shocked state.