PathGennie

Welcome to PathGennie! PathGennie is a rapid generation rare-event sampling framework.

Features

• HPC Parallelism: Easily distribute sampling with MPI and Dask on multi-node clusters.
• Asynchronous Storage: Stream huge trajectories via h5py so you never run out of memory.
• Robust Configuration: Clean, validated input configurations using pydantic.

PathGennie is a direction-guided adaptive sampling method for molecular dynamics. From an anchor configuration it launches a swarm of short, unbiased MD segments, scores each by progress in a collective-variable (CV) space, softmax-selects one, extends it, updates the anchor, and repeats — generating rare-event pathways (ligand unbinding, (un)folding, conformational change) cheaply, with only a selection bias on natural dynamics (no bias potential).

This manual documents the shared-core architecture and the features built on top of the original three-backend runners. For a high-level project overview and the example gallery, see the top-level README.md; for a chronological list of changes see CHANGELOG.md.

Contents

Reference

• Architecture — the core driver, the Engine protocol, progress variables, and the parallel executor.
• Configuration — the full input.yaml schema, including the new devices / workers_per_device / seed / profile / downstream keys.
• Multi-GPU scalability — how the device pool spreads the swarm across GPUs, and how to benchmark it.
• Strategy profiles — switching behaviour by goal (discovery vs sampling) and the learned-CV trajectory-length guard.
• Data-driven CVs (SPIB) — learning a CV and metastable states on the fly.
• Non-linear search (RRT) — RRT / RRT-Connect for pathways the greedy metric cannot follow.
• Roadmap graph — all-pairs pathways between metastable states (Dijkstra + Yen).
• Agentic controller — automating swarm size and segment lengths.
• Weighted Ensemble — path-informed free-energy / rate-constant stage.
• OPES via PLUMED — free-energy surfaces along a CV.
• Path sampling (TPS/TIS) — kinetics via OpenPathSampling on PathGennie seed paths.
• Project roadmap — what is implemented vs planned.
• Future roadmap — strategic plan toward a PLUMED/WESTPA-class framework (tiers, milestones, priority queue).

Tutorials (all runnable with no MD binary or GPU unless noted)

• 01 — Quickstart on the toy engine
• 02 — Multi-GPU runs on the MD backends
• 03 — A learned CV with SPIB
• 04 — Free energies & rates with Weighted Ensemble
• 05 — Goal-driven strategy profiles
• 06 — Non-linear search with RRT-Connect
• 07 — Metastable states, roadmap & the agent
• 08 — Free-energy surfaces with OPES
• 09 — Kinetics with TPS/TIS (OpenPathSampling)

Installation

pip install -e .            # core: AMBER + GROMACS backends
pip install -e .[openmm]    # + OpenMM, required for the OpenMM backend
pip install -e .[dev]       # + pytest
pip install -e .[ml]        # + PyTorch, required for the SPIB data-driven CV
pip install -e .[analysis]  # + scikit-learn/matplotlib/joblib/dtaidistance for pcagen and path clustering
pip install -e .[examples]  # + ParmEd for some example setups

Run the test suite to confirm a working install:

pytest -q                   # SPIB tests skip without torch; OpenMM/MDAnalysis tests skip without them

The 60-second mental model

                ┌─────────────────────────── PathGennieDriver ───────────────────────────┐
 anchor ──▶ clone ─▶ run N samplers (τ1) ─▶ project→metric ─▶ softmax_select ─▶ runner (τ2)
                          │  (ParallelExecutor: 1..G GPUs)        │ (selection.py)     │
                          ▼                                       ▼                    ▼
                    Engine.run_segment                     ProgressVariable      update anchor → repeat
   (OpenMM / AMBER / GROMACS / toy)             (geometric Escape/Target, or learned SPIB)
                                                                                       │
                                                              ┌────────────────────────┘
                                                              ▼
                                       PathEnsemble ──▶ SamplingStage (Weighted Ensemble) ──▶ FES / rates

Every box is a small, swappable interface:

Concern	Interface	Built-ins
MD engine	core.engine.Engine	OpenMM, AMBER, GROMACS, ToyLangevinEngine
Progress / CV	core.progress.ProgressVariable	EscapeMetric, TargetMetric, cv.spib.SPIBProgress
Parallelism	core.parallel.ParallelExecutor	SerialExecutor, ThreadDevicePool
Goal preset	core.strategy.RunProfile	discovery, sampling
Downstream	sampling.base.SamplingStage	WeightedEnsembleStage

Because these are protocols, you can mix any engine with any CV, any degree of parallelism, and any downstream stage without touching the others.