Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,37 @@ and versioning process.

## [Unreleased]

### Added

- **Opt-in analytic ML lattice strain virial** (`KARML_NPT_VIRIAL=analytic KARML_ML_LATTICE_VIRIAL=1`): the ML
lattice-shift virial is taken from the pair forces already computed, so forces and strain virial share one PhysNet
pass. Validated against the float64 reference to 1e-11 atm (float64) and 0.02-0.06 atm (float32 network). The default
virial (`fd64`) is unchanged. On an H200 NpT runs 1.3-1.6x faster, on a 1/64-FP64 card 3.7x.
- `KARML_JAXMD_TIMING_LOG` (per-record wall clock) and `KARML_NPT_VIRIAL_SELFCHECK_JSON` hooks for the JAX-MD backend.
- Persistent JAX compilation cache is now on by default for `md-system --backend jaxmd` and the trainer
(`KARML_NO_JAX_COMPILATION_CACHE=1` disables it).
- Opt-in `KARML_ML_CHUNK_REMAT=1`: `jax.checkpoint` around each ML chunk to cut the peak memory of the reverse-mode
strain-virial pass.
- `scripts/prepare_charmm_source.sh` and `setup/charmm_tarball_fixes.patch`: the CHARMM tarball is extracted without
macOS AppleDouble files and the 15 stale files are updated (library output name, restart-lattice fix in `dynio.F90`,
pyCHARMM cmake and python files). `make install-native` and `setup/install.sh` call it.
- Docs: GPU cluster runbook and the optional newer JAX / flax / jax-md stack (experimental, not the default pin).
- `CITATION.cff` (author and version fields to be completed at tag time) and `THIRD_PARTY_NOTICES.md`.
- `docs/RELEASE_BLOCKERS.md`, `KARML_CHARMM_LATTICE_VIRIAL` (experimental gate for the CHARMM path) and a `perf switches:` log line in `md-system`.

### Packaging

- pyCHARMM (GPL-3.0-or-later) is no longer packaged into the wheel/sdist (`karml*` only); it remains in the repository tree under its own licence.

### Not in this release

- The learned-charges work (DCMnet liquid charges), the Ewald-tail variants and the call-1 virial check are excluded from v0.1.0.
- The newer JAX / flax / jax-md stack is optional and documented, not the default pin (`jax<0.11.2` stays).

### Fixed

- Lint (ruff) and unit-suite collection on CI without pyCHARMM.

### Changed

- **Vendored CHARMM is c52a1** (15 August 2026), up from c49b1. ML/MM C API
Expand Down
32 changes: 32 additions & 0 deletions CITATION.cff
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
cff-version: 1.2.0
message: "If you use karml, please cite it as below (and the associated paper once published)."
title: "karml"
type: software
version: 0.1.0
# date-released is refreshed to the release day by the release script right before the tag is created.
date-released: 2026-11-18
abstract: >-
karml (pronounced Karamell) combines CHARMM MLpot and JAX-MD with JAX-based neural models (PhysNet, DCMNet and others)
for hybrid machine-learned/molecular-mechanics (ML/MM) condensed-phase simulations.
authors:
- family-names: Boittier
given-names: "Eric D."
affiliation: "Department of Chemistry, University of Basel, Klingelbergstrasse 80, CH-4056 Basel, Switzerland"
- family-names: Chaton
given-names: "Kham Lek"
affiliation: "Department of Chemistry, University of Basel, Klingelbergstrasse 80, CH-4056 Basel, Switzerland"
- family-names: Devereux
given-names: "Mike"
affiliation: "Department of Chemistry, University of Basel, Klingelbergstrasse 80, CH-4056 Basel, Switzerland"
- family-names: Meuwly
given-names: "Markus"
email: "m.meuwly@unibas.ch"
affiliation: "Department of Chemistry, University of Basel, Klingelbergstrasse 80, CH-4056 Basel, Switzerland"
repository-code: "https://github.com/EricBoittier/karml"
url: "https://github.com/EricBoittier/karml"
license: MIT
keywords:
- molecular dynamics
- machine-learned potentials
- ML/MM
- JAX
25 changes: 25 additions & 0 deletions RELEASE_NOTES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# karml 0.1.0

First tagged, citable release of karml: machine-learned potentials (PhysNet, DCMNet and others) in molecular-mechanics MD,
with two engines (CHARMM + MLpot and JAX-MD) sharing one model code. See `CHANGELOG.md` for the full history.

## Highlights of this release
- Opt-in analytic ML lattice strain virial for JAX-MD NpT (`KARML_NPT_VIRIAL=analytic KARML_ML_LATTICE_VIRIAL=1`): forces and strain virial in one
PhysNet pass, validated against the float64 reference; 1.3-1.6x faster NpT on an H200, 3.7x on a 1/64-FP64 GPU. Defaults are unchanged (`fd64` virial).
- Persistent JAX compilation cache by default for `md-system --backend jaxmd` and the trainer (`KARML_NO_JAX_COMPILATION_CACHE=1` disables).
- Opt-in `KARML_ML_CHUNK_REMAT=1` for lower memory in the strain-virial reverse pass; `md-system` logs which virial path and opt-ins are active.
- Clean install fixed: the CHARMM tarball is extracted without macOS `._*` files and with the 15 stale-file fixes (`make install-native`).
- GPU cluster runbook (`docs/gpu-cluster-runbook.md`) and an optional, experimental newer JAX / flax / jax-md stack (`docs/newer-jax-stack.md`).
- Repository hygiene (no personal paths), CI repaired where possible (`docs/RELEASE_BLOCKERS.md` lists what is left).

## Known limitations
- The analytic lattice virial in the CHARMM CPT path is experimental and not validated (`KARML_CHARMM_LATTICE_VIRIAL=1`).
- The learned-charges work, Ewald-tail variants and the call-1 virial check are not part of this release.
- The newer JAX stack is optional; the default pin stays `jax<0.11.2`.

## Licences
karml is MIT. The CHARMM sources and pyCHARMM bindings under `setup/` keep their own terms (`THIRD_PARTY_NOTICES.md`); pyCHARMM
(GPL-3.0-or-later) is not part of the wheel/sdist.

## Citation
See `CITATION.cff`. This release has no DOI (Zenodo archiving is not enabled).
22 changes: 22 additions & 0 deletions THIRD_PARTY_NOTICES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# Third-party software and data shipped in this repository

karml itself is MIT-licensed (see `LICENSE`). The repository also contains third-party material under its own terms.
This file records what is there; entries marked TODO need the maintainer's confirmation before a release.

| component | location | licence | note |
|---|---|---|---|
| CHARMM (c52a1 source tree, with MLpot/ML-MM C API patches) | `setup/charmm.tar.xz` (extracted to `setup/charmm/`), fixes in `setup/charmm_tarball_fixes.patch`, overlays in `setup/nbonds/`, `setup/image/` | CHARMM licence agreement, see the CHARMM project (<https://www.charmm.org/>) | the tarball carries no top-level CHARMM licence file and the Fortran sources have no licence header; see the statement below |
| pyCHARMM (Python bindings, `setup/charmm/tool/pycharmm`) | inside the CHARMM tarball | GNU GPL v3 or later (file headers and `tool/pycharmm/LICENSE`, copyright J. Buckner) | kept in the repository tree under its own licence; **not packaged** into the karml wheel/sdist (`pyproject.toml` packages `karml*` only), so the MIT wheel contains no GPL code |
| Packmol | `karml/generate/packmol/` | MIT (`karml/generate/packmol/LICENSE`) | |
| CHARMM force-field files (CGenFF, topology/parameter files) | `karml/data/charmm/`, `setup/charmm/toppar` | CGenFF/CHARMM force-field terms of the MacKerell lab; [maintainer to confirm] | |
| CHARMM source overlays (nonbonded and image routines, incl. DCM/GRaPe modules) | `setup/nbonds/`, `setup/image/` | part of CHARMM, see the CHARMM statement below | |

## CHARMM redistribution statement

[maintainer to confirm] Whether and on what terms the CHARMM sources in `setup/` may be redistributed. The exact licence text or URL, the permitted-redistribution wording and the date of the agreement
have not been verified from this repository; replace this line by the confirmed statement before the release is tagged.

## Wheel and sdist

The published wheel and sdist contain the `karml` package only (MIT). `setup/charmm.tar.xz`, `setup/charmm_tarball_fixes.patch`
and the pyCHARMM sources are part of the git repository (and its GitHub/Zenodo source archive) but not of the PyPI artefacts.
15 changes: 15 additions & 0 deletions docs/releasing.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,3 +50,18 @@ and [Getting started](getting-started.md).

Do **not** commit new large/regenerable artifacts; `.gitignore` already covers
`node_modules/`, `*.dcd`, `*.traj`, `*.parquet`, `karml/models/EF/data/`, etc.

## Citable release and Zenodo (first release)

1. `CITATION.cff` carries the author list of the manuscript (no ORCID iDs) and `version: 0.1.0`; `release.sh` refreshes `date-released` before tagging.
2. Resolve the `[maintainer to confirm]` line in `THIRD_PARTY_NOTICES.md` (CHARMM redistribution statement). pyCHARMM (GPL-3.0-or-later) is not packaged: `pyproject.toml` builds `karml*` only, so the wheel/sdist are MIT-only; the pyCHARMM sources stay in the repository tree under their own licence.
3. Zenodo is ON HOLD: no `.zenodo.json`, integration off. A DOI is minted only if the GitHub integration is switched on later (<https://zenodo.org/account/settings/github/>) before a release is published; `release.sh` creates the release only with `--yes` and states that no DOI exists.
4. Tag and publish (see above). First tag: `v0.1.0` (decided; no PyPI upload for it). `versioningit` derives the version from the
tag, so nothing in the tree is bumped. Use `v0.1.0a1` instead if the aim is a PyPI pre-release that plain
`pip install karml` does not select.
5. If Zenodo is enabled, the DOI exists only after the GitHub release has been archived; add it to `CITATION.cff` and the README badge in a follow-up commit (do not move the tag).

See also the [GPU cluster runbook](gpu-cluster-runbook.md).

The scripted version of these steps is `release.sh` (checks open PRs, CI on main, placeholders in `CITATION.cff`, tags,
pushes, creates the GitHub release, and prints the Zenodo DOI and the patches for `refs.bib`, `CITATION.cff` and the README badge).
6 changes: 4 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -342,8 +342,10 @@ include-package-data = false

[tool.setuptools.packages.find]
namespaces = false
where = [".", "setup/charmm/tool/pycharmm"]
include = ["karml*", "pycharmm*"]
# pyCHARMM (GPL-3.0-or-later, setup/charmm/tool/pycharmm) is deliberately NOT packaged: it stays in the repository tree under
# its own licence (see THIRD_PARTY_NOTICES.md); the MIT wheel/sdist contain karml only.
where = ["."]
include = ["karml*"]

[tool.setuptools.package-data]
karml = [
Expand Down
Loading