Metadata-Version: 2.5
Name: mdweave
Version: 0.1.0
Summary: Reproducible, streaming molecular-dynamics features for machine learning
Project-URL: Documentation, https://github.com/eganeganegan/MDWeave#readme
Project-URL: Repository, https://github.com/eganeganegan/MDWeave
Project-URL: Issues, https://github.com/eganeganegan/MDWeave/issues
Project-URL: ORCID, https://orcid.org/0009-0005-0222-1653
Author: Anthony Egan
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Requires-Dist: mdanalysis>=2.7
Requires-Dist: numpy>=1.23
Provides-Extra: dataframe
Requires-Dist: pandas>=1.5; extra == 'dataframe'
Provides-Extra: dev
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-cov>=4; extra == 'test'
Requires-Dist: pytest>=7; extra == 'test'
Provides-Extra: torch
Requires-Dist: torch>=2; extra == 'torch'
Description-Content-Type: text/markdown

# 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

```bash
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

```python
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:

```python
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](docs/scope.md).

## Development

```bash
pytest
ruff check .
```

The public API is alpha-stage. See [the roadmap](docs/roadmap.md),
[contributing guide](CONTRIBUTING.md), and [citation metadata](CITATION.cff).

## 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`.
