# GURU — Руководство по анализу цепей (RU)

Назначение. Анализ связности (цепи/кольца) в траекториях VASP XDATCAR и вывод гистограмм длин цепей (≥2) и размеров колец (≥3). Связи определяются по порогу расстояния `R_bond` (Å), заданному явно или полученному из статистики RDF.

---

## Синтаксис
```bash
# Запуск модулем
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]
```

Ввод из нескольких файлов
- `-x` принимает один или несколько путей к XDATCAR. Кадры объединяются в единую
  последовательность; при стыковке сегментов выводится предупреждение, если первый
  кадр следующего файла не совпадает с последним кадром предыдущего. `--skip/--stride/--end`
  применяются после объединения. Решётка берётся из первого файла.

Входные данные
- Траектории XDATCAR (фракционные координаты). Можно указывать несколько файлов для сшивки сегментов.
- Порог связи:
  - `--r-bond R` — явный порог связи в Å; или
  - `--rdf-stats rdf_stats.tsv` — TSV из `guru-rdf --stats-out` (берётся `r_min_A` для кривой `all`).

Опции
- `--skip/--stride/--end` — окно по кадрам и прореживание.
- `--min-chain-length L` — минимальная длина цепи для учёта (по умолчанию 2; исключает димеры при L>2).
- `--segments S` — разбить выбранные кадры на S непрерывных сегментов, усреднить гистограммы по сегментам и вывести средние значения (устойчивость во времени).
- `--out-chains` / `--out-rings` — пути к выходным TSV (по умолчанию `chains.tsv`, `rings.tsv`).
- `--progress|--no-progress`, `--quiet` — управление выводом.

Выходные файлы
- Chains TSV (`--out-chains`): столбцы `chain_length\tavg_count\tavg_fraction`.
  - `avg_count` — среднее по кадрам число цепей данной длины, затем усреднение по сегментам.
  - `avg_fraction` — доля таких цепей среди всех цепей в кадре/сегменте, затем усреднение по сегментам.
- Rings TSV (`--out-rings`): столбцы `ring_size\tavg_count\tavg_fraction` (аналогично).

Примечания
- Узлы, входящие в кольца, исключаются перед выделением цепей (выделяются «ствольные» сегменты).
- Число частиц по видам должно совпадать во всех файлах XDATCAR.

Примеры
```bash
# R_bond из RDF и анализ двух сегментов
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
# Явный порог связи и каждую 5‑ю конфигурацию
python -m guru.chain_analysis -x XDATCAR --r-bond 2.2 \
  --stride 5 --out-chains chains.tsv --out-rings rings.tsv
```