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

**Purpose.** Append a `phase` column to a *rich* TSV produced by `guru-thermo --out` using the self‑diffusion coefficient from `guru-msd --diff-out`. By default, if diffusion is statistically indistinguishable from zero → **solid** (`phase=0`), else **liquid** (`phase=1`).

---

## Synopsis

```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` — input **rich** TSV from `guru-thermo --out` (compact `T P E` is not supported here).
* `--msd, -m` — diffusion TSV from `guru-msd --diff-out`.
* `-o, --out` — output TSV with appended/overwritten `phase` column.
* `--tol-1e9` — tolerance in units of $10^{-9},\mathrm{m^2/s}$; default **0.01**.
* `--sigma-level` — $k$ in the $k\sigma$ rule; default **2.0**.
* `--print` — also print the decided phase summary to stdout.

---

## Inputs & expected columns

### `guru-msd --diff-out` TSV (robust parsing)

The tool accepts several header variants and picks the first that matches:

1. Preferred already-scaled fields:

* `D_1e9_m2_s` and `D_1e9_m2_s_stderr` (or `..._err`).

2. SI fallback (converted to $10^{-9},\mathrm{m^2/s}$):

* `D_m2_s` and `D_m2_s_stderr` (or `..._err`).

3. Last resort via MSD slope (3D: $\mathrm{MSD}\approx 6Dt$):

* `slope_A2_per_fs` (and `slope_A2_per_fs_stderr`).

  * Convert: $D = \tfrac{\text{slope}}{6}$; $1,\mathrm{\AA^2/fs} = 10^{-5},\mathrm{m^2/s}$.

If none is present, the script stops with a clear error message.

### `guru-thermo --out` TSV

Any schema produced by GURU is accepted. If `phase` already exists, it is **overwritten** for all rows.

> Typical columns include: `T_mean, P_mean, E_mean, E_atom_mean (optional), V_cell_A3, V_at_A3, density_g_cm3, NIONS, ...`.

---

## Decision rule

Work in $10^{-9},\mathrm{m^2/s}$ throughout. Let $D_9 = D\cdot 10^9$ and $\sigma_9$ be the stderr in the same units. The default rule is:

* If $D_9 + k,\sigma_9 \le \text{tol}$ ⇒ `phase = 0` (**solid**),
* else ⇒ `phase = 1` (**liquid**),

with defaults `tol = 0.01`, `k = 2.0`. This is conservative: only if the **upper** error bar stays below the tolerance do we mark the state as solid.

**Multi‑row thermo TSVs.** The tool assumes one MSD result represents the whole thermo table (typical: one MD segment → one stats row). If your thermo file has multiple different states, run `guru-thermo-phase` per segment to avoid mislabeling.

---

## Output

A copy of the input thermo table with an extra `phase` column (0 or 1). If `phase` exists, values are overwritten.

---

## Examples

```bash
# Compute diffusion, tag phase, and print a one-line summary
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
# Stricter solid criterion: 3σ within 0.005×10^-9 m^2/s of zero
guru-thermo-phase -t thermo.tsv -m D.tsv -o thermo_phase.tsv \
  --tol-1e9 0.005 --sigma-level 3.0
```

Typical stdout with `--print`:

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

---

## Troubleshooting

* **“Could not find diffusion coefficient columns in MSD TSV.”** Ensure `--diff-out` came from `guru-msd` or rename columns accordingly.
* **Multiple states in thermo TSV.** The same phase label will be applied to all rows; split the file per segment if needed.

---

## Best practices

* Use `guru-msd --dry-run` to inspect trajectory length and choose a meaningful fitting window for diffusion.
* Keep `--tol-1e9` reasonably small to avoid false liquids/solids. Tune only if you know your noise floor.