mmml

Molecular Mechanics + Machine-Learned Force-Field Toolkit

MMML combines CHARMM/OpenMM workflows with JAX-based neural models for electrostatics and force prediction.

Auto-prediction CLI

uv sync --extra all-cpu --extra cli 
eval "$(register-python-argcomplete mmml)"

📚 Documentation

For complete documentation, tutorials, and guides, please visit:

Read the Docs

The documentation includes:

• Installation instructions
• Quick start guides
• mmml md-system YAML config and campaign guide for condensed-phase workflows
• API reference
• Tutorials and examples
• Troubleshooting guides

Quick Installation

Using uv (Recommended)

git clone https://github.com/EricBoittier/mmml.git
cd mmml
uv sync

# For GPU support
make install-gpu

Using Conda

conda env create -f setup/environment.yml
conda activate mmml

# For GPU support
conda env create -f setup/environment-gpu.yml
conda activate mmml-gpu

Using Docker

docker-compose up -d mmml-cpu
docker-compose exec mmml-cpu bash

Quick Example

For config-driven condensed-phase MD campaigns, start with mmml/cli/run/md_system.example.yaml and the md-system YAML config guide.

import numpy as np
from pathlib import Path
from mmml.interfaces.pycharmmInterface.mmml_calculator import setup_calculator
import ase

ATOMS_PER_MONOMER = 10
N_MONOMERS = 2
Z = np.array([6, 1, 1, 1, 6, 1, 1, 1, 8, 1] * N_MONOMERS, dtype=int)
R = np.zeros((ATOMS_PER_MONOMER * N_MONOMERS, 3), dtype=float)

ckpt = Path("mmml/physnetjax/ckpts")
factory = setup_calculator(
    ATOMS_PER_MONOMER=ATOMS_PER_MONOMER,
    N_MONOMERS=N_MONOMERS,
    doML=True,
    doMM=False,
    model_restart_path=ckpt,
    MAX_ATOMS_PER_SYSTEM=ATOMS_PER_MONOMER * N_MONOMERS,
    ml_energy_conversion_factor=1,
    ml_force_conversion_factor=1,
)

calc, _ = factory(atomic_numbers=Z, atomic_positions=R, n_monomers=N_MONOMERS)
atoms = ase.Atoms(Z, R)
atoms.calc = calc
print("Energy (kcal/mol):", atoms.get_potential_energy())

Getting Help

• Full Documentation: Read the Docs
• Issues: GitHub Issues

License

Copyright (c) 2025, Eric Boittier

Acknowledgements

Project based on the Computational Molecular Science Python Cookiecutter version 1.10.