# GURU — руководство по `guru-iso-fit` (RU)

**Назначение.** По термологам TSV (обычно из `guru-thermo`) или по прямоугольной сетке EOS строит кривые и вычисляет/восстанавливает:
- **изотерму** (const `T`) и **изохору** (const `ρ`) — по точкам (полиномы) или по сетке (интерполяция);
- **изобару** (const `P`) — восстановление пути `(T,ρ,E)` по точкам (сглаживающие би-сплайны) или по сетке.

---

## Синтаксис
```bash
# Точки (TSV) — изотерма/изохора
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]

# Точки — изобара (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]

# Сетка EOS — если --mode опущен:
#   --grid-T => изотерма,  --grid-rho => изохора,  иначе — изобара
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]
```

**Входные данные**
- Один или несколько TSV: **компактный** (`T\tP\tE`) или **расширенный** (столбцы `*_mean`). Плотность `ρ` берётся из расширенного TSV, если она там есть.
- Прямоугольная сетка EOS (TSV со столбцами `T`, `rho`, `P`, `E/E_atom`).

**Ключевое поведение**
- Скрипт **автоматически определяет характерную T или ρ** по данным (среднее значение) и проверяет однородность в пределах `--tol` (для изотермы/изохоры).
  - Значения по умолчанию: `--tol` **10 K** (изотерма) и **0.01 г/см³** (изохора).
  - Если есть точки вне допуска: при `--on-outliers ignore` они отбрасываются; при `fail` скрипт выводит сообщение и завершает работу.
- Используется **энергия на атом** (`E_atom` / `E_atom_mean`), если доступна; иначе `E` трактуется как пер-атомная величина.

**Аппроксимация/интерполяция**
- Изотерма: аппроксимировать `E(V)` и `P(V)` по `V = 1/ρ` полиномом степени 1–3. Оценить `E(V*)` при условии `P(V*) = P*`.
- Изохора : аппроксимировать `E(T)` и `P(T)` по `T`. Оценить `E(T*)` при `P(T*) = P*`.
- Экстраполяция допускается, но помечается в комментарии вывода.

**Изобара**
- По точкам: строки группируются в приблизительные изотермы (по `T` с допуском `--tol`) и изохоры (по `ρ` с допуском `--tol`), по каждой кривой строится PCHIP и решается `P=P*` (скобка + `brentq`). При `--isobar-allow-extrap` допускается осторожная экстраполяция, такие точки помечаются. Экстраполяция в отрицательные температуры запрещена.
- По сетке: используются интерполяторы с сохранением формы; для каждого `T` берётся «скобка» по узлам `ρ` и уточняется корень `brentq`. Если базовая сетка неотрицательна по `T`/`ρ`, нижние границы удерживаются ≥ 0.

**Результаты**
- Для **изотермы**: строка TSV `T  P  E  V  rho  mode  degree`.
- Для **изохоры**: строка TSV `rho  P  E  T  mode  degree`.
- Для **изобары**: многократные строки TSV `T  rho  P  E` (путь вдоль изобары).

**Графики**
- При `--plot` формируются PNG:
  - Изотерма: **P–ρ** и **E–ρ** (точки + аппроксимация, вычисленная точка отмечена).
  - Изохора : **P–T** и **E–T** (те же обозначения).
  - Изобара  : **T–ρ** и **E–T** вдоль изобары (линия для сетки, точки/линия для режима по точкам).
  - Дополнительно для grid‑режима изотермы/изохоры — отдельные графики с выделенной целевой точкой.

**Прогресс**
- `--progress` / `--no-progress` включают/отключают прогресс в stderr. В grid‑режиме показаны отдельные стадии (изотерма/изохора/изобара), в points‑режиме isobar — по кривым.

---

## Примеры
Вычислить `P=0` вдоль изохоры, собранной из двух файлов:
```bash
guru-iso-fit --mode isochor --degree 2 --pressure 0 \
  -i rho15.tsv rho15_part2.tsv -o init_rho15.tsv --plot
```
Изотерма около 300 K (определена автоматически), кубический полином:
```bash
guru-iso-fit --mode isotherm --degree 3 --pressure 200 \
  -i T300.tsv -o init_T300.tsv --plot --plot-prefix plots/T300
```
Изобара по сетке при `P=100` кбар:
```bash
guru-iso-fit --grid-eos EOS_grid.tsv --pressure 100 -o isobar_grid.tsv --plot
```
Изобара по точкам при `P=200` кбар:
```bash
guru-iso-fit --mode isobar --pressure 200 -i rich/*.tsv -o isobar_points.tsv --isobar-n 600 --plot
```

---

## Диагностика
- **Неоднородные данные**: проверьте `--tol`; убедитесь, что входы относятся к одной изотерме/изохоре; используйте `--on-outliers ignore`, чтобы отбросить ошибочные строки.
- **Экстраполяция**: запрошенное давление вне диапазона аппроксимации; добавьте точки.
- **Нет точек изобары**: выбранное `P*` может быть недостижимо в пределах диапазона; расширьте границы или используйте режим сетки.
- **Отрицательные температуры**: при экстраполяции в points‑режиме изобары решения с T<0 отбрасываются.

---

## Примечания по единицам
- `P` в кбар, `T` в К, `E` в эВ/атом, `ρ` в г/см³ (совместимо с выводом `guru-thermo`).