# Project Name
GURU — General Unified Research Utilities for Thermophysics

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

# Core Idea
GURU is a collection of CLI utilities for reproducible thermophysics data processing and uncertainty evaluation from VASP MD/DFT (primarily OUTCAR/XDATCAR) and downstream physics. It standardizes inputs/outputs as TSVs, builds shape‑preserving interpolators over T–ρ grids, and solves problems such as Rankine–Hugoniot loci, isentropes, isotherm/isochor fits, and property sampling. Utilities cover diffusion (MSD), RDF, phase tagging, Monte‑Carlo fitting, and piping TSV data between steps. Most tools support progress reporting, plotting, and rich TSV outputs for reproducibility.

# Version
Current: 1.63

# Modules
Navigation:
- [hugoniot.py](#hugoniotpy)
- [iso_fit.py](#iso_fitpy)
- [isentrope.py](#isentropepy)
- [thermo.py](#thermopy)
- [msd_diffusion.py](#msd_diffusionpy)
- [rdf.py](#rdfpy)
- [phase_tag.py](#phase_tagpy)
- [equil.py](#equilpy)
- [mc_fit.py](#mc_fitpy)
- [prop_along.py](#prop_alongpy)
- [chain_analysis.py](#chain_analysispy)
- [tsv_cat.py](#tsv_catpy)
- [interp_utils.py](#interp_utilspy)
- [progress.py](#progresspy)
- [invoke_log.py](#invoke_logpy)
- [xdatcar.py](#xdatcarpy)
- [outcar.py](#outcarpy)
- [viscosity.py](#viscositypy)
- thermo.py — Parse OUTCAR or compact logs, compute windowed statistics (T, P, E), optionally emit rich TSV and per‑step logs. Supports concatenating multiple OUTCAR segments with consistency checks (NIONS, lattice, TEBEG, SIGMA, POTCAR).
- hugoniot.py — Phase‑aware Hugoniot solver along isotherms/isochors from TSVs or EOS grid; progress, compact output, and plots.
- iso_fit.py — Fit isotherm/isochor to reach a target pressure; reconstruct isobars from TSVs or a grid; progress and plots.
- isentrope.py — Integrate isentropic paths T(ρ) from an EOS grid and compute mass velocity u(P); optional diagnostics and plots.
- msd_diffusion.py — Compute MSD and self‑diffusion coefficient from XDATCAR (+POTIM from OUTCAR); logs, fits, and plots.
- rdf.py — Compute radial distribution functions g(r) from XDATCAR, including partials and shell density; optional plots.
- phase_tag.py — Phase tagging of thermo TSV rows; produces phase column for phase‑aware solvers.
- equil.py — Equilibration assessment utilities (see manual) for thermo datasets.
- mc_fit.py — Monte‑Carlo fitting over datasets (sampling, statistics).
- prop_along.py — Sample properties along supplied T–ρ paths using an EOS grid.
- chain_analysis.py — Analyze polymer/chain structures along trajectories.
- tsv_cat.py — Concatenate/transform TSV files; small CLI for table ops.
- interp_utils.py — Common interpolation helpers: PCHIP2D, grid readers, clamped bispline extrapolation.
- progress.py — Unified progress wrapper (tqdm fallback) for consistent CLI UX.
- invoke_log.py — Append invocation metadata (guru.log) near outputs for provenance.
- xdatcar.py — Shared XDATCAR parsing utilities.
- outcar.py — Shared OUTCAR utilities: POTIM reader, static fingerprint, and multi‑file consistency checks.
- viscosity.py — Viscosity estimation (SE variant): uses D from guru‑msd, r_peak from guru‑rdf stats, T (and rho) from guru‑thermo.

# hugoniot.py
**Key Classes/Functions**
- main(argv) — CLI entry: reads initial state, groups curves, solves Hugoniot, writes TSVs and plots.
- dhug(E,E0,P,P0,V,V0,Ma) — Rankine–Hugoniot residual in SI per atom.
- Pchip2D (from interp_utils) — Shape‑preserving 2D interpolator used in grid mode.

**Dependencies**
- numpy, scipy (constants, interpolate, optimize)
- interp_utils.Pchip2D, progress.Progress, invoke_log.append_invocation
- TSV inputs from guru-thermo; optional phase column from guru-thermo-phase

**Constraints**
- Physics units must be consistent (eV/atom, kbar, cm³/g with Ma).
- Prefer in‑range roots; extrapolation is allowed but marked. Grid scans must avoid ρ=0 and negative T when base grid is non‑negative.

**Minimal TSV Example(s)**
- Full TSV:
  curve_type	label	P[kbar]	T[K]	rho[g/cm^3]	is_extrapolated	phase	rho/rho0	D[km/s]	U[km/s]

  isotherm	T=300.0K	100.000000	300.000000	2.100000	0	-1	1.120000	5.230000	1.700000
- Compact TSV:
  P[kbar]	T[K]	rho[g/cm^3]	D[km/s]	U[km/s]

  100.000000	300.000000	2.100000	5.230000	1.700000

**Entry Points**
- `guru-hugoniot --Ma 20.18 -i thermo.tsv --curves both -o hug.tsv --progress --plot`
- `guru-hugoniot --Ma 20.18 --grid-eos EOS.tsv --grid-init-T 300 --grid-init-rho 2.1 --curves iso -o hug.tsv`

**Context Hints**
- Key flags: `--Ma`, `--initial` or `--grid-eos`, `--grid-init-T/--grid-init-rho`, `--P0/--E0` (override initial), `--curves`, `--group-dT/--group-drho`, `--interp`, `-o`, `--out-compact`, `--plot`, `--progress`, `--u0` (double‑shock particle speed adjustment).
- In: thermo TSV(s) or EOS grid TSV; Out: full TSV (+compact TSV), plots


# iso_fit.py
**Key Classes/Functions**
- main(argv) — Fits isotherm/isochor at target P or reconstructs isobar from TSVs/grid.
- poly_fit_and_invert — Polynomial fits and bracketing/bisection root for P(x)=P*.
- Points isobar: per‑curve PCHIP on grouped isotherms/isochors (by --tol-T/--tol-rho), bracketing + brentq; optional PCHIP of the union.

**Dependencies**
- numpy, scipy (optimize, interpolate)
- interp_utils (grid reader, PCHIP2D), progress.Progress, invoke_log
- TSV inputs from guru-thermo; grid TSV (T,ρ,P,E) for grid mode

**Constraints**
- Forbid extrapolated negative‑temperature solutions in points‑isobar mode.
- Grouping tolerances are split: `--tol-T` (K) and `--tol-rho` (g/cm³). Require ≥2 points per curve.

**Minimal TSV Example(s)**
- Isotherm one‑line:
  T	P	E	V	rho	mode	degree

  300.000000	200.000000	-0.020000	0.476190	2.100000	isotherm	2
- Isochor one‑line:
  rho	P	E	T	mode	degree

  2.100000	0.000000	-0.019000	100.000000	isochor	2
- Isobar points:
  T	rho	P	E	is_extrapolated

  300.000000	2.050000	1000.000000	-0.120000	0

**Entry Points**
- `guru-iso-fit --mode isotherm --degree 2 --pressure 200 -i T300.tsv -o init_T300.tsv --tol-T 10`
- `guru-iso-fit --mode isobar --pressure 1000 -i tsv/*.tsv -o isobar.tsv --tol-T 10 --tol-rho 0.01`

**Context Hints**
- Key flags: `--mode`, `--degree`, `--pressure`, `-i`, `-o`, `--tol-T`, `--tol-rho`, `--isobar-allow-extrap`, `--isobar-fit-out`, `--isobar-fit-n`, `--plot`, `--progress`
- In: thermo TSV(s) or EOS grid TSV; Out: one‑line init TSV (iso*), multi‑line isobar TSV, optional fit TSV, plots


# isentrope.py
**Key Classes/Functions**
- main(argv) — Integrates isentrope from EOS grid; writes path and optional u(P) TSVs and plots.
- Pchip2D — Grid interpolation for P(T,ρ), E(T,ρ); acoustic diagnostics helpers.
- compute_mass_velocity_path/grid — u(P) along path or uniform P grid.

**Dependencies**
- numpy, scipy (interpolate splines), interp_utils.Pchip2D, progress.Progress

**Constraints**
- Keep unit conversions explicit (eV/atom, kbar, g/cm³). Respect extrapolation bounds and stop conditions.

**Minimal TSV Example(s)**
- Path:
  T	rho	P	E_atom

  300.0	2.10	100.0	-0.0189
- u(P) path:
  P[kbar]	u[km/s]

  5.0	0.10

**Entry Points**
- `guru-isentrope -i EOS.tsv --Ma 20.18 --T0 300 --rho0 2.1 --drho 0.01 -o iso.tsv --out-velocity u.tsv --plot`

**Context Hints**
- Key flags: `-i`, `--Ma`, `--T0`, `--rho0`, `--drho`, `--nmax`, `--out`, `--out-velocity`, `--diag-out`, `--plot`, `--progress`
- In: EOS TSV; Out: path TSV (T,rho,P,E), optional u(P) TSV, plots


# thermo.py
**Key Classes/Functions**
- main(argv) — Parse OUTCAR/TSV logs, compute window statistics, logs, plots.
- OUTCAR readers; per‑step dump; rich TSV writer with structure fields (density, volumes, NIONS).

**Dependencies**
- numpy, optional matplotlib; VASP OUTCAR format knowledge; progress.Progress

**Constraints**
- Strict mode must abort on missing fields in averaging window. Preserve units and column names as documented.

**Minimal TSV Example(s)**
- Compact stdout:
  T	P	E

  300.0	12.3	-0.0189
- Rich `--out`:
  T_mean	P_mean	E_atom_mean	density_g_cm3	N_used

  300.1	12.28	-0.01890	8.900	1500

**Entry Points**
- `guru-thermo -i OUTCAR --out thermo.tsv --dump-log ep_log.tsv --plot --progress`

**Context Hints**
- Key flags: `-i`, `--format`, `--skip/--end/--maxrows`, `--out`, `--dump-log`, `--plot`, `--progress`
- In: OUTCAR or compact TSV with header; Out: compact stdout, rich TSV, per‑step log


# msd_diffusion.py
**Key Classes/Functions**
- main(argv) — Compute MSD and D from XDATCAR (+ POTIM from OUTCAR); optional plots.
- Unwrapping in fractional space; metric tensor G; linear fit with covariance.

**Dependencies**
- numpy, xdatcar helpers, progress.Progress; optional matplotlib

**Constraints**
- Robust to triclinic cells; accurate time handling via POTIM.

**Minimal TSV Example(s)**
- msd.tsv:
  step	t_fs	MSD_A2

  0	0.000000	0.0000000000
- diffusion.tsv:
  slope_A2_per_fs	D_A2_per_fs	D_m2_per_s	D_1e-9_m2_per_s	stderr_slope_A2_per_fs	stderr_D_m2_per_s	fit_start_fs	fit_end_fs	n_pts

  1.2e-3	2.0e-4	2.0e-9	2.000000	1.0e-4	1.7e-10	100.0	900.0	200

**Entry Points**
  - `guru-msd -x XDATCAR1 XDATCAR2 ... -o OUTCAR --msd-log msd.tsv --diff-out diffusion.tsv --plot --progress`

**Context Hints**
- Key flags: `-x XDATCAR1 XDATCAR2 ...`, `-o OUTCAR`, `--skip/--stride/--end`, `--msd-log`, `--diff-out`, `--plot`, `--progress`
- In: XDATCAR(s) (+OUTCAR); Out: msd.tsv, diffusion.tsv, optional plot


# rdf.py
**Key Classes/Functions**
- main(argv) — Compute RDF (total/partial), shell density, integrals; plots.
- Histogram kernel with PBC in fractional space; neighbor stats.

**Dependencies**
- numpy, xdatcar helpers, progress.Progress; optional matplotlib

**Constraints**
- Efficient block processing; safe handling of species pairs and cutoffs.

**Minimal TSV Example(s)**
- rdf.tsv:
  r_A	g_total

  1.50	0.05

**Entry Points**
  - `guru-rdf -x XDATCAR1 XDATCAR2 ... --rdf-out rdf.tsv --plot path.png --progress`

**Context Hints**
- Key flags: `-x XDATCAR`, `--pair`, `--rmax`, `--bins`, `--rdf-out`, `--plot`, `--progress`
- In: XDATCAR; Out: rdf.tsv (+ optional stats/out plots)


# phase_tag.py
**Key Classes/Functions**
- main(argv) — Tag phases in thermo TSVs, emit `phase` column for downstream tools.

**Dependencies**
- numpy/pandas (if used), TSV schema from guru-thermo

**Constraints**
- Non‑destructive enrichment: preserve existing headers, append phase.

**Minimal TSV Example(s)**
- Enriched TSV:
  ...	phase

  ...	1

**Entry Points**
- `guru-thermo-phase -i thermo.tsv -o thermo_with_phase.tsv`

**Context Hints**
- Key flags: `-i`, `-o`
- In: rich thermo TSV; Out: same TSV with `phase`


# equil.py
**Key Classes/Functions**
- CLI to assess equilibration from thermo logs (see manual); windowing and metrics.

**Dependencies**
- numpy, guru-thermo TSVs

**Constraints**
- Transparent criteria; don’t mutate inputs.

# mc_fit.py
**Key Classes/Functions**
- Monte‑Carlo sampling and fitting over datasets; progress, logging.

**Dependencies**
- numpy/scipy; progress.Progress

**Constraints**
- Reproducible sampling; careful random seeding where needed.

# prop_along.py
**Key Classes/Functions**
- Sample P,E along provided T–ρ path from an EOS grid; plotting support.

**Dependencies**
- numpy, interp_utils.Pchip2D; optional matplotlib

**Constraints**
- Respect grid bounds/extrapolation policy; document path format.

**Minimal TSV Example(s)**
- Sampled path:
  T	rho	P	E_atom

  300.0	2.10	100.0	-0.0189

**Entry Points**
- `guru-prop-along --grid-eos EOS.tsv --path path.tsv -o props.tsv`

**Context Hints**
- Key flags: `--grid-eos`, `--path`, `-o`, `--plot`
- In: EOS grid + path TSV; Out: sampled path TSV, plot


# chain_analysis.py
**Key Classes/Functions**
- Analyze chain/polymer metrics along trajectories; outputs TSV/plots.

**Dependencies**
- numpy; trajectory parsing helpers

**Constraints**
- Handle large trajectories efficiently; clear metrics definitions.

**Minimal TSV Example(s)**
- chains.tsv:
  chain_length\tavg_count\tavg_fraction

  5\t12.4\t0.083
- rings.tsv:
  ring_size\tavg_count\tavg_fraction

  6\t3.1\t0.021

**Entry Points**
- `python -m guru.chain_analysis -x XDATCAR1 XDATCAR2 ... --r-bond 2.2 --out-chains chains.tsv --out-rings rings.tsv --progress`

**Context Hints**
- Key flags: `-x XDATCAR1 XDATCAR2 ...`, `--r-bond` or `--rdf-stats`, `--skip/--stride/--end`, `--progress`
- In: XDATCAR(s); Out: chains.tsv (chain_length, avg_count, avg_fraction), rings.tsv (ring_size, avg_count, avg_fraction)

# tsv_cat.py
**Key Classes/Functions**
- Concatenate/filter/reshape TSVs; compose downstream inputs (e.g., for hugoniot/iso_fit).
- Grid mode: infer a rectangular EOS grid TSV (T, ρ, P, E) from scattered TSV rows; cluster by tolerances, fill a few missing cells by interpolation.

**Dependencies**
- Python stdlib (csv), numpy where relevant

**Constraints**
- Preserve headers; avoid lossy transformations by default.

**Minimal TSV Example(s)**
- Concatenated TSV:
  <same headers as inputs, rows appended>

**Entry Points**
- `guru-tsv-cat --glob "data/*.tsv" -o merged.tsv`

**Context Hints**
- Key flags: `--glob`, `-o`
- In: multiple TSVs; Out: concatenated TSV


# interp_utils.py
**Key Classes/Functions**
- Pchip2D — separable PCHIP evaluator with derivatives and vector evals.
- read_rect_grid_tsv — robust grid reader; clamped extrapolation helpers.

**Dependencies**
- numpy, scipy.interpolate

**Constraints**
- Shape‑preserving interpolation; explicit unit assumptions.

# progress.py
**Key Classes/Functions**
- Progress — unified progress bar with optional tqdm backend.

**Dependencies**
- Python stdlib; optional tqdm

**Constraints**
- Write to stderr; avoid excessive updates (mininterval).

# invoke_log.py
**Key Classes/Functions**
- append_invocation — write `guru.log` entries near outputs for provenance.

**Dependencies**
- Python stdlib (datetime, os, json-ish formatting)

**Constraints**
- Fail‑safe logging (never break the main flow if logging fails).

# xdatcar.py
**Key Classes/Functions**
- parse_poscar_header, iter_xdatcar_frames, count_xdatcar_frames — shared XDATCAR helpers.
- iter_xdatcar_frames_multi, count_xdatcar_frames_multi — multi-file trajectory helpers with optional continuity checks.

**Dependencies**
- numpy; text parsing

**Constraints**
- Streaming parsing; don’t load entire files into memory.

# Dependencies (Global)
- Python 3, numpy, scipy; optional matplotlib and tqdm.
- Inputs: VASP OUTCAR/XDATCAR; TSVs produced by guru-thermo and related tools.

# Constraints (Global)
- Preserve units and column schemas across modules.
- Prefer shape‑preserving interpolation (PCHIP) and robust bracketing/root finding (bisect/brentq).
- Avoid non‑physical regions (negative T or ρ) unless explicitly intended; mark extrapolations.
- Provide progress and provenance (progress bars, guru.log) for long‑running tasks.

# Module Snapshots (Ultra‑short)
- thermo: OUTCAR/TSV stats → compact/rich TSV; plots/progress.
- hugoniot: Solve RH along iso‑curves (TSV/grid); phase‑aware; safe SI residual.
- iso_fit: Fit isotherm/isochor to P*; reconstruct isobars (TSV/grid); plots.
- isentrope: Integrate isentropic T(ρ) on grid; u(P) diagnostics.
- msd: MSD/D from XDATCAR; PBC‑safe unwrapping; linear fit.
- rdf: g(r) total/partial + shell density; trajectory‑wide histograms.
- phase_tag: Add integer phase to thermo TSV rows.
- equil: Assess equilibration windows; simple metrics from thermo logs.
- mc_fit: Monte‑Carlo sampling/fitting; aggregates stats across datasets.
- prop_along: Probe EOS along provided T–ρ path; emits P,E.
- chain_analysis: Polymer/chain metrics along trajectories; TSV/plots.
- tsv_cat: Concatenate/filter TSVs; pipe data between tools.
- interp_utils: PCHIP2D + grid helpers; shape‑preserving.
- progress: Unified stderr progress; tqdm if available.
- invoke_log: Best‑effort CLI logging to guru.log near outputs.
- xdatcar: Streaming XDATCAR frame IO; header parsing.

# Overview Meta
- One‑liners (per tool)
  - thermo: Fast OUTCAR/TSV stats to compact or rich TSV with optional plots.
  - hugoniot: Phase‑aware RH solver from TSVs or EOS grid; safe units, progress, plots.
  - iso_fit: Fit iso‑curves to target P and reconstruct isobars from TSVs/grid.
  - isentrope: Integrate T(ρ) on EOS grid; optional u(P) diagnostics and plots.
  - msd: MSD and diffusion from XDATCAR; robust PBC, fit and plots.
  - rdf: Total/partial g(r) with shell density; XDATCAR, plots.
  - phase_tag: Add integer phase labels to thermo TSV rows.

- Supported modes/flags (high‑level)
  - Progress: `--progress/--no-progress` (stderr; tqdm fallback).
  - Plotting: `--plot[--plot-prefix]` saves PNGs where available.
  - Logging: guru.log near outputs; never breaks main flow.

# Data & Units
- T [K], P [kbar], E [eV/atom], ρ [g/cm³], V [cm³/g]; Ma [g/mol].
- Conversions: eV→J, kbar→Pa, cm³/g→m³/atom via Ma/NA.
- Guards: avoid ρ=0; forbid negative T in extrapolated paths where configured (iso_fit isobar). 

# I/O Schemas (TSV)
- thermo stdout (compact):
  T	P	E

  300.0	12.3	-0.0189

- thermo rich (`--out`):
  T_mean	P_mean	E_atom_mean	density_g_cm3	...

  300.1	12.28	-0.01890	8.90	...

- hugoniot (full):
  curve_type	label	P[kbar]	T[K]	rho[g/cm^3]	is_extrapolated	phase	...

  isotherm	T=300.0K	100.0	300.0	2.10	0	-1	...

- iso_fit isobar (points):
  T	rho	P	E	is_extrapolated

  300.0	2.05	1000	-0.12	0


# Entry Points (recipes)
- Extract thermo and rich TSV:
  `guru-thermo -i OUTCAR --out thermo.tsv --dump-log ep_log.tsv --plot --progress`
- Fit initial state (isotherm T≈300 K):
  `guru-iso-fit --mode isotherm --degree 2 --pressure 200 -i T300.tsv -o init_T300.tsv --tol-T 10 --plot`
- Hugoniot from grid (isotherms):
  `guru-hugoniot --Ma 20.18 --grid-eos EOS.tsv --grid-init-T 300 --grid-init-rho 2.1 --curves iso -o hug.tsv --progress --plot`
- Isentrope + u(P):
  `guru-isentrope -i EOS.tsv --Ma 20.18 --T0 300 --rho0 2.1 --drho 0.01 -o iso.tsv --out-velocity u.tsv --plot`
- Isobar from TSVs:
  `guru-iso-fit --mode isobar --pressure 1000 -i tsv_cat/*.tsv -o isobar.tsv --tol-T 10 --tol-rho 0.01 --isobar-allow-extrap --plot`

# Workflows
- Sample‑based RH:
  thermo (rich TSV) → phase_tag (optional) → iso_fit (init) → hugoniot (TSVs)
- Grid‑based RH/isentropes:
  Build EOS TSV (T,ρ,P,E) → hugoniot/isentrope with PCHIP2D
- Diffusion/RDF:
  XDATCAR(+OUTCAR) → msd_diffusion / rdf → TSV/plots

# Module Snapshots (Ultra‑short)
- thermo: OUTCAR/TSV stats → compact/rich TSV; plots/progress.
- hugoniot: Solve RH along iso‑curves (TSV/grid); phase‑aware; safe SI residual.
- iso_fit: Fit isotherm/isochor to P*; reconstruct isobars (TSV/grid); plots.
- isentrope: Integrate isentropic T(ρ) on grid; u(P) diagnostics.
- msd: MSD/D from XDATCAR; PBC‑safe unwrapping; linear fit.
- rdf: g(r) total/partial + shell density; trajectory‑wide histograms.
- phase_tag: Add integer phase to thermo TSV rows.
- tsv_cat: Concatenate/filter TSVs; pipe data between tools.
- interp_utils: PCHIP2D, grid readers, clamped extrapolation helpers.
- progress: Unified stderr progress; tqdm if available.

# Dependencies & Env
- Core: Python 3, numpy, scipy; optional matplotlib, tqdm.
- No network required; CPU‑bound; memory depends on OUTCAR/XDATCAR size and grid density.

# Performance & Scaling
- Use grid nodes for bracketing, then `brentq` (hugoniot/iso_fit grid); avoid dense uniform scans.
- Prefer PCHIP (shape‑preserving) to splines with oscillations; stream OUTCAR where possible.

# Error & Exit Codes
- Typical non‑zero exits: bad input schema, no rows parsed, missing required flags.
- Errors reported on stderr with concise messages; some tools write warnings but keep going.

# Logging & Provenance
- `guru.log` appended near outputs with CLI argv and timestamps; best‑effort, never fatal.

# Progress & UI
- All long‑running loops instrumented via `progress.Progress` (stderr). Disable with `--no-progress`.

# Testing & Validation
- Sanity TSVs: small T–ρ–P–E grids, short XDATCAR + OUTCAR. Compare against manual calculations or known references.

# Datasets
- See `testdata/`: OUTCAR/XDATCAR samples, thermo/rdf plots; use for quick validation and demos.

# Known Pitfalls
- Missing/invalid density in TSVs; ρ=0; negative T in inputs; inconsistent units. Fix by using guru-thermo rich TSVs and reviewing headers.
- Extrapolation beyond data/grid: allowed but marked; avoid relying on it for critical points.

# Glossary
- Isotherm (T=const), Isochor (ρ=const), Isobar (P=const),
  Hugoniot (RH locus), PCHIP2D (separable PCHIP over T,ρ), u(P) (mass velocity).

# Roadmap / TODO
- More diagnostics in hugoniot (residual traces), unified plotting themes, richer validation datasets.

# Style & Contrib
- Use `apply_patch` to edit files; keep modules focused; update manuals in `manuals/` alongside code changes; preserve units and column names.
 - Provide a top-level `guru` CLI with `--version` and `--list` to aid discovery (see setup.cfg entry points).

# AI Agent Rules
- Keep this `project_summary.md` and related manuals in `manuals/` up to date with every change to code modules.
- If a module lacks a manual, create it (EN/RU where applicable) alongside the change.
- Versioning policy (semantic‑lite):
  - +0.01 for non‑breaking changes within existing modules (bug fixes, options, minor features).
  - +0.1 for adding new modules or significant cross‑cutting features.
  - Keep versions in sync in `setup.cfg [metadata].version` and `guru/__init__.py::__version__`.
- When adding features that affect CLI/IO schemas, also update README (examples), and the “What’s New” section.
- Prefer small, focused patches and keep units/column schemas consistent across tools.
 - Provide a top-level `guru` CLI with `--version` and `--list` to aid discovery (see setup.cfg entry points).
 - When adding a new CLI module or renaming an existing one, update packaging entry points in BOTH files:
   - `setup.cfg [options.entry_points].console_scripts` and
   - `setup.py` (`build_entry_points()` helper),
   so that `pip install -e .` generates proper console scripts.
# outcar.py
**Key Functions**
- get_potim(path) — read POTIM (fs) from OUTCAR.
- read_static_fingerprint(path) — minimal system fingerprint: NIONS, direct lattice (3×3), TEBEG, SIGMA, POTCAR/TITEL list.
- check_consistency(paths) — compare fingerprints across multiple OUTCAR; returns (ref, errors).

# viscosity.py
**Key Functions**
- main(argv) — CLI entry: read D (msd), r_peak (rdf stats), T and rho (thermo), compute eta [Pa·s] and nu [m²/s] via Stokes–Einstein variant.

**Dependencies**
- numpy, scipy.constants; guru inputs (msd/rdf/thermo TSVs).

**Constraints**
- Requires RDF stats TSV (`--stats-out`) to obtain `r_peak_A`.

**Constraints**
- Streaming‑friendly scans; no heavy parsing. Lattice taken from the first direct lattice block.