# GURU — Изоэнтропа (guru-isentrope)

Расчёт изоэнтропической кривой T(ρ) по табличному EOS P(T,ρ), E(T,ρ) и массовой скорости u(P) по соотношениям Римана. Поддерживаются прямоугольные сетки (точные сплайны) и «квазисетки» (сглаживающие сплайны).

## Единицы и соглашения

- Температура T: K
- Плотность ρ: г/см^3
- Давление P: кбар
- Энергия E: эВ/атом (на атом)
- Массовая скорость u: км/с
- Молярная масса Ma: г/моль

## Физика и формулы

Наклон изоэнтропы в плоскости T–ρ (через теплоёмкость при постоянном объёме):

    dT/dρ |_S = (T / ρ^2) * ( (∂P/∂T)|_ρ / c_v ),
    c_v = (∂E/∂T)|_ρ · (эВ→Дж) / m_atom,
    m_atom = Ma / N_A / 1000 (кг/атом).

В реализации явно учтены переводы единиц:

- (∂P/∂T) в кбар/К → Па/К (1 кбар = 1e8 Па).
- c_v из (∂E/∂T) в эВ/атом/К → Дж/(кг·К).
- dT/dρ возвращается в K на (г/см^3).

Соотношение Римана для массовой скорости на изоэнтропическом разгружении:

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

В инструменте используется практическая форма:

    u(P) = u0 + ∫ (1/ρ) √(max(dρ/dP, 0)) dP / √10,  при P в кбар и ρ в г/см^3.

Фактор √10 следует из 1 кбар = 1e8 Па и согласования единиц.

## Численные методы

- Сплайны:
  - Прямоугольная сетка: RectBivariateSpline для P(T,ρ) и E(T,ρ), точная интерполяция (s=0).
  - Квазисетка: SmoothBivariateSpline по «рассеянным» точкам (T,ρ) с фактором сглаживания `s ≥ 0`.
- Интегрирование: двухстадийная явная схема (Эйлер–Коши / Хойна) с параметром a=0.5 по равномерным шагам ρ `drho` (может быть <0 для разгрузки).
- P и E берутся из выбранных сплайнов вдоль интегрируемого пути.
- Контроль экстраполяции: разрешается выход за базовые пределы сетки до ±`extrap-frac` по T и ρ; далее расчёт прекращается с сообщением.
- Стоп по давлению `--stop-P-le`: остановка, когда P ≤ порог.

## CLI

```
guru-isentrope \
  -i EOS.tsv [EOS2.tsv ...] \
  --Ma <г/моль> \
  --T0 <K> --rho0 <г/см^3> --drho <г/см^3> --nmax <N> \
  -o iso.tsv [--out-velocity pu.tsv] [--diag-out diag.tsv]
```

Ключевые опции:

- Вход и сетка:
  - `-i/--input`: один или несколько TSV. Поддерживаются «компактные» и «rich» TSV. Имена колонок распознаются без учета регистра с синонимами: `T/T_mean`, `P/P_mean`, `E_atom/E_atom_mean/E/E_mean`, `rho/density_g_cm3/d`.
  - `--grid-mode {rect,quasi}`: прямоугольная точная сетка (по умолчанию) или сглаживающие сплайны по квазисетке.
  - `--smooth-s <float>`: фактор сглаживания для quasi (0 = интерполяция).
- Начальная точка и шаги:
  - `--T0`, `--rho0`, `--drho` (отрицательный для разгрузки), `--nmax` количество шагов.
  - `--extrap-frac <доля>`: допустимая экстраполяция за пределы сетки (по умолчанию 0.10 = 10%).
  - `--stop-P-le <кбар>`: остановка при P ≤ порога.
- Выходы:
  - `-о/--out`: изоэнтропа с колонками `T  rho  P  E_atom`.
  - `--out-velocity`: массовая скорость `P[kbar]  u[km/s]`.
  - `--u0 <км/с>`: начальная массовая скорость.
  - `--vel-mode {path,grid}`: считать u(P) в точках пути или на равномерной сетке по давлению.
  - `--vel-dp <кбар>`, `--vel-Pmin <кбар>`: шаг и нижний предел для grid‑режима.
- `--diag-out`: диагностика `T  rho  P  c[km/s]  rho_c`.
  - Графики: `--plot` сохраняет PNG; `--plot-prefix` задаёт префикс имён.
    - Сохраняемые графики:
      - `<prefix>_P_rho.png` — P от ρ
      - `<prefix>_P_T.png` — P от T
      - `<prefix>_T_rho.png` — T от ρ
      - `<prefix>_P_u.png` — P от u (только если считали u(P))
- Удобства:
  - `--progress/--no-progress`: индикатор прогресса.
  - `--no-log`: не писать вызов в `guru.log` рядом с выходами.

## Примеры

Прямоугольная сетка, разгрузка, стоп при P≤0, диагностика и u(P) в точках пути:

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

Квазисетка с сглаживающим сплайном, только диагностика:

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

## Выходы

- `iso.tsv`:

```
T	ρ	P	E_atom
300	0.8	...	...
...
```

- `pu.tsv` (режим path):

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

- Графики при `--plot`:
  - `iso_run_P_rho.png`, `iso_run_P_T.png`, `iso_run_T_rho.png`
  - `iso_run_P_u.png` (если считали u(P))

## Замечания

- Подавайте энергию **на атом** (E_atom), если возможно; иначе интерпретация `E` может отличаться.
- Для квазисетки подбирайте `--smooth-s`, чтобы уравновесить шум/точность.
- Разгрузка обычно использует отрицательный `drho` и `--u0` из ударно‑сжатого состояния.