Metadata-Version: 2.4
Name: karml
Version: 0.1.0a1
Summary: karml (pronounced Karamell): machine-learned potentials in molecular-mechanics MD
Author-email: Eric Boittier <eric.boittier@icloud.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/EricBoittier/karml
Project-URL: Documentation, https://karml.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/EricBoittier/karml
Project-URL: Issues, https://github.com/EricBoittier/karml/issues
Project-URL: Changelog, https://github.com/EricBoittier/karml/releases
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.14,>=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: jax<0.11.2,>=0.10.0
Requires-Dist: jaxlib<0.11.2,>=0.10.0
Requires-Dist: jax-md>=0.2.29
Requires-Dist: flax>=0.12.1
Requires-Dist: optax
Requires-Dist: jaxtyping
Requires-Dist: orbax-checkpoint
Requires-Dist: ml-dtypes
Requires-Dist: ase
Requires-Dist: pyyaml
Requires-Dist: chemcoord
Requires-Dist: numba>=0.61
Requires-Dist: tqdm
Requires-Dist: rich
Requires-Dist: pint
Requires-Dist: h5py>=3.8.0
Requires-Dist: apsw>=3.45.0
Requires-Dist: e3x>=1.0.2
Requires-Dist: tblite
Requires-Dist: plotnine>=0.15.1
Requires-Dist: patchworklib>=0.6.6
Requires-Dist: pillow>=12.0.0
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: pymbar>=4.0
Requires-Dist: umap-learn>=0.5.12
Provides-Extra: charmm-interface
Requires-Dist: mpi4py; extra == "charmm-interface"
Provides-Extra: plotting
Requires-Dist: asciichartpy>=1.5.25; extra == "plotting"
Requires-Dist: polars; extra == "plotting"
Requires-Dist: cmap>=0.3.0; extra == "plotting"
Provides-Extra: nl-validation
Requires-Dist: vesin>=0.6.1; extra == "nl-validation"
Provides-Extra: cli
Requires-Dist: argcomplete>=3.5.0; extra == "cli"
Provides-Extra: scafacos-interface
Requires-Dist: mpi4py; extra == "scafacos-interface"
Provides-Extra: nvalchemiops-pme
Requires-Dist: nvalchemi-toolkit-ops[jax]; extra == "nvalchemiops-pme"
Provides-Extra: metatomic
Requires-Dist: metatomic-ase>=0.1.1; extra == "metatomic"
Requires-Dist: metatomic-torch>=0.1.12; extra == "metatomic"
Requires-Dist: upet>=0.3.0; extra == "metatomic"
Requires-Dist: metatrain>=2026.4; extra == "metatomic"
Provides-Extra: jax-pme-solver
Requires-Dist: jax-pme>=0.1.0; extra == "jax-pme-solver"
Provides-Extra: md-cpu
Requires-Dist: vesin>=0.6.1; extra == "md-cpu"
Requires-Dist: mdanalysis; extra == "md-cpu"
Requires-Dist: mda-xdrlib; extra == "md-cpu"
Provides-Extra: mbar
Requires-Dist: pymbar>=4.0; extra == "mbar"
Provides-Extra: nl-gpu
Requires-Dist: vesin>=0.6.1; extra == "nl-gpu"
Requires-Dist: cupy-cuda13x<14,>=13.0.0; extra == "nl-gpu"
Provides-Extra: gpu
Requires-Dist: jax[cuda13]; extra == "gpu"
Requires-Dist: nvidia-cudnn-cu13>=9.10.1; extra == "gpu"
Requires-Dist: cupy-cuda13x<14,>=13.0.0; extra == "gpu"
Requires-Dist: cutensor-cu13>=2.0.0; extra == "gpu"
Requires-Dist: mpi4py; extra == "gpu"
Provides-Extra: gpu-cuda12
Requires-Dist: jax[cuda12]>=0.9.0; extra == "gpu-cuda12"
Requires-Dist: cupy-cuda12x<14,>=13.0.0; extra == "gpu-cuda12"
Requires-Dist: cutensor-cu12>=2.0.0; extra == "gpu-cuda12"
Requires-Dist: mpi4py; extra == "gpu-cuda12"
Provides-Extra: quantum
Requires-Dist: pyscf>=2.8.0; extra == "quantum"
Requires-Dist: basis-set-exchange>=0.11; extra == "quantum"
Requires-Dist: pyscf-dispersion>=1.3.0; sys_platform == "linux" and extra == "quantum"
Requires-Dist: pyscf-dispersion<1.5,>=1.3.0; (sys_platform == "darwin" and platform_machine == "x86_64") and extra == "quantum"
Requires-Dist: geometric>=1.1.0; extra == "quantum"
Requires-Dist: dscribe; extra == "quantum"
Provides-Extra: quantum-gpu
Requires-Dist: karml[quantum]; extra == "quantum-gpu"
Requires-Dist: gpu4pyscf-cuda13x; extra == "quantum-gpu"
Requires-Dist: gpu4pyscf-libxc-cuda13x; extra == "quantum-gpu"
Provides-Extra: quantum-gpu-cuda12
Requires-Dist: karml[quantum]; extra == "quantum-gpu-cuda12"
Requires-Dist: gpu4pyscf-cuda12x; extra == "quantum-gpu-cuda12"
Requires-Dist: gpu4pyscf-libxc-cuda12x; extra == "quantum-gpu-cuda12"
Provides-Extra: quantum-crosscheck
Requires-Dist: tblite; extra == "quantum-crosscheck"
Provides-Extra: ml
Requires-Dist: e3x; extra == "ml"
Requires-Dist: lovely-jax; extra == "ml"
Provides-Extra: viz
Requires-Dist: plotly; extra == "viz"
Requires-Dist: plotnine; extra == "viz"
Requires-Dist: seaborn; extra == "viz"
Requires-Dist: scienceplots; extra == "viz"
Requires-Dist: cmcrameri; extra == "viz"
Requires-Dist: patchworklib>=0.6.0; extra == "viz"
Requires-Dist: py3dmol; extra == "viz"
Provides-Extra: md
Requires-Dist: vesin>=0.6.1; extra == "md"
Requires-Dist: mdanalysis; extra == "md"
Requires-Dist: mda-xdrlib; extra == "md"
Requires-Dist: mmtf-python; extra == "md"
Requires-Dist: griddataformats; extra == "md"
Requires-Dist: mrcfile; extra == "md"
Provides-Extra: chem
Requires-Dist: chemcoord; extra == "chem"
Requires-Dist: pubchempy; extra == "chem"
Requires-Dist: pyxtal; extra == "chem"
Requires-Dist: molzip; extra == "chem"
Requires-Dist: sphynx>=0.0.3; extra == "chem"
Provides-Extra: data
Requires-Dist: polars; extra == "data"
Requires-Dist: pyarrow; extra == "data"
Requires-Dist: fastparquet<2026; extra == "data"
Provides-Extra: notebooks
Requires-Dist: ipykernel; extra == "notebooks"
Requires-Dist: ipython; extra == "notebooks"
Requires-Dist: ipywidgets; extra == "notebooks"
Requires-Dist: jupyter-client; extra == "notebooks"
Requires-Dist: jupyter-core; extra == "notebooks"
Requires-Dist: nbformat; extra == "notebooks"
Provides-Extra: experiments
Requires-Dist: wandb>=0.15.0; extra == "experiments"
Requires-Dist: hydra-core>=1.3.0; extra == "experiments"
Requires-Dist: omegaconf>=2.3.0; extra == "experiments"
Requires-Dist: hydra-optuna-sweeper>=1.2.0; extra == "experiments"
Provides-Extra: dev
Requires-Dist: pytest>=6.1.2; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ipykernel>=6.30.1; extra == "dev"
Requires-Dist: mkdocs<2.0,>=1.6; extra == "dev"
Requires-Dist: mkdocs-material>=9.7; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.30; extra == "dev"
Requires-Dist: reportlab>=4.0; extra == "dev"
Requires-Dist: ruff>=0.15; extra == "dev"
Requires-Dist: vulture>=2.16; extra == "dev"
Requires-Dist: asv>=0.6.4; extra == "dev"
Provides-Extra: all
Requires-Dist: karml[charmm-interface,chem,data,experiments,gpu,md,ml,notebooks,plotting,quantum,quantum-gpu,viz]; extra == "all"
Provides-Extra: all-cuda12
Requires-Dist: karml[chem,data,experiments,gpu-cuda12,md,ml,notebooks,plotting,quantum,quantum-gpu-cuda12,viz]; extra == "all-cuda12"
Provides-Extra: all-cuda13
Requires-Dist: karml[chem,data,experiments,gpu,md,ml,notebooks,plotting,quantum,quantum-gpu,viz]; extra == "all-cuda13"
Provides-Extra: all-cpu
Requires-Dist: karml[chem,data,experiments,md,md-cpu,ml,notebooks,plotting,quantum,viz]; extra == "all-cpu"
Dynamic: license-file

<h1 align="center">karml</h1>

[![CI](https://github.com/EricBoittier/karml/workflows/CI/badge.svg)](https://github.com/EricBoittier/karml/actions?query=workflow%3ACI)
[![codecov](https://codecov.io/gh/EricBoittier/karml/branch/main/graph/badge.svg)](https://codecov.io/gh/EricBoittier/karml/branch/main)
[![Docs](https://readthedocs.org/projects/karml/badge/?version=latest)](https://karml.readthedocs.io/en/latest/)
[![Python](https://img.shields.io/badge/python-3.13-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Status: Alpha](https://img.shields.io/badge/status-alpha-orange.svg)](#status)

**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](#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](docs/releasing.md)). Until the
first tag is pushed, `pip install karml` is not on the index yet — use a
checkout, below.

### pip

```bash
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.

```bash
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.

```bash
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:

```bash
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`):

```bash
.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

```bash
# 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/`](devtools/docker/):

```bash
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

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

## CLI quick start

```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 check
```

## License

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

## Acknowledgements

Project based on the [Computational Molecular Science Python Cookiecutter](https://github.com/molssi/cookiecutter-cms) version 1.10.
