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

**Назначение.** Определяет область равновесия (конец «разогрева»/burn‑in) в термологе, находя достаточно длинное окно, где выбранные ряды (по умолчанию `P_sum`, `E_sum`) не имеют значимого тренда относительно собственных флуктуаций.

---

## Синтаксис
```bash
guru-equil -i ep_log.tsv \
  [--columns P_sum,E_sum] \
  [--min-window 200] [--drift-ratio 0.3] [--stride 1] \
  [--out equil.tsv] [--plot equil.png] [--quiet]
```

---

## Входные данные
- TSV из `guru-thermo --dump-log` с заголовком. Типичные колонки:
  `P_dft  P_nkt  P_sum  E_dft  E_kin  E_sum  T`.
- Если нет `P_sum` или `E_sum`, но есть их компоненты, суммы восстанавливаются как `P_dft + P_nkt` и `E_dft + E_kin`.

---

## Опции
- `--columns P_sum,E_sum` — колонки для проверки равновесия (через запятую).
- `--min-window L` — минимальная длина окна (в шагах), чтобы объявить равновесие (по умолчанию 200).
- `--drift-ratio r` — окно стабильно, если для каждого ряда дрейф за окно не превышает долю от внутривоконных флуктуаций:
  `|slope| * L <= r * std(window)` (по умолчанию 0.3).
- `--stride k` — шаг сдвига по старту окна (по умолчанию 1).
- `--out equil.tsv` — сохранить `start, end, length, min_window, drift_ratio, columns` в TSV.
- `--plot equil.png` — сохранить PNG‑график рядов с вертикальными линиями начала (зелёная) и конца (красная) равновесия.
- `--quiet` — тихий режим.

---

## Методика
- Для каждого окна `[i, i+L)` строится линейный тренд `y = a t + b` и считается `std(y)` внутри окна.
- Принимается первое окно, для которого выполняется `|a| * L <= drift_ratio * std(y)` для всех выбранных рядов.
- Начало равновесия — `i`; конец — последний индекс ряда. Если ни одно окно не прошло, выбирается последнее окно `[N-L, N)`.

---

## Выходные данные
- В stdout: `Equilibrium start`, `Equilibrium end`, `Length`.
- `--out`: однострочный TSV с параметрами и найденными индексами.
- `--plot`: PNG‑визуализация рядов с отмеченными границами.

---

## Примеры
```bash
# Построить лог и определить окно равновесия (настройки по умолчанию)
guru-thermo -i OUTCAR --dump-log ep_log.tsv
guru-equil -i ep_log.tsv --out equil.tsv --plot equil.png
```
```bash
# Строже (длиннее окно, ниже допустимый дрейф)
guru-equil -i ep_log.tsv --columns P_sum,E_sum --min-window 400 --drift-ratio 0.2 \
  --out equil.tsv --plot equil.png
```

---

## Замечания
- Выбирайте `--min-window` сопоставимым типичному burn‑in (например, 200–500). Увеличивайте для шумных данных или при фазовых переходах.
- Можно добавить дополнительные ряды в `--columns` (например, `T`), чтобы требовать устойчивость по большему числу параметров.