Getting Started#

Setup#

GPU acceleration requires a working CUDA 12 toolchain and matching drivers.
The CHARMM Python bindings now ship with MMML. You still need a CHARMM shared library (see setup/install.sh) and the environment variables CHARMM_HOME / CHARMM_LIB_DIR so the bundled code can discover libcharmm.

Install#

Install the core package in editable mode from the repository root:

cd ~/mmml
pip install -e .

Optionally install extra integrations (including the CHARMM helpers) via extras:

pip install -e ".[charmm-interface]"

The legacy helper script bash setup/install.sh remains available if you prefer the previous workflow that compiles CHARMM and installs all extras in one step.

import mmml

Installation#

Quick start (CPU only)#

Create and activate a fresh environment (recommended):

With uv:

uv venv
. .venv/bin/activate  # on Windows: .venv\Scripts\activate

Or with conda/mamba:

mamba create -n mmml python=3.11 -y
mamba activate mmml

Install the core package:
```
pip install -e .
```

Optional: GPU and extra backends#

JAX with CUDA (for PhysNetJax and GPU acceleration):

Find your CUDA/cuDNN versions, then install matching JAX wheels. For CUDA 12.x:

pip install --upgrade "jax[cuda12]" -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html

Verify:
```
import jax; print(jax.devices())
```

e3x (E(3)-equivariant ops used by some models):
```
pip install e3x
```

PySCF with GPU support (gpu4pyscf):

pip install pyscf
pip install gpu4pyscf  # requires a working CUDA toolchain

Notes: - Some modules (e.g., mmml.dcmnet.dcmnet, mmml.pyscf4gpuInterface) require optional deps like e3x, CUDA, and gpu4pyscf. If not installed, those submodules may be unavailable during docs build or runtime. - Ensure your NVIDIA drivers and CUDA runtime are installed and match the wheels you choose.

Developer setup#

Install dev/runtime extras (tests, docs):

pip install -r docs/requirements.yaml  # if using pip+pip-tools style
# or, if using conda env file
mamba env update -n mmml -f devtools/conda-envs/test_env.yaml

Build the documentation locally:

cd docs
make html  # on Windows: .\make.bat html

Open the docs:

xdg-open _build/html/index.html  # macOS: open, Windows: start