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

**Назначение.** Извлекает пошаговые термодинамические величины из VASP `OUTCAR` (и наследуемых логов), вычисляет статистики на выбранном окне и, при необходимости, формирует расширенный TSV со структурной информацией, полученной из того же `OUTCAR` (объём ячейки, объём на атом, плотность, массы, NIONS).

---

## Синтаксис
```bash
guru-thermo -i OUTCAR1 [OUTCAR2 ...] [--format outcar|log] \
            [--skip N] [--end N] [--maxrows N] \
            [--pressure-col P_sum] [--energy-col E_sum] \
            [--strict] [--quiet] [--dry-run] \
            [--out stats.tsv] [--dump-log ep_log.tsv] \
            [--plot thermo.png] [--progress|--no-progress]
```

**Позиционные/обязательные**
- `-i, --input` — один или несколько файлов **OUTCAR** либо компактный покадровый лог (TSV), сформированный старыми скриптами или `--dump-log`.

Ввод из нескольких OUTCAR
- Если указано несколько OUTCAR, они склеиваются в один непрерывный расчёт.
- Перед склейкой выполняются проверки согласованности: должны совпадать `NIONS`, прямые векторы решётки (первый блок), `TEBEG`, `SIGMA` и последовательность POTCAR/TITEL. При несовпадении выводится понятная ошибка, работа прерывается.

**Часто используемые опции**
- `--format {outcar,log}` — принудительно задать формат входа (по умолчанию определяется автоматически).
- `--skip N` — пропустить первые **N** строк термокривой перед усреднением.
- `--end N` — завершить окно на абсолютном индексе **N** (в стиле Python `[start:end)`).
- `--maxrows N` — ограничить число строк после `--skip`.
- `--pressure-col NAME` — какое давление усреднять; по умолчанию `P_sum` («total pressure»).
- `--energy-col NAME` — какую энергию усреднять; по умолчанию `E_sum` (DFT + кинетическая, если есть).
- `--strict` — если в окне усреднения какая-то строка не содержит нужного поля, вывести предупреждение и завершить работу с ошибкой.
- `--quiet` — скрыть прогресс.
- `--dry-run` — быстрый подсчёт: вывести определённый формат входа, общее число строк, окно (start/end) и число доступных для усреднения строк; затем завершить работу.
- `--plot PATH` — сохранить PNG с `P_sum` и `E_sum` в зависимости от шага (при отсутствии суммарных столбцов используется выбранная пара `--pressure-col`/`--energy-col`). Если matplotlib недоступен, построение пропускается.
 - `--progress` / `--no-progress` — включить/выключить индикатор прогресса в stderr. По умолчанию показывает прогресс, если stderr — TTY и не задан `--quiet`. При наличии `tqdm` используется красивая полоса; иначе — лёгкий текстовый индикатор.

**Выводы**
- **Stdout (компактный)** — заголовок `T\tP\tE` и одна строка со средними.
- `--out stats.tsv` — расширенный TSV со средними/СКО/SEM/дисперсией + структурными полями, когда доступны.
- `--dump-log ep_log.tsv` — покадровый компактный лог для последующих инструментов (заголовок + строки).
 - `--plot` — PNG с `P_sum (кбар)` и `E_sum (эВ)` как функции шага.

---

## Форматы входных данных

### OUTCAR
`guru-thermo` читает файл и извлекает, когда присутствует: внешнее давление, идеальное (кинетическое) давление, полное давление, кинетическую энергию, энтропийно-свободную полную энергию, температуру (блок `EKIN_LAT`), а также статические данные:
- `direct lattice vectors` (первое вхождение; используется для вычисления объёма ячейки через тройное произведение),
- `POMASS` и `ions per type` (или `NIONS`) для вычисления плотности,
- `number of ions  NIONS = ...`.

### Компактный лог (TSV)
Требуется заголовок (первая строка), типичные столбцы:
```
P_dft	P_nkt	P_sum	E_dft	E_kin	E_sum	T
```
Допускаются подмножества; отсутствующие столбцы пропускаются, но фиксируются в логах.

---

## Статистика
Пусть `window = rows[start:end]`, где `start = --skip`, `end = --end или len(rows)`, далее окно можно укоротить `--maxrows`. Для каждого столбца (T, P, E):
- **mean**: `np.mean`;
- **variance**: выборочная дисперсия `np.var(..., ddof=1)` при `N>1`, иначе `0`;
- **SEM**: `std / sqrt(N)` с выборочным `std` при `N>1`, иначе `0`.

`--strict` обеспечивает контролируемый выход, если внутри окна усреднения встречаются строки без требуемых значений, чтобы не получить смещённые средние.

---

## Расширенный TSV (`--out`)
Столбцы (разделитель — табуляция):
- Термостатистика: `T_mean, T_std, T_sem, P_mean, P_std, P_sem, E_mean, E_std, E_sem`.
- Учёт окна: `N_used, N_skipped, start, end`.
- Структура (если извлечена из `OUTCAR`): `V_cell_A3, V_at_A3, density_g_cm3, NIONS, ions_per_type, masses_amu`.

> **Примечание:** энергия на атом (`E_atom_mean`) включается, если вход содержал пер-атомную энергию; иначе `E_mean` уже задан в расчётах MD как энергия на атом.

---

## Примеры

Усреднить последние 1500 шагов и сохранить подробную статистику и покадровый лог:
```bash
guru-thermo -i OUTCAR --skip 500 --end 2000 \
  --out thermo_stats.tsv --dump-log ep_log.tsv
```

Использовать наследуемый покадровый TSV в качестве входа:
```bash
guru-thermo -i ep_log.tsv --format log --skip 100
```

Быстро оценить доступное число шагов для усреднения:
```bash
guru-thermo -i OUTCAR --skip 500 --end 2000 --dry-run
```

Склеить две части возобновлённого QMD‑расчёта и усреднить по обоим:
```bash
guru-thermo -i OUTCAR_part1 OUTCAR_part2 --skip 500 \
  --out thermo_stats.tsv --dump-log ep_log.tsv
```

---

## Диагностика
- **"No thermo rows parsed"** — неверный `--format` или отсутствует/искажён заголовок TSV.
- **Выход по strict‑режиму** — в окне усреднения отсутствовали требуемые столбцы; запустите без `--strict`, чтобы увидеть пропущенные индексы.
- **Плотность не вычислена** — в `OUTCAR` нет одновременно `POMASS` и количества ионов; поля, связанные с плотностью, будут пустыми в `--out`.

---

## Рекомендации по производительности
- Предпочитайте работать напрямую с `OUTCAR`; это избавляет от создания крупных промежуточных файлов.
- Один раз запишите `--dump-log`, после чего остальные инструменты смогут использовать небольшой TSV, не перечитывая `OUTCAR` многократно.
- Если нужны только средние на stdout (без `--out`/`--dump-log`), инструмент считает статистики потоково, не храня все строки в памяти.