# GURU — руководство по `guru-rdf` (RU) **Назначение.** Вычисление радиальной функции распределения g(r) из траекторий VASP `XDATCAR` с учётом ПГУ для произвольных триклинных ячеек. Поддерживаются общая и парциальные RDF g_{αβ}(r), опциональное сглаживание, устойчивый поиск пика/минимума, расчёт координационного числа первой оболочки и построение графиков. --- ## Синтаксис ```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] ``` Ввод из нескольких файлов - `-x` принимает один или несколько путей к XDATCAR. Кадры объединяются по порядку; при несоответствии первого кадра следующего файла последнему кадру предыдущего выводится предупреждение (проверка непрерывности). `--skip/--stride/--end` применяются уже после объединения. Решётка берётся из первого файла. --- ## Входные данные - `XDATCAR` (VASP) с фракционными координатами по кадрам. Заголовок POSCAR‑типа используется для чтения решётки, числа ионов по видам и общего числа ионов. - Предполагается фиксированная ячейка по кадрам (типично для `XDATCAR`). Если ячейка меняется, свяжитесь с авторами. --- ## Опции - Окно по кадрам: - `--skip N` — пропустить первые N кадров; `--stride K` — брать каждый K‑й кадр; `--end N` — использовать не более N выбранных кадров. - Выбор пар (многокомпонентный случай): - `--pair i-j` — пары видов по 1‑основанным порядковым из заголовка; можно повторять или перечислять через запятую. Если не задано, считается общая g(r) по всем атомам. - Биннинг и отсечка: - `--rmax R` (Å) — максимальный радиус; по умолчанию `~0.48*min(|a|,|b|,|c|)`. - `--bins M` — количество бинов (равномерный шаг); шаг вывода `dr = rmax / M`. - Сглаживание и интегрирование: - `--smooth-r L` (Å) — сглаживание скользящим средним для выходной g(r) и графиков; `0` отключает. - `--n1-from-raw` — интегрировать n1 по «сырой» g(r), даже если включено сглаживание. - Граница первой оболочки: - `--n1-bound rdf|shell` — выбирать `r_min` как минимум g(r) (`rdf`) или минимума «локальной плотности соседей» `4πρ r² g(r)` (`shell`). По умолчанию `rdf`. - Поиск пика/минимума (pro‑режим): - `--peak-min-r R0` — игнорировать r < R0 при поиске первого пика (по умолчанию 0.5 Å). - `--peak-smooth-r Lp` — сглаживание только для детекции пика (по умолчанию 0.1 Å; `0` — без сглаживания). - `--baseline-tail-frac f` — доля хвоста для оценки базовой линии на больших r (по умолчанию 0.2). - `--peak-amp-frac af`, `--peak-amp-abs a0` — минимальная высота пика относительно базы и абсолютная (по умолчанию 0.4, 0.1). - `--peak-prom-frac pf`, `--peak-prom-abs p0` — минимальная «выдача» над локальным фоном относительно базы и абсолютная (по умолчанию 0.1, 0.05). - Выводы: - `--rdf-out rdf.tsv` — таблица с `r_A`, `g(curve)`; при `--shell-column` добавляются столбцы `shell(curve) = 4πρ r² g(r)`. - `--stats-out stats.tsv` — сводка по кривым (TSV): `curve, r_peak_A, r_min_A, n1, dr_A`. - `--plot` — PNG для g(r). `--plot-shell` — PNG для `4πρ r² g(r)`. `--mark-extrema` — вертикальные линии в `r_peak` (точечная) и `r_min` (штриховая). - Прочее: - `--dry-run` — вывести информацию о кадрах, видах, объёме, `rmax`, `bins` и выйти. - `--quiet` — тихий режим. - `--progress` / `--no-progress` — включить/выключить индикатор прогресса в stderr (авто‑включение для TTY, если не задан `--quiet`). При наличии `tqdm` используется прогресс‑бар, иначе — простой текстовый индикатор. --- ## Методика - Расстояния с ПГУ через метрический тензор: для решётки L (строки a,b,c, Å) `G = L Lᵀ`. - Пары бинируются в равномерные интервалы `[0, rmax]` шириной `dr`. - Нормировка (общая или парциальная αβ) даёт g(r). Локальная «плотность соседей» на оболочке радиуса r: $$ s(r) = 4\pi\,\rho\, r^2\, g(r), \quad \rho = \frac{N}{V}. $$ - Координационное число первой оболочки $$ n_1 = 4\pi\,\rho \int_{0}^{r_{\min}} r^2 g(r)\,\mathrm{d}r, $$ где `r_min` — первый минимум g(r) или s(r) (по `--n1-bound`). - Поиск пика/минимума устойчив к шуму на малых r за счёт сглаживания и порогов по амплитуде/выдаче; пороги настраиваются. --- ## Выходные данные - TSV (`--rdf-out`): - Столбцы: `r_A`, `g(all)` или `g(i-j)`; при `--shell-column` рядом добавляются `shell(all)` или `shell(i-j)`. - Единицы: r в Å; g(r) безразмерна; `shell` — в 1/Å. - TSV (`--stats-out`): `curve, r_peak_A, r_min_A, n1, dr_A`. - Консоль: по строке на кривую с `r_peak`, `r_min`, `n1`, `dr`. --- ## Примеры ```bash # Общая RDF, сглаживание 0.15 Å, графики и сводка 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 # Парциальные RDF 1-1 и 1-2, более строгая детекция пиков, n1 по «сырой» 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 # Граница n1 по минимуму «плотности соседей» и вывод столбцов shell в TSV guru-rdf -x XDATCAR --n1-bound shell --shell-column --rdf-out rdf.tsv ``` ```bash # Многосегментная траектория (два файла XDATCAR) guru-rdf -x XDATCAR_part1 XDATCAR_part2 \ --rdf-out rdf.tsv --stats-out rdf_stats.tsv --plot rdf.png --mark-extrema ``` --- ## Диагностика - «No frames selected» — ослабьте `--skip/--stride/--end`. - «Ложные пики при малых r» — увеличьте `--peak-min-r` и/или используйте `--peak-smooth-r` с более высокими порогами амплитуды/выдачи. - «Зубчатая» g(r) — увеличьте `--smooth-r` или повысить статистику (увеличить `--end`, уменьшить `--stride`). --- ## Советы по производительности - Алгоритм потоково читает кадры и бинирует попарные расстояния; память растёт с `bins` и размерами видов, а не с числом кадров. - Держите `rmax` умеренным, чтобы уменьшить число пар; значение по умолчанию безопасно. --- ## Единицы измерения - r — Å; объём — ų; ρ — 1/ų; g(r) — безразмерная; `s(r) = 4πρ r² g(r)` — 1/Å; `n1` — безразмерное.