karml (pronounced Karamell) — machine-learned potentials in molecular-mechanics MD.
karml combines CHARMM/OpenMM workflows with JAX-based neural models for electrostatics and force prediction, for building and running hybrid ML/MM condensed-phase simulations.
KARML is in alpha. The core calculator, CLI, and md-system YAML workflow are usable today, but interfaces are still settling and may change without notice ahead of a first tagged release. Feedback and issues are welcome — see Getting Help.
Requires Python 3.13. Prefer uv.
git clone https://github.com/EricBoittier/karml.git
cd karml
uv sync
# Optional extras
uv sync --extra cli # shell tab completion (argcomplete)
uv sync --extra md-cpu # Vesin NL + MDAnalysis (CPU MD smokes)
uv sync --extra dev # pytest, MkDocs, ruff
uv sync --extra metatomic # TorchScript AtomisticModel ASE + CHARMM MLpot
make install-gpu # JAX CUDA 13 + CuPy (GPU nodes; SM 7.5+)
# make install-gpu-cuda12 # older GPUs / CUDA 12For PyCHARMM / Packmol (native libs, not installed by uv):
make install-native # builds libcharmm + packmol under setup/charmm
make doctor # karml doctor — env / CHARMM readinessOr from a fresh clone: make install-full (uv sync + native build).
Installs the karml command into its own isolated environment. Pick one GPU
extra; JAX's CUDA wheels bring their own CUDA/cuDNN, so only an NVIDIA driver
is needed on the machine.
uv tool install -p 3.13 "karml[gpu] @ git+https://github.com/EricBoittier/karml" # CUDA 13 (SM 7.5+)
uv tool install -p 3.13 "karml[gpu-cuda12] @ git+https://github.com/EricBoittier/karml" # CUDA 12 (older GPUs/drivers)
uv tool install -p 3.13 "karml @ git+https://github.com/EricBoittier/karml" # CPU only
# from a local checkout instead: uv tool install -p 3.13 ".[gpu]"The git+ form clones the full repository history (about 2 minutes today).
Pass -p 3.13 so uv does not try an incompatible default Python. Add
,jax-pme-solver to the extras for the jax-pme long-range backend. The CUDA 12
and CUDA 13 extras are mutually exclusive. PyCHARMM still needs the native
libcharmm (see above; point CHARMM_LIB_DIR at it); everything else works
without it.
Register the project venv as its own kernel once, and select it in the
notebook (Kernel → Change Kernel → karml-venv):
.venv/bin/python -m ipykernel install --user --name karml-venv --display-name "karml venv"Without this, Jupyter's default python3 kernel may start a different
interpreter: the kernelspec uv installs uses a bare "python" in its argv,
so it resolves against PATH and picks up an active conda environment instead of
.venv. The symptom is an immediate
TypeError: 'type' object is not subscriptable
on the first import karml..., because that interpreter is too old to parse
tuple[float, ...] annotations. It looks like broken code but is purely kernel
selection. Check with import sys; print(sys.executable) — it must point inside
.venv.
# Conda
conda env create -f setup/environment.yml
conda activate karml
# Or Makefile micromamba targets (preferred on clusters)
make micromamba-create
make micromamba-create-gpu # CUDA 12 env file
make micromamba-create-gpu-cuda13GPU env files: setup/environment-gpu.yml, setup/environment-gpu-cuda13.yml.
Dockerfile and Compose live under devtools/docker/:
cd devtools/docker
docker compose up -d karml-cpu
docker compose exec karml-cpu bash
# GPU: docker compose up -d karml-gpuuv sync --extra cli
eval "$(register-python-argcomplete karml)"
# or: eval "$(karml completion bash)"karml -h # compact top-level help
karml commands # all subcommands by category
karml examples # copy-paste invocations
karml configure # interactive YAML / Snakemake wizard
karml env # checkpoints + CHARMM paths
karml md-system --help # condensed-phase MD flags
karml doctor # environment health checkCondensed-phase campaigns: start from
karml/cli/run/md_system.example.yaml
and the md-system YAML config guide.
CPU MD smokes (no CUDA; bundled DESdimers JSON checkpoint):
make install-md-cpu
source examples/md_cpu/_env.sh
bash examples/md_cpu/run_all.shSee examples/md_cpu/README.md.
ML-only energy/forces via ASE using the bundled ACO/DESdimers checkpoint
(examples/ckpts_json/DESdimers_params.json):
from pathlib import Path
import ase
import numpy as np
from karml.interfaces.pycharmmInterface.calculator_utils import unpack_factory_result
from karml.interfaces.pycharmmInterface.karml_calculator import setup_calculator
ATOMS_PER_MONOMER = 10
N_MONOMERS = 2
Z = np.array([6, 1, 1, 1, 6, 1, 1, 1, 8, 1] * N_MONOMERS, dtype=np.int32)
R = np.zeros((ATOMS_PER_MONOMER * N_MONOMERS, 3), dtype=np.float64)
# Place monomers apart so the dimer is non-overlapping
R[ATOMS_PER_MONOMER:, 0] = 5.0
ckpt = Path("examples/ckpts_json/DESdimers_params.json")
factory = setup_calculator(
ATOMS_PER_MONOMER=ATOMS_PER_MONOMER,
N_MONOMERS=N_MONOMERS,
doML=True,
doMM=False,
model_restart_path=str(ckpt),
MAX_ATOMS_PER_SYSTEM=ATOMS_PER_MONOMER * N_MONOMERS,
defer_xla_gpu_warmup=True,
verbose=False,
)
calc, _, _ = unpack_factory_result(
factory(atomic_numbers=Z, atomic_positions=R, n_monomers=N_MONOMERS)
)
atoms = ase.Atoms(numbers=Z, positions=R)
atoms.calc = calc
print("Energy (kcal/mol):", atoms.get_potential_energy())For a geometry-aware version of the same path, run
uv run python examples/md_cpu/02_ml_energy_ase.py.
Published site: Read the Docs.
Serve the current MkDocs tree locally: uv sync --extra dev && make docs-serve → http://127.0.0.1:8000.
Highlights (in-repo):
- Getting started — install, CLI, local docs
- CLI overview —
karml commands, examples, tab completion md-systemYAML configs — campaigns and condensed-phase builders- Calculator capability matrix — calculators, hybrid assembly, LR solvers
- PyCHARMM + MM/ML checklist — status, examples, diagrams
- MLpot settings — COM handoff, medium PBC, spatial MPI
- Documentation: Read the Docs
- Issues: GitHub Issues
MIT License, Copyright (c) 2025, Eric Boittier. See LICENSE for details.
Project based on the Computational Molecular Science Python Cookiecutter version 1.10.