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

**Purpose.** Compute the **mean squared displacement** (MSD) and the **self‑diffusion coefficient** from `XDATCAR` plus `POTIM` from `OUTCAR`. Works for fully general triclinic cells and uses fractional‑space unwrapping under PBC.

---

## Synopsis
```bash
guru-msd -x XDATCAR1 [XDATCAR2 ...] -o OUTCAR \
         [--skip N] [--stride K] [--end N] [--indices RANGES] \
         [--fit auto|window] [--fit-start fs] [--fit-end fs] [--min-tail-frac a] \
         [--msd-log msd.tsv] [--diff-out D.tsv] [--plot msd.png] \
         [--progress|--no-progress] [--dry-run] [--quiet]
```

**Options**
- `--skip/--stride/--end` — subsample frames.
- `--indices` — subset of atoms as 1‑based ranges (e.g. `1-32,60,100-120`).
- `--fit auto` — scan tail windows and choose the one with best R², requiring at least `--min-tail-frac` of points.
- `--fit window` — manual window starting at `--fit-start` fs; if `--fit-end` is omitted, the fit goes **to the end**.
- `--dry-run` — only report frames, atoms, `POTIM`, total & effective (post‑subsampling) time, then exit.
- `--progress` / `--no-progress` — enable/disable a progress indicator on stderr (auto‑enabled on TTY unless `--quiet`). Uses `tqdm` if available; otherwise a simple text indicator.

**Outputs**
- `--msd-log` — `step  t_fs  MSD_A2`.
- `--diff-out` — slope, `D` in Ų/fs, m²/s, and 10⁻⁹ m²/s, with stderr and fit window.
- `--plot` — PNG with MSD points and the fitted line drawn only on the selected window.

---

## Method
- Fractional displacements with nearest‑image wrap: `Δs = (s_t − s_{t-1}) − round(s_t − s_{t-1})`, accumulate `S_t`.
- Metric tensor `G = L Lᵀ` from the first POSCAR header in `XDATCAR` (Ų).
- `MSD(t) = ⟨ S_tᵀ G S_t ⟩_atoms`.
- Diffusion in 3D: `MSD ≈ 6 D t` ⇒ `D = slope / 6`.

---

## Examples
```bash
# Auto window
guru-msd -x XDATCAR -o OUTCAR --msd-log msd.tsv --diff-out D.tsv --plot msd.png

# Manual window from 10 ps to end
guru-msd -x XDATCAR -o OUTCAR --fit window --fit-start 10000 --plot msd.png

# Inspect length and timing only
guru-msd -x XDATCAR -o OUTCAR --skip 100 --stride 5 --dry-run

# Multi‑segment trajectory (concatenate two XDATCAR files)
guru-msd -x XDATCAR_part1 XDATCAR_part2 -o OUTCAR \
         --msd-log msd.tsv --diff-out D.tsv --plot msd.png
```

---

## Troubleshooting
- **Not enough frames** — increase simulation length or relax `--skip/--stride/--end`.
- **Nonlinear MSD tail** — increase `--fit-start` or use `--fit auto` to select a later segment.

---

## Performance tips
- Use `--indices` to restrict expensive unwrapping/averaging to mobile species only (e.g. light ions).
- Prefer writing the MSD log and plotting externally for very long runs to reduce memory pressure.