# GURU — руководство по `guru-msd` (RU)

**Назначение.** Вычисляет **среднеквадратичное смещение** (MSD) и **коэффициент самодиффузии** по `XDATCAR` вместе с `POTIM` из `OUTCAR`. Работает для произвольных триклинных ячеек и использует разворачивание во фракционном пространстве с учётом ПГУ.

---

## Синтаксис
```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]
```

**Параметры**
- `--skip/--stride/--end` — прореживание кадров.
- `--indices` — подвыборка атомов в виде диапазонов с 1 (например, `1-32,60,100-120`).
- `--fit auto` — перебор окон на хвосте и выбор с наилучшим R², при условии что окно содержит не менее доли `--min-tail-frac` точек.
- `--fit window` — ручное окно, начиная с `--fit-start` fs; если `--fit-end` не задан, подгонка идёт **до конца**.
- `--dry-run` — лишь сообщает число кадров, атомов, `POTIM`, общее и эффективное (после прореживания) время и завершает работу.
- `--progress` / `--no-progress` — включить/выключить индикатор прогресса в stderr (авто‑включение для TTY, если не задан `--quiet`). При наличии `tqdm` используется прогресс‑бар, иначе — простой текстовый индикатор.

**Выходные файлы**
- `--msd-log` — столбцы `step  t_fs  MSD_A2`.
- `--diff-out` — наклон, `D` в Ų/fs, м²/с и 10⁻⁹ м²/с, вместе со стандартной ошибкой и границами окна подгонки.
- `--plot` — PNG с точками MSD и нанесённой прямой только на выбранном окне.

---

## Методика
- Фракционные смещения с учётом ближайшего изображения: `Δs = (s_t − s_{t-1}) − round(s_t − s_{t-1})`, накапливается `S_t`.
- Метрический тензор `G = L Lᵀ` из первой строки POSCAR в `XDATCAR` (Ų).
- `MSD(t) = ⟨ S_tᵀ G S_t ⟩_atoms`.
- Диффузия в 3D: `MSD ≈ 6 D t` ⇒ `D = slope / 6`.

---

## Примеры
```bash
# Автоматический выбор окна
guru-msd -x XDATCAR -o OUTCAR --msd-log msd.tsv --diff-out D.tsv --plot msd.png

# Ручное окно от 10 пс до конца
guru-msd -x XDATCAR -o OUTCAR --fit window --fit-start 10000 --plot msd.png

# Только оценить длину траектории и шаг по времени
guru-msd -x XDATCAR -o OUTCAR --skip 100 --stride 5 --dry-run

# Многосегментная траектория (два файла XDATCAR)
guru-msd -x XDATCAR_part1 XDATCAR_part2 -o OUTCAR \
         --msd-log msd.tsv --diff-out D.tsv --plot msd.png
```

---

## Диагностика
- **Недостаточно кадров** — увеличьте длину симуляции или ослабьте `--skip/--stride/--end`.
- **Нелинейный хвост MSD** — увеличьте `--fit-start` или используйте `--fit auto`, чтобы выбрать более поздний сегмент.

---

## Советы по производительности
- Применяйте `--indices`, чтобы ограничить дорогое разворачивание/усреднение мобильными видами (например, лёгкими ионами).
- При очень длинных траекториях лучше писать лог MSD и строить графики отдельно, чтобы снизить нагрузку на память.