novomcp-nnp¶

Neural network potentials for fast geometry optimization and energy prediction. The published image serves two backends: MACE and ANI-2x. GPU-accelerated; CPU works but is 10–50× slower.

Two axes, kept orthogonal: - method — which potential runs (mace / ani-2x). - engine — how it executes: ase (ASE BFGS optimizer, default) or alchemi (the NVIDIA ALCHEMI Toolkit GPU-batched relaxation dynamics running the same method potential on batched CUDA kernels). The ALCHEMI engine is what powers batch_geometry_relaxation, which relaxes a whole library in one batched pass instead of a per-molecule loop.

Pre-reqs¶

Docker
NVIDIA GPU recommended (L4 / A10G / L40S / A100 all fine)
CPU-only fallback for small molecules and low-throughput use
~2 GB RAM per active calculation
~1 GB disk for weights (bundled)

Deploy¶

# GPU
docker run -d \
  --name novomcp-nnp \
  --gpus all \
  -p 8032:8032 \
  --restart unless-stopped \
  ghcr.io/novomcp/novomcp-nnp:latest

# CPU only
docker run -d \
  --name novomcp-nnp \
  -p 8032:8032 \
  --restart unless-stopped \
  ghcr.io/novomcp/novomcp-nnp:latest

Wire into the engine¶

export NOVOMCP_NNP_URL=http://localhost:8032

Verify¶

curl -s http://localhost:8032/health
# {"status":"healthy","service":"novomcp-nnp","version":"1.0.0","port":8032,
#  "models":{"ani2x":{"available":true},"mace":{"available":true}},
#  "ready_models":["ani2x","mace"]}

Tools that light up¶

optimize_geometry_nnp, fast single-molecule NNP geometry optimization
compute_energy, single-point energy and forces (MLIP; batched via engine=alchemi)
batch_geometry_relaxation, library relaxation in one batched pass (built for the geometry phase of screen_oled_library / screen_electrolyte_library)
Model selection is the method argument (auto | ani2x | mace); execution engine is the engine argument (ase | alchemi)

Env vars¶

Var	Default	Purpose
`PORT`	`8032`	HTTP listen port
`DEFAULT_BACKEND`	`mace`	Model backend when caller doesn't specify `method`. Must be one the image serves (`mace` or `ani2x`).
`USE_GPU`	`auto`	Force `cpu` or `gpu`; `auto` detects at boot
`ALCHEMI_ENABLED`	`false`	Enable the `engine=alchemi` GPU-batched path (requires the `nvalchemi-toolkit` extra + a CUDA 12/13 GPU). When `false`, requests with `engine=alchemi` get a structured `503 alchemi backend not built` error.

ALCHEMI batched engine (optional)¶

The engine=alchemi path routes relaxation through the NVIDIA ALCHEMI Toolkit's batched dynamics — many systems co-resident on the GPU per kernel call. It runs the same method potential you'd use otherwise (MACE / ANI-2x); ALCHEMI is the execution layer, not a new model.

Build: the image must install the toolkit extra — pip install 'nvalchemi-toolkit[cu13]' --extra-index-url https://download.pytorch.org/whl/cu130 --extra-index-url https://pypi.nvidia.com (CUDA 12/13 only; no CPU wheels). Keep it an optional build arg so the base image stays CPU-installable.
Endpoints: POST /api/optimize-geometry accepts engine for single molecules; POST /api/relax-batch accepts {smiles_list, method, engine, fmax} and returns per-input relaxed XYZ + energy + convergence in input order, with per-item failures reported inline (a bad SMILES never fails the batch).
Status: the toolkit is public beta (API subject to change) — pin the version and keep the adapter thin so upstream churn is contained to one module.

Backend cheatsheet¶

MACE (MACE-MPA-0), strong general-purpose potential, good on periodic systems and materials. Recommended default.
ANI-2x, fast, covers H/C/N/O/S/F/Cl, wide validation on drug-like molecules.

These two are the only backends the published image serves. /health reports exactly which loaded, and requesting any other method (e.g. aimnet2) returns a structured "Model '<name>' not available" result rather than crashing. If you need another potential, build the image with its weights yourself.

Weights and licenses¶

The model weights are bundled in the image. The MACE backend uses MACE-MPA-0, which is MIT-licensed — not MACE-MP-0, whose Academic Software License forbids commercial use. So the MACE path is commercial-safe here. ANI-2x ships under its own upstream open license; if you run this commercially, confirm it against its source repository. The service code itself is Apache-2.0.

Speed¶

MACE opt (drug-sized molecule): ~0.5 s (GPU) / ~10 s (CPU)
Batch of 1000 molecules: ~2 min (GPU)