Metadata-Version: 2.4
Name: fastmdxplora
Version: 2.1.0
Summary: FastMDXplora: Fully Automated SysTem for Molecular Dynamics eXploration
Author: Adekunle Aina, Derrick Kwan
Maintainer: Adekunle Aina
License: MIT
Project-URL: Homepage, https://github.com/aai-research-lab/FastMDXplora
Project-URL: Documentation, https://fastmdxplora.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/aai-research-lab/FastMDXplora
Project-URL: Issues, https://github.com/aai-research-lab/FastMDXplora/issues
Project-URL: Changelog, https://github.com/aai-research-lab/FastMDXplora/blob/main/CHANGELOG.md
Keywords: molecular-dynamics,md-simulation,trajectory-analysis,automation,orchestrator,computational-chemistry,biophysics,structural-biology,reproducibility
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.14,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Requires-Dist: pyyaml>=6.0
Requires-Dist: mdtraj>=1.9.7
Requires-Dist: matplotlib>=3.5
Requires-Dist: scikit-learn>=1.0
Requires-Dist: pandas>=1.4
Requires-Dist: python-pptx>=0.6.21
Provides-Extra: md
Requires-Dist: pdbfixer; extra == "md"
Requires-Dist: openmm>=8.0; extra == "md"
Provides-Extra: ligand
Requires-Dist: openff-toolkit>=0.16; extra == "ligand"
Requires-Dist: openmmforcefields>=0.12; extra == "ligand"
Provides-Extra: plumed
Requires-Dist: openmm-plumed>=1.0; extra == "plumed"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
Requires-Dist: myst-parser>=2.0; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: python-pptx>=0.6.21; extra == "dev"
Dynamic: license-file

# FastMDXplora

> **F**ully **A**utomated **Sy**s**T**em for **M**olecular **D**ynamics e**Xplora**tion

[![DOI](https://img.shields.io/badge/DOI-10.1002%2Fjcc.70350-blue)](https://doi.org/10.1002/jcc.70350)
[![PyPI version](https://img.shields.io/pypi/v/fastmdxplora)](https://pypi.org/project/fastmdxplora/)
[![Python versions](https://img.shields.io/pypi/pyversions/fastmdxplora)](https://pypi.org/project/fastmdxplora/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/aai-research-lab/FastMDXplora/actions/workflows/tests.yml/badge.svg)](https://github.com/aai-research-lab/FastMDXplora/actions/workflows/tests.yml)
[![codecov](https://codecov.io/gh/aai-research-lab/FastMDXplora/branch/main/graph/badge.svg)](https://codecov.io/gh/aai-research-lab/FastMDXplora)

---

**FastMDXplora** explores a protein's behavior end to end from a single
command. Given a structure (or just a PDB ID) it performs molecular dynamics
exploration all the way through setup, simulation, analysis, and reporting,
then hands back publication-ready results.

```
  setup  →  simulation  →  analysis  →  report
```

## Highlights

- Explore a protein's full dynamics with a single command, covering setup, simulation, analysis, and reporting
- Probe protein-ligand binding automatically with analyses for pose stability, contacts, and protein-ligand hydrogen bonds
- Reach beyond plain MD with built-in PLUMED enhanced sampling (metadynamics, umbrella sampling, steered MD)
- Design, start, watch, and review an exploration from a browser, with a 3D viewer and live telemetry
- Scale from a quick single-protein exploration to large parallel campaigns, driven the same way from the CLI or the Python API

## Phases of FastMDXplora

| Phase | What it does |
|---|---|
| **setup** | Cleans up your structure and builds a simulation-ready system: fixes missing atoms, adds hydrogens, solvates, and adds ions. |
| **simulation** | Runs the molecular dynamics (energy minimization, equilibration, and production), with optional enhanced sampling. |
| **analysis** | Computes the standard structural and dynamic metrics (and protein-ligand metrics when a ligand is present), with figures ready to use. |
| **report** | Packages everything into a slide deck, a written report, and a self-contained bundle you can share. |

## Install

Analysis and reporting are pure pip. Setup and simulation additionally need
OpenMM and PDBFixer, which come from conda-forge.

```bash
# analysis and reporting only
pip install fastmdxplora

# all four phases
conda create -n fastmdxplora "python>=3.9,<3.14"
conda activate fastmdxplora
conda install -c conda-forge openmm pdbfixer openmmforcefields
pip install fastmdxplora
```

To work on FastMDXplora itself, clone the repository and use the bundled
`environment.yml`. Full instructions, including Windows and WSL2, optional
extras, and troubleshooting, are in the
[installation guide](https://fastmdxplora.readthedocs.io/en/latest/installation.html).

## Quick start

```bash
fastmdx explore --system 1L2Y      # a full exploration, from a PDB ID
fastmdx gui                        # design, start, and watch one in a browser
fastmdx info                       # what is installed and which backends are present
```

From Python:

```python
import fastmdxplora as fastmdx

runs = fastmdx.FastMDXplora(system="1L2Y", output_dir="trpcage").explore()
print(runs[0].output_dir)
```

For anything beyond a quick run, capture the whole exploration in a YAML file.
`fastmdx init-config` writes a commented template, and the same file drives
both the CLI and the Python API:

```bash
fastmdx explore --config study.yml
```

Parameter sweeps, multi-system campaigns, cross-run comparison, parallel
execution, and the full flag list are covered in the
[usage examples](https://fastmdxplora.readthedocs.io/en/latest/usage_examples.html)
and the
[CLI reference](https://fastmdxplora.readthedocs.io/en/latest/cli_reference.html).

## Outputs by phase

Each phase writes to its own subdirectory under the output root, with a
parameters manifest so every artifact is traceable to the options that
produced it.

| Phase | Key outputs |
|---|---|
| `setup` | `prepared.pdb`, `solvated.pdb`, `setup_parameters.json` |
| `simulation` | `production.dcd`, `topology.pdb`, `simulation_parameters.json` |
| `analysis` | `<analysis>/*.dat`, `<analysis>/*.png`, `analysis_manifest.json` |
| `report` | `report.md`, `dashboard.html`, `slides.pptx`, `project_bundle.zip` |

## Documentation

Full documentation is at
[fastmdxplora.readthedocs.io](https://fastmdxplora.readthedocs.io):

- [Beginner's guide](https://fastmdxplora.readthedocs.io/en/latest/getting_started.html): first run, start to finish
- [Installation](https://fastmdxplora.readthedocs.io/en/latest/installation.html): every route, platform notes, troubleshooting
- [GUI](https://fastmdxplora.readthedocs.io/en/latest/gui.html): the browser interface, and watching a cluster run
- [Configuration](https://fastmdxplora.readthedocs.io/en/latest/configuration.html): the YAML file, option by option
- [CLI reference](https://fastmdxplora.readthedocs.io/en/latest/cli_reference.html): every command and flag
- [Production runs](https://fastmdxplora.readthedocs.io/en/latest/production.html): GPUs, long trajectories, scaling

## Citation

If you use FastMDXplora in your work, please cite:

> Aina, A.; Kwan, D. *FastMDAnalysis: Software for Automated Analysis of Molecular Dynamics Trajectories.* J. Comput. Chem. **2026**, 47, e70350. DOI: [10.1002/jcc.70350](https://doi.org/10.1002/jcc.70350)

```bibtex
@article{aina2026fastmd,
  author  = {Aina, Adekunle and Kwan, Derrick},
  title   = {FastMDAnalysis: Software for Automated Analysis of Molecular Dynamics Trajectories},
  journal = {Journal of Computational Chemistry},
  volume  = {47},
  number  = {8},
  pages   = {e70350},
  year    = {2026},
  doi     = {10.1002/jcc.70350},
}
```

## Contributing

Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md). FastMDXplora follows the [Contributor Covenant](CODE_OF_CONDUCT.md).

## License

MIT. See [LICENSE](LICENSE).

## Acknowledgements

FastMDXplora is developed in the [AAI Research Lab](https://aai-research-lab.github.io) at California State University Dominguez Hills. It builds on a deep ecosystem of open-source scientific Python: MDTraj, OpenMM, PDBFixer, NumPy, SciPy, scikit-learn, Matplotlib, python-pptx, and many others.
