# GURU — General Unified Research Utilities for Thermophysics

![Version](https://img.shields.io/badge/version-1.63-blue)
_Текущая версия: 1.63_

![GURU Logo](guru-logo-glow-micro.png)

Reproducible thermophysics data processing (EOS, Hugoniot, Isentrope, Diffusion, Viscosity, etc.).

ГУРУ — Глобальный Универсальный Расчётно-аналитический Узел (Теплофизика)

Набор утилит для воспроизводимой обработки данных и оценки неопределённости (УРС, Гюгонио, изэнтропа, диффузия, вязкость и др.).

**GURU** — набор CLI‑утилит для обработки результатов MD/DFT (сейчас VASP; далее QE, ABINIT, LAMMPS) и расчёта термодинамических свойств, ударной адиабаты и смежных величин.

## Возможности

- `guru-thermo` — разбор `OUTCAR` или компактных логов, усреднение (T, P, E) на окне, расширенный TSV (объём ячейки, объём на атом, плотность, массы). Поддерживает склейку нескольких `OUTCAR` с проверками согласованности (NIONS, решётка, TEBEG, SIGMA, POTCAR). `--dry-run`, `--plot`.
- `guru-iso-fit` — аппроксимация изотерм/изохор и подбор точки при заданном давлении; реконструкция изобар из TSV/сетки; PCHIP‑интерполяции, графики.
- `guru-hugoniot` — фазо‑чувствительное решение ранкино‑гюгонио вдоль изотерм/изохор из TSV/сетки EOS; безопасные единицы СИ, графики.
- `guru-isentrope` — интегрирование изоэнтроп T(ρ) по сетке EOS; расчёт u(P) по пути или сетке по давлению; диагностика акустики; графики.
- `guru-msd` — MSD(t) и коэффициент самодиффузии из одного или нескольких `XDATCAR` (+ `POTIM` из `OUTCAR`); устойчивый PBC‑анфолдинг; авто/ручной выбор окна; графики.
- `guru-rdf` — g(r) (общая и парциальные) из одного или нескольких `XDATCAR`; сглаживание, устойчивый поиск пика/минимума, n1 по g(r) или `4πρ r² g(r)`; графики.
- `guru-thermo-phase` — присвоение фаз термо‑таблице по диффузии из `guru-msd`; безопасный разбор TSV.
- `guru-equil` — оценка выхода на равновесие по `guru-thermo --dump-log` (окно без тренда относительно флуктуаций).
- `guru-mc-fit` — Монте‑Карло/джекнайф‑оценки и подгонка на P–u; выбор моделей/фаз; графики и отчёты.
- `guru-prop-along` — выборка P,E и др. свойств вдоль заданного пути T–ρ по сетке EOS; графики Q–ρ, Q–T, опционально Q–P.
- `guru-tsv-cat` — объединение/фильтрация TSV‑файлов и подготовка прямоугольной EOS‑сетки (режим `--mode grid`) для расчётов `guru-isentrope`/`guru-hugoniot`.
- `guru-chains` (опц.) — анализ цепей/колец в траекториях `XDATCAR`, усреднение гистограмм по сегментам.
- `guru-viscosity` — оценка вязкости (динамической/кинематической) по Стоксу–Эйнштейну: `D` из `guru-msd`, `r_peak` из `guru-rdf --stats-out`, `T` (и ρ) из `guru-thermo`.

## Что нового

- Поддержка нескольких `OUTCAR` в `guru-thermo` с проверками согласованности (NIONS, прямые векторы, TEBEG, SIGMA, POTCAR/TITEL).
- Поддержка нескольких `XDATCAR` в `guru-msd`, `guru-rdf`, `guru-chains` (склейка сегментов с проверкой непрерывности).
- Новый общий модуль `guru/outcar.py` с утилитами: чтение `POTIM`, «отпечаток» системы и проверка согласованности множества OUTCAR.
- Обновлены мануалы (EN/RU) для MSD/RDF/thermo/chain_analysis, добавлены примеры многосегментных входов.
- `guru-chains` (опц.) — анализ цепей/колец по траектории `XDATCAR` с порогом связи, усреднение гистограмм по сегментам.

## Установка и окружение

Рекомендуется использовать отдельное виртуальное окружение Python ≥3.8/3.9.

```bash
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# .\venv\Scripts\activate  # Windows PowerShell

pip install --upgrade pip
pip install -e .

# Дополнительные утилиты (mc-fit, chain-analysis)
# Устанавливаются по специальному указанию через переменную окружения:
# (добавляются скрипты guru-mc-fit и guru-chains)
GURU_WITH_EXTRAS=1 pip install -e .
```

### Зависимости

- numpy
- scipy
- matplotlib (для графиков; опционально, но рекомендовано)

### Опциональные зависимости

Для удобства можно установить дополнительный набор пакетов из файла `requirements-optional.txt`:

```bash
pip install -r requirements-optional.txt
```

В него входят:
- `matplotlib` — построение графиков в модулях `guru-thermo`, `guru-msd`, `guru-rdf`, `guru-mc-fit`, `guru-iso-fit`.
- `tqdm` — красивый прогресс‑бар (если не установлен, используется лёгкий текстовый индикатор).

## Использование (примеры)

```bash
# Версия пакета
guru --version

# Усреднение термодинамических данных (один OUTCAR)
guru-thermo -i OUTCAR --skip 500 --out stats.tsv --dump-log ep_log.tsv --plot thermo.png

# Склейка нескольких OUTCAR (возобновлённый QMD)
guru-thermo -i OUTCAR_part1 OUTCAR_part2 --skip 500 --out stats.tsv --dump-log ep_log.tsv

# MSD и диффузия (авто-окно фита)
guru-msd -x XDATCAR -o OUTCAR --msd-log msd.tsv --diff-out D.tsv --plot msd.png

# MSD по нескольким XDATCAR (склейка сегментов)
guru-msd -x XDATCAR1 XDATCAR2 XDATCAR3 -o OUTCAR --msd-log msd.tsv --diff-out D.tsv

# Фазовая метка по диффузии
guru-thermo-phase --thermo thermo.tsv --msd D.tsv -o thermo_with_phase.tsv --print

# Аппроксимация изохоры
guru-iso-fit --mode isochor --degree 2 --pressure 0 -i data/300K.tsv -o ep0.tsv --plot

# Решение уравнения Гюгонио
guru-hugoniot --initial ep0.tsv --Ma 63.5 -i data/*.tsv -o hugo.tsv

# Объединение нескольких TSV
guru-tsv-cat -o all_data.tsv data/*.tsv

# Монте‑Карло импеданс‑согласование
guru-mc-fit -i HUG_PBE.tsv -i HUG_LDA.tsv \
  --model-choice weighted --model-probs 0.6 0.4 \
  --phase-choice union --degree 2 --resample jackknife \
  --w 5 --sigma-w 0.1 --D 7 --sigma-D 0.1 --rho0 10 --sigma-rho0 0.1 \
  --samples 20000 --plot --plot-prefix results/mc

# RDF из XDATCAR (общая и парциальные)
guru-rdf -x XDATCAR --pair 1-1 --pair 1-2 --smooth-r 0.1 \
  --n1-bound shell --shell-column --rdf-out rdf.tsv --plot rdf.png --plot-shell shell.png --stats-out rdf_stats.tsv

# RDF по нескольким XDATCAR (склейка сегментов)
guru-rdf -x XDATCAR_part1 XDATCAR_part2 --rdf-out rdf.tsv --stats-out rdf_stats.tsv --plot rdf.png --mark-extrema

# Построить прямоугольную сетку EOS из «рассеянных» TSV
guru-tsv-cat --mode grid -o EOS_grid.tsv thermo/*.tsv --tol-T 5 --tol-rho 0.01

# Оценка выхода на равновесие
guru-thermo -i OUTCAR --dump-log ep_log.tsv
guru-equil -i ep_log.tsv --columns P_sum,E_sum --min-window 200 --drift-ratio 0.3 --out equil.tsv --plot equil.png

# Изоэнтропа и u(P)
guru-isentrope -i EOS.tsv --Ma 28 --T0 300 --rho0 0.8 --drho -0.01 --nmax 600 \
  --stop-P-le 0 --extrap-frac 0.1 \
  -o iso.tsv --out-velocity pu.tsv --u0 1.0 --vel-mode path --diag-out diag.tsv

# Свойство вдоль пути (например, проводимость вдоль изоэнтропы)
guru-prop-along -g thermo_rich.tsv --prop sigma \
  --path iso.tsv -o iso_with_sigma.tsv \
  --plot --plot-prefix iso_sigma
```

После установки в режиме `-e .` все CLI‑команды  
(`guru`, `guru-thermo`, `guru-iso-fit`, `guru-hugoniot`, `guru-tsv-cat`, `guru-mc-fit`, `guru-msd`, `guru-thermo-phase`, `guru-rdf`, `guru-viscosity`)  
будут доступны напрямую из терминала.

## Документация

- 📄 Общий PDF: [guru_manual.pdf](guru_manual.pdf)  
- 📝 Общий Markdown: [guru_manual.md](guru_manual.md)  
- 📚 Подробные мануалы по отдельным скриптам — каталог `manuals/`
  - Thermo: [EN](manuals/guru_thermo_manual_en.md) / [RU](manuals/guru_thermo_manual_ru.md)
  - Hugoniot: [EN](manuals/guru_hugoniot_manual_en.md) / [RU](manuals/guru_hugoniot_manual_ru.md)
  - Iso‑fit: [EN](manuals/guru_iso_fit_manual_en.md) / [RU](manuals/guru_iso_fit_manual_ru.md)
  - Isentrope: [EN](manuals/guru_isentrope_manual_en.md) / [RU](manuals/guru_isentrope_manual_ru.md)
  - MSD: [EN](manuals/guru_msd_manual_en.md) / [RU](manuals/guru_msd_manual_ru.md)
  - RDF: [EN](manuals/guru_rdf_manual_en.md) / [RU](manuals/guru_rdf_manual_ru.md)
  - Phase tagging: [EN](manuals/guru_phase_tag_manual_en.md) / [RU](manuals/guru_phase_tag_manual_ru.md)
  - Equilibration: [EN](manuals/guru_equil_manual_en.md) / [RU](manuals/guru_equil_manual_ru.md)
  - Prop along: [EN](manuals/guru_prop_along_manual_en.md) / [RU](manuals/guru_prop_along_manual_ru.md)
  - Monte‑Carlo fit: [EN](manuals/guru_mc_fit_manual_en.md) / [RU](manuals/guru_mc_fit_manual_ru.md)
  - TSV cat: [EN](manuals/guru_tsv_cat_manual_en.md) / [RU](manuals/guru_tsv_cat_manual_ru.md)
  - Chain analysis: [EN](manuals/guru_chain_analysis_manual_en.md) / [RU](manuals/guru_chain_analysis_manual_ru.md)

## Лицензия

Этот проект распространяется по лицензии **GNU General Public License v3.0 (GPL‑3.0)**.  
Вы можете свободно использовать, модифицировать и распространять программу при условии сохранения той же лицензии.

См. https://www.gnu.org/licenses/gpl-3.0.html для деталей.