mdweave

mdweave is an early-stage Python toolkit for reproducible, streaming conversion of molecular-dynamics trajectories into ML-ready structural and temporal features. It delegates trajectory I/O and atom selections to MDAnalysis, then adds stable feature schemas, canonical units, provenance, lazy frame views, and bounded-memory processing.

The initial release is Milestone 1: an MDAnalysis trajectory adapter, lazy slicing, mass-weighted radius of gyration, a metadata-rich result container, tests, and CI.

Installation

python -m pip install -e ".[test]"

Python 3.10+ is supported. Public units are angstrom for distance, picoseconds for time, and (for future angular features) radians.

Quickstart

import mdweave

traj = mdweave.load("trajectory.xtc", topology="protein.pdb")
feature = mdweave.features.RadiusOfGyration(selection="protein")

result = feature.transform(traj)
print(result.values.shape)
print(result.feature_names)
print(result.metadata)

Large trajectories can be consumed in bounded-memory batches:

for batch in feature.transform_stream(traj[100::10], batch_size=1_000):
    train_incrementally(batch.values)

FeatureResult.values works directly with NumPy and scikit-learn. Optional to_dataframe() and to_torch() methods import pandas and PyTorch only on demand.

Why this project?

MDAnalysis and MDTraj already provide excellent trajectory I/O, selection, geometry, and chunk iteration; CPPTRAJ and GROMACS provide extensive high-performance analysis; ProLIF provides chemically informed protein-ligand fingerprints; deeptime provides kinetic estimators. mdweave does not replace them. Its proposed contribution is the missing connective layer: deterministic feature definitions and provenance, consistent frame/time alignment, streaming feature batches, generic temporal transforms, and clean handoff to mainstream Python ML tools. See the landscape and scope.

Development

pytest
ruff check .

The public API is alpha-stage. See the roadmap, contributing guide, and citation metadata.

Releasing

GitHub releases are published to PyPI through Trusted Publishing. Configure the PyPI publisher with workflow filename release.yml and GitHub environment pypi, then publish a GitHub release after updating the version in pyproject.toml.