# GURU — Chain Analysis Manual (EN)

Purpose. Analyze polymer/chain connectivity in VASP XDATCAR trajectories and report histograms of chain lengths (≥2) and ring sizes (≥3). Bonds are defined by a cutoff distance `R_bond` (Å) provided explicitly or derived from RDF stats.

---

## Synopsis
```bash
# Run as a module
python -m guru.chain_analysis -x XDATCAR1 [XDATCAR2 ...] \
  (--r-bond R | --rdf-stats rdf_stats.tsv) \
  [--skip N] [--stride K] [--end N] \
  [--min-chain-length L] [--segments S] \
  [--out-chains chains.tsv] [--out-rings rings.tsv] \
  [--progress|--no-progress] [--quiet]
```

Multi‑file input
- `-x` accepts one or more XDATCAR paths. Frames are concatenated into a single
  stream with a continuity warning if the first frame of the next file does not
  match the last frame of the previous. `--skip/--stride/--end` apply after
  concatenation. The lattice from the first file is used.

Inputs
- XDATCAR trajectory (fractional coordinates). Use multiple files to stitch segments.
- Bond cutoff:
  - `--r-bond R` — explicit bond cutoff in Å; or
  - `--rdf-stats rdf_stats.tsv` — TSV from `guru-rdf --stats-out` (uses `r_min_A` for curve `all`).

Options
- `--skip/--stride/--end` — frame windowing and sub‑sampling.
- `--min-chain-length L` — minimal chain length to count (default 2; excludes dimers if set >2).
- `--segments S` — split the used frames into S contiguous segments, average histograms in each segment, then report the mean over segments (stability across time).
- `--out-chains` / `--out-rings` — output TSV paths (defaults: `chains.tsv`, `rings.tsv`).
- `--progress|--no-progress`, `--quiet` — control console output.

Outputs
- Chains TSV (`--out-chains`): columns `chain_length\tavg_count\tavg_fraction`.
  - `avg_count` — average per‑frame count of chains of a given length, averaged over segments.
  - `avg_fraction` — within each segment/frame, fraction among all chains; then averaged over segments.
- Rings TSV (`--out-rings`): columns `ring_size\tavg_count\tavg_fraction` (analogous definitions).

Notes
- Ring nodes are removed before chain extraction to focus on trunk segments.
- Species counts must be consistent across all XDATCAR files.

Examples
```bash
# Derive R_bond from RDF stats and analyze two trajectory segments
guru-rdf -x XDATCAR_part1 XDATCAR_part2 --stats-out rdf_stats.tsv
python -m guru.chain_analysis -x XDATCAR_part1 XDATCAR_part2 \
  --rdf-stats rdf_stats.tsv --segments 3 \
  --out-chains chains.tsv --out-rings rings.tsv --progress
```
```bash
# Use explicit bond cutoff and restrict to every 5th frame
python -m guru.chain_analysis -x XDATCAR --r-bond 2.2 \
  --stride 5 --out-chains chains.tsv --out-rings rings.tsv
```