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

**Purpose.** Compute the radial distribution function g(r) from VASP `XDATCAR` trajectories with periodic boundary conditions for general triclinic cells. Supports overall and partial RDFs g_{αβ}(r), optional smoothing, robust peak/min detection, first‑shell coordination number, and plotting.

---

## Synopsis
```bash
guru-rdf -x XDATCAR1 [XDATCAR2 ...] \
  [--skip N] [--stride K] [--end N] \
  [--pair i-j [--pair p-q ...]] \
  [--rmax R] [--bins M] \
  [--smooth-r L] [--n1-from-raw] \
  [--n1-bound {rdf|shell}] \
  [--peak-min-r R0] [--peak-smooth-r Lp] \
  [--baseline-tail-frac f] [--peak-amp-frac af] [--peak-amp-abs a0] \
  [--peak-prom-frac pf] [--peak-prom-abs p0] \
  [--rdf-out rdf.tsv] [--shell-column] \
  [--stats-out stats.tsv] \
  [--plot rdf.png] [--plot-shell shell.png] [--mark-extrema] \
  [--progress|--no-progress] \
  [--dry-run] [--quiet]
```

Multi‑file input
- `-x` accepts one or more XDATCAR paths. Trajectory frames are concatenated in order;
  a warning is printed if the first frame of the next file does not match the last
  frame of the previous (continuity check). `--skip/--stride/--end` apply after concatenation.
  The lattice from the first file is used.

---

## Inputs
- `XDATCAR` from VASP with fractional coordinates per frame. The POSCAR‑like header is parsed to read the lattice, species counts and total ion count.
- Assumes a fixed simulation cell across frames (typical for `XDATCAR`). If your cell varies, contact the maintainers.

---

## Options
- Trajectory windowing:
  - `--skip N` — skip first N frames; `--stride K` — take each K‑th frame; `--end N` — use at most N selected frames.
- Pair selection (multi‑component):
  - `--pair i-j` — species pair(s) by 1‑based ordinals from the header counts; repeat or comma‑separate. If omitted, computes overall g(r) across all atoms.
- Binning and cut‑off:
  - `--rmax R` (Å) — maximum r; default `~0.48*min(|a|,|b|,|c|)` to avoid aliasing.
  - `--bins M` — number of bins (uniform Δr); output step `dr = rmax / M`.
- Smoothing and integration:
  - `--smooth-r L` (Å) — moving‑average smoothing length for output g(r) and plots; `0` disables.
  - `--n1-from-raw` — integrate coordination number from raw g(r) even when smoothing is enabled.
- First‑shell boundary selector:
  - `--n1-bound rdf|shell` — choose `r_min` as the first minimum of g(r) (`rdf`) or of the shell neighbor density `4πρ r² g(r)` (`shell`). Default `rdf`.
- Peak/min detection (pro mode):
  - `--peak-min-r R0` — ignore r < R0 when seeking the first peak (default 0.5 Å).
  - `--peak-smooth-r Lp` — smoothing for peak detection only (default 0.1 Å; `0` disables).
  - `--baseline-tail-frac f` — tail fraction used to estimate large‑r baseline (default 0.2).
  - `--peak-amp-frac af`, `--peak-amp-abs a0` — minimal peak height relative to baseline and absolute (defaults 0.4, 0.1).
  - `--peak-prom-frac pf`, `--peak-prom-abs p0` — minimal prominence above local floor relative to baseline and absolute (defaults 0.1, 0.05).
- Outputs:
  - `--rdf-out rdf.tsv` — table with `r_A`, `g(curve)` columns; when `--shell-column` is set also adds `shell(curve) = 4πρ r² g(r)`.
- `--stats-out stats.tsv` — per‑curve summary (TSV): `curve, r_peak_A, r_min_A, n1, dr_A`.
  - `--plot` — PNG of g(r) curves. `--plot-shell` — PNG of shell neighbor density. `--mark-extrema` — add vertical lines at `r_peak` (dotted) and `r_min` (dashed).
- Utility:
  - `--dry-run` — print frames, species, volume, default `rmax`, `bins`, then exit.
  - `--quiet` — reduce console output.
  - `--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.

---

## Method
- Distances under PBC via metric tensor. Let L be the lattice (rows a,b,c in Å) and `G = L Lᵀ`.
- For atoms at fractional positions s, nearest‑image displacement `Δs = (s_t − s_{t-1}) − round(s_t − s_{t-1})`; instantaneous pair distances use `|Δr| = sqrt(Δsᵀ G Δs)`.
- Histogram pairs into uniform bins `[0, rmax]` with width `dr`.
- Normalization (overall or partial αβ) gives RDF g(r). The local shell neighbor density is
  $$ s(r) = 4\pi\,\rho\, r^2\, g(r), \quad \rho = \frac{N}{V}. $$
- First‑shell coordination number
  $$ n_1 = 4\pi\,\rho \int_{0}^{r_{\min}} r^2 g(r)\,\mathrm{d}r, $$
  with `r_min` chosen as the first minimum of either `g(r)` or `s(r)` depending on `--n1-bound`.
- Peak/min detection is robust to small‑r noise by optional smoothing and amplitude/prominence thresholds; parameters are configurable (see pro mode).

---

## Output
- TSV (`--rdf-out`):
  - Columns: `r_A`, `g(all)` or `g(i-j)`; with `--shell-column`: `shell(all)` or `shell(i-j)` added alongside.
  - Units: r in Å; g(r) dimensionless; `shell` in 1/Å (dimensionless×Ų×1/ų yields 1/Å).
- CSV (`--stats-out`): `curve, r_peak_A, r_min_A, n1, dr_A`.
- Console: one line per curve with `r_peak`, `r_min`, `n1`, and `dr`.

---

## Examples
```bash
# Overall RDF, default cut-off, smooth output (0.15 Å), save plots and stats
guru-rdf -x XDATCAR --smooth-r 0.15 \
  --rdf-out rdf.tsv --plot rdf.png --plot-shell shell.png --mark-extrema \
  --stats-out rdf_stats.tsv
```
```bash
# Partial RDFs for species 1-1 and 1-2, tighter peak detection, n1 from raw g(r)
guru-rdf -x XDATCAR --pair 1-1 --pair 1-2 \
  --peak-min-r 0.7 --peak-smooth-r 0.2 --peak-amp-frac 0.5 --peak-prom-frac 0.15 \
  --smooth-r 0.10 --n1-from-raw --rdf-out rdf.tsv --plot rdf.png --stats-out rdf_stats.tsv
```
```bash
# Use shell-density minimum for n1 boundary and include shell columns in TSV
guru-rdf -x XDATCAR --n1-bound shell --shell-column --rdf-out rdf.tsv
```
```bash
# Multi‑segment trajectory (concatenate two XDATCAR files)
guru-rdf -x XDATCAR_part1 XDATCAR_part2 \
  --rdf-out rdf.tsv --stats-out rdf_stats.tsv --plot rdf.png --mark-extrema
```

---

## Troubleshooting
- “No frames selected” — relax `--skip/--stride/--end`.
- “Peaks at tiny r” — increase `--peak-min-r` and/or use `--peak-smooth-r` and higher amplitude/prominence thresholds.
- Jagged curves (low statistics) — increase `--smooth-r`, or raise `--end` / lower `--stride`.

---

## Performance Tips
- The algorithm streams frames and bins distances in blocks; memory scales with `bins` and species sizes, not with frames.
- Keep `rmax` conservative to reduce pair counts; default heuristic is safe for most cells.

---

## Units
- r in Å; volume in ų; ρ in 1/ų; g(r) dimensionless; `s(r) = 4πρ r² g(r)` in 1/Å; `n1` dimensionless.