karml

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.

Status

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.

Quick Installation

Requires Python 3.13. The published package is a ~4 MB wheel. It does not include the CHARMM tarball or the git history.

A v* tag publishes to PyPI (see Releasing). Until the first tag is pushed, pip install karml is not on the index yet — use a checkout, below.

pip

pip install karml
pip install "karml[cli]"          # shell tab completion
pip install "karml[gpu]"          # CUDA 13 wheels (SM 7.5+); driver only
pip install "karml[gpu-cuda12]"   # CUDA 12 wheels (older GPUs / drivers)

JAX's CUDA wheels bring their own CUDA runtime and cuDNN. The CUDA 12 and CUDA 13 extras are mutually exclusive. Add jax-pme-solver to the extras for the jax-pme long-range backend.

uv tool

Installs the karml command into its own environment. Pass -p 3.13 so uv does not try an incompatible default Python.

uv tool install -p 3.13 karml
uv tool install -p 3.13 "karml[gpu]"
uv tool install -p 3.13 "karml[gpu-cuda12]"

conda / micromamba

Conda supplies Python. The package itself comes from PyPI, because the JAX stack is not a conda-forge package set we pin.

conda env create -f setup/environment-user.yml
conda activate karml

# GPU
conda env create -f setup/environment-user-gpu.yml          # CUDA 13
conda env create -f setup/environment-user-gpu-cuda12.yml   # CUDA 12

Micromamba accepts the same files (micromamba env create -f ...).

From a checkout (development, or PyCHARMM)

pip / uv tool / the conda env files do not build libcharmm or Packmol. Those are native libraries. From a clone:

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 12

make install-native   # builds libcharmm + packmol under setup/charmm
make doctor           # karml doctor — env / CHARMM readiness

Or from a fresh clone: make install-full (uv sync + native build).

Point CHARMM_LIB_DIR at setup/charmm if auto-discovery does not find it. The charmm.tar.xz asset on each GitHub release is that same tree, for a machine that installed the wheel and still needs PyCHARMM.

Jupyter kernel (required for the example notebooks)

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.

Using Conda / micromamba

# 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-cuda13

GPU env files: setup/environment-gpu.yml, setup/environment-gpu-cuda13.yml.

Using Docker

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-gpu

CLI tab completion

uv sync --extra cli
eval "$(register-python-argcomplete karml)"
# or: eval "$(karml completion bash)"

CLI quick start

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 check

License

MIT License, Copyright (c) 2025, Eric Boittier. See LICENSE for details.

Acknowledgements

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