Metadata-Version: 2.4
Name: fastmdxplora
Version: 2.2.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: scipy>=1.7
Requires-Dist: scikit-learn>=1.0
Requires-Dist: pandas>=1.4
Requires-Dist: python-pptx>=0.6.21
Requires-Dist: pillow>=10.0
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"
Requires-Dist: rdkit>=2023.3; extra == "ligand"
Requires-Dist: propka>=3.5; extra == "ligand"
Provides-Extra: amber
Requires-Dist: netCDF4>=1.6; extra == "amber"
Provides-Extra: umap
Requires-Dist: umap-learn>=0.5; extra == "umap"
Provides-Extra: plumed
Requires-Dist: openmm-plumed>=1.0; extra == "plumed"
Provides-Extra: all
Requires-Dist: fastmdxplora[amber,ligand,md,plumed,umap]; extra == "all"
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
- Build a protein-ligand system from a PDB identifier alone: the ligand is identified, its chemistry retrieved, and its protonation settled in the binding site, with a refusal rather than a guess where the structure is ambiguous
- 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. Decides what each non-standard residue means — a bound ligand is parameterized, a cryoprotectant discarded, a coordinated metal kept — and stops where the structure does not say. |
| **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

From conda-forge, which brings every backend with it:

```bash
conda create -n fastmdxplora -c conda-forge fastmdxplora
conda activate fastmdxplora
```

This is the recommended route. OpenMM, PDBFixer, OpenFF, RDKit, and PROPKA are
conda-forge packages, and the ligand path needs all of them; installing them
any other way is more work for the same result.

From PyPI, if you already manage those yourself or only need part of the
pipeline:

```bash
pip install fastmdxplora            # analysis and reporting
pip install "fastmdxplora[md]"      # adds setup and simulation
pip install "fastmdxplora[ligand]"  # adds protein-ligand preparation
```

Run `fastmdx info` afterwards to see which backends were found.

Working on FastMDXplora itself, Windows and WSL2, and troubleshooting a partial
install are covered 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.
