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

**Назначение.** Добавляет столбец `phase` в *расширенный* TSV, полученный командой `guru-thermo --out`, используя коэффициент самодиффузии из `guru-msd --diff-out`. По умолчанию, если диффузия статистически неотличима от нуля → **твердое состояние** (`phase=0`), иначе → **жидкость** (`phase=1`).

---

## Синтаксис

```bash
guru-thermo-phase --thermo thermo_stats.tsv --msd D.tsv \
                  -o thermo_with_phase.tsv \
                  [--tol-1e9 0.01] [--sigma-level 2.0] [--print]
```

* `--thermo, -t` — входной **расширенный** TSV из `guru-thermo --out` (компактный `T P E` здесь не поддерживается).
* `--msd, -m` — TSV с диффузией из `guru-msd --diff-out`.
* `-o, --out` — выходной TSV с добавленным/перезаписанным столбцом `phase`.
* `--tol-1e9` — допуск в единицах $10^{-9},\mathrm{м^2/с}$; по умолчанию **0.01**.
* `--sigma-level` — параметр $k$ в правиле $k\sigma$; значение по умолчанию **2.0**.
* `--print` — дополнительно вывести краткую сводку решения в stdout.

---

## Входы и ожидаемые столбцы

### TSV из `guru-msd --diff-out` (устойчивый парсинг)

Инструмент принимает несколько вариантов заголовков и выбирает первый подходящий:

1. Предпочтительные уже масштабированные поля:

* `D_1e9_m2_s` и `D_1e9_m2_s_stderr` (или `..._err`).

2. SI-резерв (переводится в $10^{-9},\mathrm{м^2/с}$):

* `D_m2_s` и `D_m2_s_stderr` (или `..._err`).

3. Последняя возможность — наклон MSD (3D: $\mathrm{MSD}\approx 6Dt$):

* `slope_A2_per_fs` (и `slope_A2_per_fs_stderr`).

  * Пересчёт: $D = \tfrac{\text{slope}}{6}$; $1,\mathrm{\AA^2/fs} = 10^{-5},\mathrm{м^2/с}$.

Если ни один вариант не найден, скрипт завершается с понятной ошибкой.

### TSV из `guru-thermo --out`

Принимается любая схема, порождённая GURU. Если `phase` уже есть, он будет **перезаписан** во всех строках.

> Типичные столбцы: `T_mean, P_mean, E_mean, E_atom_mean (опция), V_cell_A3, V_at_A3, density_g_cm3, NIONS, ...`.

---

## Правило решения

Работа ведётся в $10^{-9},\mathrm{м^2/с}$. Пусть $D_9 = D\cdot 10^9$, а $\sigma_9$ — стандартная ошибка в тех же единицах. Правило по умолчанию:

* Если $D_9 + k,\sigma_9 \le \text{tol}$ ⇒ `phase = 0` (**твердое состояние**),
* иначе ⇒ `phase = 1` (**жидкость**),

при `tol = 0.01`, `k = 2.0`. Это консервативная логика: состояние считают твёрдым только если **верхняя граница** ошибки остаётся ниже допуска.

**Многострочные thermo TSV.** Предполагается, что одно значение MSD относится ко всей таблице (обычно: один участок MD → одна строка статистики). Если в thermo-файле несколько состояний, запускайте `guru-thermo-phase` по сегментам, чтобы избежать неправильных меток.

---

## Выходные данные

Копия исходной таблицы thermo с дополнительным столбцом `phase` (0 или 1). Если `phase` уже существовал, значения перезаписываются.

---

## Примеры

```bash
# Посчитать диффузию, присвоить фазу и вывести краткую сводку
guru-msd -x XDATCAR -o OUTCAR --diff-out D.tsv
guru-thermo -i OUTCAR --skip 500 --out thermo.tsv
guru-thermo-phase --thermo thermo.tsv --msd D.tsv -o thermo_with_phase.tsv --print
```

```bash
# Более строгий критерий твердости: 3σ в пределах 0.005×10^-9 м^2/с от нуля
guru-thermo-phase -t thermo.tsv -m D.tsv -o thermo_phase.tsv \
  --tol-1e9 0.005 --sigma-level 3.0
```

Типичный stdout при `--print`:

```
phase=0  (D_1e-9=0.0031 ± 0.0012, tol=0.0100, k=2.0)
```

---

## Диагностика

* **«Could not find diffusion coefficient columns in MSD TSV.»** Убедитесь, что `--diff-out` сформирован `guru-msd`, или переименуйте столбцы.
* **Несколько состояний в thermo TSV.** Одна и та же фазовая метка будет присвоена всем строкам; разбейте файл по сегментам при необходимости.

---

## Рекомендации

* Используйте `guru-msd --dry-run`, чтобы оценить длину траектории и подобрать разумное окно подгонки диффузии.
* Держите `--tol-1e9` достаточно малым, чтобы избегать ложных жидкостей/твёрдых фаз. Настраивайте допуск только если знаете уровень шума.