MSTBx: Molecular Simulation ToolBox (v0.8.10-beta)

Introduction

MSTBx is a high-performance, modular Python-based ecosystem designed to streamline the preparation, configuration, and execution of Molecular Dynamics (MD) simulations. Built with a "Waiter/Chef" architecture, MSTBx provides a unified Command Line Interface (CLI) that automates complex tasks involving VMD, PSFGen, and MDAnalysis.

While web-based system builders are convenient, they often struggle with massive systems or complex high-throughput requirements. MSTBx is engineered for efficiency, capable of preparing systems with millions of atoms (such as the SARS-CoV-2 Spike protein) in a fraction of the time required by conventional tools. It offers an excellent synergy with the CHARMM-GUI PDBReader: users can generate initial topology/coordinates (PSF/PDB) via CHARMM-GUI and then leverage MSTBx's speed for rapid solvation, ionization, and protocol generation. Furthermore, MSTBx is highly versatile and can process PSF/PDB files generated by any other standard modeling tools.

Core Philosophies

1. Efficiency: Optimized for large-scale complexes where automation is critical.
2. Reproducibility: Parameter-driven configuration ensures consistent protocol generation.
3. Engine Versatility: Native support for NAMD 2/3, GROMACS, and OpenMM, with AMBER planned.
4. Standardization: Enforces strict geometric symmetries and nomenclature across all modules.

---

Installation

1. Environment Management (Conda)

Use the repository Conda recipe to install MSTBx together with the executable tools required by the validated GROMACS workflows (Python >= 3.12):

conda env create -f environment.yml
conda activate mstbx

For a fresh checkout, the equivalent commands are:

conda create -n mstbx python=3.12 pip
conda activate mstbx
pip install -e ".[test]"

The Conda recipe installs gromacs, openbabel, OpenMM, PDBFixer, MDAnalysis, MDTraj, and the Python package. gromacs and obabel are external executables, not Python modules, so a Python-only pip install does not provide them.

Verify the installation:

mstbx --help
gmx --version
obabel -V
python -m pytest

VMD/NAMD and Apptainer are optional external programs for the corresponding workflows. Install them through the provider or cluster module system and verify them separately:

vmd -dispdev text -eofexit
namd2 --version
apptainer --version

The GROMACS force field and CGenFF converter are packaged inside the Python wheel. The CHARMM-GUI/CGenFF Web service remains a manual external step.

2. Persistent Shell Completion

To enable robust TAB completion for all MSTBx modules, add the following to your `~/.zshrc` (or `~/.bashrc`):

# MSTBx CLI Completion
eval "$(_MSTBX_COMPLETE=zsh_source $HOME/miniconda3/envs/mstbx/bin/mstbx)"

---

📚 Documentation Map

Start with the tutorials: they are the primary documentation and cover every workflow end to end, one file per engine.

• Tutorials index
  • 0. PDBWriter Structure Preparation
  • NAMD workflows (Ubiquitin, protein-ligand, membrane, SMD, glycosylated systems)
  • GROMACS workflows (protein-only and protein-ligand/CGenFF)
  • OpenMM workflows
  • Docking workflows
• Module Reference: flag-by-flag reference for every command, for when a tutorial's defaults need to be looked up or changed.
• Testing Manual: verification checklist per workflow.
• Changelog: version history.

---

Testing

Every workflow change (NAMD, GROMACS, OpenMM, structure preparation, PSF/system construction, docking, translation, enhanced sampling, and container modules) must be covered by unit tests (pure logic, parsers, defaults, generated files), regression tests (validated command order, file layout, protocol constants), and adversarial tests (malformed input, invalid option combinations, missing metadata, unavailable external tools). See the Testing Manual for the per-workflow verification checklist.

Run the automated suite from the repository root:

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

This validates all registered CLI commands, defaults, and option combinations without launching long MD simulations. When the external tools are installed, run the short PDB2PQR/GROMACS regressions explicitly (these compile EM/NVT/NPT/production TPR inputs with grompp; they do not call mdrun):

MSTBX_PDB2PQR="$(command -v pdb2pqr)" \
MSTBX_GMX="$(command -v gmx)" \
python -m pytest -m external -q

Use --pdb2gmx-protonation only when explicit HIS/ASP/GLU/LYS/ARG protonation choices are required; otherwise pdb2gmx uses its force-field defaults.

Version history is tracked in CHANGELOG.md.

---

Development Standards

MSTBx follows strict internal standards to ensure reliability: - Logging: All output is timestamped: `[LEVEL HH:MM:SS DD/MM/YYYY]`. - Documentation: All README documentation must be written in English. - Naming: Consistent flags across all modules (`--env`, `--engine`, `--psf`, `--pdb`). - Safety: Automated box symmetry checks to prevent periodic boundary condition artifacts. - Local Development Skill: Standards are checked locally by the `mstbx-development` skill.

---

Module Reference and Technical Documentation

The full flag-by-flag reference for every module (topopsfgen, md-inputs (NAMD and GROMACS engines), topogmx, smd-inputs, metad-inputs, pdbwriter, resetpsf, md-translate, and openmm-run), including the engine architecture table, generated directory layouts, and default constants, has moved to docs/REFERENCE.md.

---

Author

Ropón-Palacios G.
Department of Physics, UNESP.
georcki.ropon@unesp.br

License

MSTBx is licensed under the MIT License.