# GURU — `guru-equil` Manual (EN)

**Purpose.** Detect the equilibrium segment (burn‑in end) in a thermo log by scanning for a drift‑free window relative to the natural fluctuations of selected series (default: `P_sum`, `E_sum`).

---

## Synopsis
```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]
```

---

## Inputs
- TSV from `guru-thermo --dump-log` with a header row. Typical columns:
  `P_dft  P_nkt  P_sum  E_dft  E_kin  E_sum  T`.
- If `P_sum` or `E_sum` are missing but their components are present, they are reconstructed as `P_dft + P_nkt` and `E_dft + E_kin`.

---

## Options
- `--columns P_sum,E_sum` — comma‑separated series to test for equilibrium.
- `--min-window L` — minimal window length (steps) to declare equilibrium (default 200).
- `--drift-ratio r` — window is stable if for each series the drift over the window does not exceed a fraction of in‑window fluctuations:
  `|slope| * L <= r * std(window)` (default 0.3).
- `--stride k` — stride for sliding the window start (default 1).
- `--out equil.tsv` — write `start, end, length, min_window, drift_ratio, columns` to a TSV.
- `--plot equil.png` — save a PNG: each series, plus vertical lines at start (green) and end (red).
- `--quiet` — suppress info messages.

---

## Method
- For each candidate window `[i, i+L)`, fit a straight line `y = a t + b` to each selected series and compute `std(y)` inside the window.
- Accept the first window for which `|a| * L <= drift_ratio * std(y)` holds for all series.
- The equilibrium start is `i`; the end is the last index of the series. If no window passes, fall back to the last window `[N-L, N)`.

---

## Output
- Stdout: `Equilibrium start`, `Equilibrium end`, `Length`.
- `--out`: one‑row TSV with parameters and detected indices.
- `--plot`: PNG visualization of series and detected boundaries.

---

## Examples
```bash
# Build per‑step log and detect equilibrium window (default settings)
guru-thermo -i OUTCAR --dump-log ep_log.tsv
guru-equil -i ep_log.tsv --out equil.tsv --plot equil.png
```
```bash
# Stricter detection (longer window, tighter drift)
guru-equil -i ep_log.tsv --columns P_sum,E_sum --min-window 400 --drift-ratio 0.2 \
  --out equil.tsv --plot equil.png
```

---

## Notes
- Choose `--min-window` comparable to typical burn‑in (e.g., 200–500). Increase for noisy data or when phase transitions occur.
- You can add more columns in `--columns` (e.g., `T`) to require stability across additional series.