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

**Purpose.** Extract per-step thermodynamic properties from VASP `OUTCAR` (and legacy logs), compute statistics over a chosen window, and optionally emit a rich TSV with structural information inferred from the same `OUTCAR` (cell volume, per-atom volume, density, masses, NIONS).

---

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

**Positional/required**
- `-i, --input` one or more **OUTCAR** files or a compact per-step log (TSV) produced by older scripts or `--dump-log`.

Multi‑file OUTCAR
- If multiple OUTCAR paths are provided, they are concatenated as a single continuous run.
- Consistency checks are enforced before concatenation: `NIONS`, direct lattice (first block), `TEBEG`, `SIGMA`, and POTCAR/TITEL sequence must match across files. Any mismatch aborts with an informative error.

**Common options**
- `--format {outcar,log}` — force input format (auto-detected by default).
- `--skip N` — skip first **N** thermo rows before averaging.
- `--end N` — stop window at absolute index **N** (Python-style `[start:end)`).
- `--maxrows N` — limit the number of rows used after `--skip`.
- `--pressure-col NAME` — which pressure to average; default `P_sum` ("total pressure").
- `--energy-col NAME` — which energy to average; default `E_sum` (DFT + kinetic when present).
- `--strict` — if any row in the window lacks a required field, print a warning and exit with non‑zero code.
- `--quiet` — suppress progress info.
- `--dry-run` — fast count only: print detected format, total rows, window start/end and available rows, then exit.
- `--plot PATH` — save a PNG with `P_sum` and `E_sum` vs step (falls back to selected columns if sums are missing). Plotting is skipped if matplotlib is unavailable.
 - `--progress` / `--no-progress` — enable/disable a progress indicator on stderr. By default, progress shows if stderr is a TTY and `--quiet` is not set. Uses `tqdm` when available; otherwise a lightweight text indicator.

**Outputs**
- **Stdout (compact)** — header `T\tP\tE` and one averaged line.
- `--out stats.tsv` — rich TSV with means/STD/SEM/variance + structural fields when available.
- `--dump-log ep_log.tsv` — per-step compact log for downstream tools (header + rows).
 - `--plot` — PNG with `P_sum(kbar)` and `E_sum(eV)` as functions of the step.

---

## Input formats

### OUTCAR
`guru-thermo` scans the file and extracts, when present: external pressure, ideal-gas (kinetic) pressure, total pressure, kinetic energy, entropy-free total energy, temperature (`EKIN_LAT` block), and static data:
- `direct lattice vectors` (first occurrence; used to recompute cell volume by triple product),
- `POMASS` and `ions per type` (or `NIONS`) to compute the density,
- `number of ions  NIONS = ...`.

### Legacy compact log (TSV)
Header must be present (first line), typical columns:
```
P_dft	P_nkt	P_sum	E_dft	E_kin	E_sum	T
```
Other subsets are accepted; missing columns are skipped but logged.

---

## Statistics
Let `window = rows[start:end]` where `start = --skip`, `end = --end or len(rows)` then optionally trimmed by `--maxrows`. For each requested column (T, P, E):
- **mean**: `np.mean`;
- **variance**: sample variance `np.var(..., ddof=1)` if `N>1`, else `0`;
- **SEM**: `std / sqrt(N)` with sample `std` if `N>1`, else `0`.

`--strict` causes a controlled abort if within the averaging window some rows miss required values, to avoid biased means.

---

## Rich TSV (`--out`)
Columns (tab-separated):
- Thermo statistics: `T_mean, T_std, T_sem, P_mean, P_std, P_sem, E_mean, E_std, E_sem`.
- Window accounting: `N_used, N_skipped, start, end`.
- Structure (if parsed from `OUTCAR`): `V_cell_A3, V_at_A3, density_g_cm3, NIONS, ions_per_type, masses_amu`.

> **Note:** Energy per atom (`E_atom_mean`) is included when the input had per-atom energy; otherwise `E_mean` is already per atom for MD outputs.

---

## Examples

Average last 1500 steps and save detailed stats & per-step log:
```bash
guru-thermo -i OUTCAR --skip 500 --end 2000 \
  --out thermo_stats.tsv --dump-log ep_log.tsv
```

Use a legacy per-step TSV as input:
```bash
guru-thermo -i ep_log.tsv --format log --skip 100
```

Quickly inspect how many rows are available for averaging:
```bash
guru-thermo -i OUTCAR --skip 500 --end 2000 --dry-run
```

Concatenate two OUTCAR parts of a resumed QMD run and average over both:
```bash
guru-thermo -i OUTCAR_part1 OUTCAR_part2 --skip 500 \
  --out thermo_stats.tsv --dump-log ep_log.tsv
```

---

## Troubleshooting
- **"No thermo rows parsed"** — wrong `--format` or header in the TSV missing or misspelled.
- **Strict mode exit** — some rows in the averaging window lacked the requested columns; re-run without `--strict` to see which indices are skipped.
- **Density missing** — `OUTCAR` did not have both `POMASS` and counts; density-related fields will be empty in `--out`.

---

## Performance tips
- Prefer running on `OUTCAR` directly; it spares creating large intermediates.
- Use `--dump-log` once, then downstream tools can reuse a small TSV instead of scanning `OUTCAR` repeatedly.
- When only stdout means are needed (no `--out`/`--dump-log`), the tool streams statistics without storing all rows.