conformatlas 1.0.0

Mapping conformational landscapes from molecular simulations

Installation · Quick start · Outputs · Documentation · Citation

ConformAtlas turns molecular dynamics trajectories into a quantitative map of conformational space: principal components, a free-energy landscape with error bars, the metastable states on it, the barriers and rates between them, and a verdict on whether the sampling supports those numbers. It runs as a single command (conformatlas analyze) and as a Python library, reads anything MDAnalysis can open, and ships with a validation suite that checks every numerical component against analytical results or an independent implementation.

_{Influenza A/H1N1 neuraminidase bound to zanamivir, 2001 frames at 300 K: free-energy landscape on the first two Cα principal components with three watershed states (48 / 41 / 11 %). Unmodified figures/fel_2d_3d.png from a single conformatlas analyze run; see the tutorial.}

Features

Installation

pip install conformatlas            # core (includes MDAnalysis)
pip install "conformatlas[all]"     # + interactive figures, HDF5, progress bars, PDF report

From source:

git clone https://github.com/AtharvaTilewale/ConformAtlas.git
cd ConformAtlas
pip install -e ".[dev]"
conformatlas doctor                 # checks Python dependencies and GROMACS (optional)

Requires Python ≥ 3.10. GROMACS is optional and only needed for --pca-backend gromacs.

Quick start

Analyse one system (any number of replicates):

conformatlas analyze -s topology.gro -f rep1.xtc -f rep2.xtc -f rep3.xtc -T 300 -o results/WT

Protein–ligand complex, discarding the equilibration phase and adding a Markov state model:

conformatlas analyze -s md.gro -f md_noPBC.xtc -n index.ndx \
    --cov-group C-alpha --lig ZMR -T 300 \
    --equilibration auto --bootstrap 200 --msm \
    -o results/complex

Compare conditions (wild type vs mutant, apo vs holo, …) in a shared PCA space:

conformatlas compare --config comparison.yaml -o results/comparison

Try it on the bundled synthetic two-state peptide:

conformatlas example -o demo
conformatlas analyze -s demo/WT/topology.pdb -f demo/WT/rep1.xtc -f demo/WT/rep2.xtc -T 300 --bins 32 --smooth-sigma 1.0 -o demo/results

Every option can live in a YAML file (conformatlas init-config --type analyze -o run.yaml). Trajectories must be made whole across periodic boundaries first (gmx trjconv -pbc mol). The full option reference is in docs/cli.md.

From Python:

from conformatlas import api

ens  = api.load_trajectories("topology.gro", ["rep1.xtc", "rep2.xtc"], group="C-alpha")
pcs  = api.pca(ens)
land = api.landscape(pcs, temperature=300)
st   = api.states(land)
fig, ax, _ = api.plot_landscape(land, states=st.states)

What you get

results/
├── report.html         # interactive landscape, structure viewer, interpretation
├── summary.json        # state populations and minima, convergence assessment
├── pca/                # eigenvalues, projections, eigenvectors, modes.nmd, mode contributions
├── fel/                # free-energy grid, probability, bootstrap SD and CI
├── states/             # basins, frame assignments, barriers, state ΔG, representative structures
├── statistics/         # populations with block SD/SEM and bootstrap 95 % CI
├── kinetics/  msm/     # transition matrices, dwell times, MFPT; MSM diagnostics (--msm)
├── convergence/        # RMSIP, N_eff, equilibration, cosine content, population stability
├── residues/           # DCCM, state differences, ligand contacts (--residue-analysis)
└── figures/            # 2-D/3-D landscapes, uncertainty maps, kinetics, MSM, DCCM panels

Units: Å, ps, kJ/mol. The complete file manifest is in docs/outputs.md.

Validation

validation/validate.py compares every numerical component with an analytical result or an independent implementation — MDAnalysis, GROMACS (covar, anaeig, sham), pymbar, deeptime, SciPy and ProDy — and writes the report that is published as docs/benchmarks.md (147/147 checks). Components that are conventions rather than derivations (convergence thresholds, grid heuristics, MSM lag selection) are labelled as such in docs/methods.md.

Boltzmann inversion assumes an unbiased equilibrium ensemble; for biased simulations use conformatlas reweight and --weights-file. See the FAQ for this and other pitfalls.

Documentation

Full documentation: conformatlas.readthedocs.io

Citation

@software{conformatlas2026,
  author  = {Tilewale, Atharva and Patel, Dhaval},
  title   = {ConformAtlas: mapping conformational landscapes from molecular simulations},
  year    = {2026},
  version = {1.0.0},
  url     = {https://github.com/AtharvaTilewale/ConformAtlas}
}

A machine-readable citation is in CITATION.cff.

Contributing

Bug reports, feature requests and pull requests are welcome — see CONTRIBUTING.md. Please run ruff check, the test suite and validation/validate.py before opening a pull request.

Authors and license

Developed by Atharva Tilewale and Dhaval Patel. Released under the MIT License.