Calculator and electrostatics capability matrix¶

This page inventories calculator implementations and states where they are actually supported. It also separates calculator choice from hybrid energy assembly, MM charge mode, MM nonbond mode, long-range solver, and MD driver.

“Implemented” does not automatically mean “supported by every CLI.” The narrowest public interface wins. The canonical dimer calculator surface is checked directly against its parser and factory tests rather than copied from a dated snapshot. [evidence: dimer_calculator_surface]

The independent axes¶

flowchart LR
    Surface["User surface<br/>dimer-scan / md-system / evaluate / Python"]
    Model["Molecular calculator<br/>PhysNet / SpookyNet / QC / MBD / multipoles"]
    Assembly["Hybrid assembly<br/>doML / doML_dimer / doMM"]
    Charges["MM charge source<br/>fixed / Q0 / Q1 / latent variants"]
    Nonbond["MM nonbond mode<br/>jax_mic / periodic_external"]
    LR["Long-range solver<br/>mic / ewald / jax_pme / nvalchemiops / ScaFaCoS"]
    Driver["Execution driver<br/>ASE / JAX-MD / PyCHARMM"]

    Surface --> Model
    Surface --> Driver
    Model --> Assembly
    Assembly --> Charges
    Charges --> Nonbond
    Nonbond --> LR

Changing the MD driver does not select a different charge mode. Enabling a PhysNet charge head does not automatically replace the charges used by MM. Selecting JAX-PME does not select the ML model. These choices must be recorded independently in scientific provenance.

Canonical 1D dimer scan calculators¶

These calculator names are accepted by mmml dimer-scan.

The artifact contract is tested independently of calculator choice: successful runs preserve a versioned manifest, extxyz trajectory, and ASE trajectory containing energy and forces. [evidence: dimer_artifact_contract]

`--calculator`	Implementation	Checkpoint	Properties used	Charge inputs	Where supported
`physnet`	`mmml.interfaces.calculators.checkpoint_loading.create_calculator_from_checkpoint`	Required: portable JSON, joint pickle, or Orbax/directory formats understood by the centralized loader	Energy and forces; interaction energy/forces are dimer minus isolated monomers	Optional total `--charge` and `--spin` are supported by the joint `SimpleInferenceCalculator` path; standalone PhysNet checkpoints currently reject explicit values	Canonical Python `run_dimer_scan` and `mmml dimer-scan`
`xtb`	`mmml.analysis.dimer_scans.make_xtb_calculator`	None; uses `xtb-python`, falling back to `tblite`	Energy and forces through ASE	`--method` selects the xTB method (default GFN2-xTB); the current dimer CLI does not expose backend-specific UHF options	Canonical Python `run_dimer_scan` and `mmml dimer-scan`
`spookynet`	`SpookyNetCalculator`	Required	Energy and forces	`--charge`; `--spin` is multiplicity	Canonical dimer scan
`mbd`	`QCMLMBDCalculator`	Required	Learned MBD energy and forces	`--charge`; `--spin` is multiplicity	Canonical dimer scan
`multipoles`	`LearnedMolecularMultipoleElectrostatics`	Required	Energy and complete central-finite-difference forces	Fragment charges/multiplicities currently default to neutral singlets	Canonical dimer scan; finite-difference step is recorded
`efield`	`EFieldCalculator`	Parameter JSON required; optional model config JSON	Energy, forces, dipole; scan requests E/F	Explicit `--electric-field EX EY EZ` in atomic units	Canonical dimer scan
`dftb3-d4`	ASE DFTB+ adapter	No model checkpoint; requires DFTB+ and 3ob-3-1 Slater–Koster directory	Energy and forces	DFTB method state	Canonical dimer scan with explicit scratch directory
`pyscf`	Lazy `PySCFDimerCalculator`	None; requires PySCF	HF or DFT energy and analytic nuclear-gradient forces	`--charge`; `--spin` is multiplicity	Canonical dimer scan; `--method hf\|dft`, `--basis`, and `--xc`

The physnet loader supports standalone PhysNet energy/force checkpoints and joint PhysNet + DCMNet/non-equilibrium checkpoints. For joint checkpoints the ASE adapter still supplies the energy/force path; optional dipole, charge, and multipole results depend on the checkpoint architecture.

Hybrid ML/MM and JAX CGenFF spoof remain on the specialized PyCHARMM scan path, not the canonical calculator factory. They require residue-specific PSF/CGenFF state, MLpot handoff configuration, and often a periodic runtime; treating them as checkpoint-only ASE calculators would hide scientifically material inputs. The existing scan_mlpot_dimer_2d_pycharmm.py --scan-1d path supports both, and should be migrated by representing those inputs in DimerScanConfig.

Calculator implementations elsewhere in MMML¶

Calculator family	ASE properties	Primary implementation	Supported surfaces	Important limitations
PhysNet / joint PhysNet+DCMNet inference	Energy, forces; adapter may also expose dipole, charges, multipoles	`mmml.interfaces.calculators.simple_inference` and `checkpoint_loading`	Python ASE use; evaluation commands; hybrid MLpot model loading; canonical dimer scan	Checkpoint atom-padding capacity and architecture must match the system.
SpookyNet / SpookyPhysNet	Energy, forces	`mmml.models.spookynet_calc.SpookyNetCalculator`	Python ASE use; Spooky evaluation/training scripts; hybrid MLpot when checkpoint architecture resolves as Spooky	Standalone adapter does not provide the dynamic CGenFF arrays used by every hybrid architecture. Optional frozen MBD is loaded when recorded/configured.
SpookyNet + frozen MBD correction	Energy, forces	`SpookyNetCalculator` with `mbd_checkpoint` and `mbd_weight`	Python ASE evaluation; checkpoint-matched evaluation paths; PyCHARMM hybrid setup also accepts an MBD correction	Recorded cluster-local checkpoint paths may need explicit remapping. Weight must match training.
Learned QCML MBD surrogate	Energy, forces	`mmml.models.mbd.QCMLMBDCalculator`	Python ASE use; standalone evaluation; optional correction in hybrid paths	Requires MBD checkpoint; molecular charge and multiplicity are explicit inputs.
Learned molecular multipole electrostatics	Energy and finite-difference forces	`mmml.models.multipoles.LearnedMolecularMultipoleElectrostatics`	Canonical dimer scan; Python ASE use; multipole analysis; JAX-MD unified force-field build can freeze learned fragment multipoles	Forces differentiate predicted moments, origins, and interaction energy by central differences; accurate but substantially slower than an eventual JAX autodiff kernel.
E-field PhysNet	Energy, forces, dipole, polarizability	`mmml.models.efield.ase_calc_EF.EFieldCalculator`	Canonical dimer scan, `efield-evaluate`, `efield-md`, and Python use	Requires the external-field model/input contract; not wired to every hybrid MLpot assembly.
DCMNet property calculator	Charges, dipole, multipoles	`mmml.models.dcmnet.dcmnet_ase.DCMNetCalculator`	Python/property evaluation and joint-model workflows	Property-only: no standalone energy/forces. The joint PhysNet+DCMNet loader supplies E/F through PhysNet.
PySCF CPU ASE calculator	Energy, forces, dipole	`mmml.interfaces.pyscf4gpuInterface.cpu.PYSCF`	Python ASE use and QC scripts	Requires a configured PySCF mean-field/post-HF object; method-dependent runtime and gradients.
GPU4PySCF ASE calculator	Public declaration currently energy-only; calculation code has method-specific gradient paths	`mmml.interfaces.pyscf4gpuInterface.aseInterface.PYSCF`	GPU PySCF CLI/campaign paths and Python use	Do not assume generic ASE force support from `implemented_properties`; use the dedicated PySCF evaluation commands for supported E/F workflows.
xTB / tblite	Energy and forces through upstream ASE adapter	`make_xtb_calculator`	Canonical dimer scan, cross-check workflow, Python use	Optional dependency/runtime; method defaults to GFN2-xTB.
DFTB3-D4	Energy/forces through ASE DFTB+ adapter	`mmml.analysis.dimer_scans.make_dftb3_d4_calculator`	Canonical dimer scan, reference campaigns, and Python use	Requires external DFTB+ executable, complete 3ob-3-1 Slater–Koster files, and explicit scratch directory.
Molecular/monomer-sum PhysNet composition	Energy, forces	`MolecularPhysNetCalculator`, `MonomerSumCalculator`	Python ASE composition workflows	Intramolecular sum only; intermolecular terms require another calculator/assembly layer.
JAX intermolecular CGenFF nonbonded	Energy, forces	`JAXIntermolecularCalculator`	Python ASE hybrid composition and internal hybrid paths	Needs prepared nonbond parameters, cell, molecule IDs, and explicit units.
Full hybrid ML/MM MLpot	Energy, forces, decomposition/diagnostics	`mmml.interfaces.pycharmmInterface.mmml_calculator.setup_calculator` and `DecomposedMlpotCalculator`	`mmml md-system` with ASE, JAX-MD, or PyCHARMM routes; lambda TI; specialized dimer/PBC campaigns	Compatibility depends on energy assembly, MM charge mode, nonbond mode, LR solver, PBC, checkpoint charge head, and system size. See matrices below.
JAX CGenFF “ML spoof”	Energy, forces	hybrid setup with `--jax-mm-spoof` / `ml_potential_mode="jax_mm_clone"`	`md-system` infrastructure and parity testing	Validation/infrastructure mode, not a learned potential or scientific replacement for PhysNet.
JAX CGenFF spoof dimer scan	Energy, forces, hybrid decomposition	`scan_mlpot_dimer_2d_pycharmm.py --scan-1d --jax-mm-spoof` and MLpot setup	Specialized 1D/2D PyCHARMM scan campaigns	Requires PSF/CGenFF construction and handoff/MM settings; not yet represented by canonical `DimerScanConfig`.
Pure CHARMM/CGenFF	CHARMM energy/forces	PyCHARMM runtime and MLpot setup with ML disabled or separate pure-MM routes	`md-system --backend pycharmm`, liquid-box preparation, validation workflows	Requires compiled CHARMM/PyCHARMM and topology/parameter assets.

Legacy mmml.interfaces.aseInterface.dimers is excluded from supported calculator surfaces: it mutates environment/device state and contains machine-specific execution at import time.

Hybrid energy assembly modes¶

These booleans control energy terms, independently of mm_charge_mode.

Assembly	`doML`	`doML_dimer`	`doMM`	Meaning	Typical surface
Full hybrid	yes	yes	yes	Isolated ML monomers + switched ML dimer correction + MM intermolecular terms	Default hybrid `md-system`, lambda TI, MLpot campaigns
ML-only hybrid decomposition	yes	yes	no	ML monomers and ML dimer interaction; no MM pair term	`--no-include-mm`, force/energy diagnosis
Monomer ML + MM	yes	no	yes	ML intramolecular monomers plus MM intermolecular interaction; skips ML dimer correction	`--skip-ml-dimers`, or a dimer placed past the ML→MM handoff (see small-system Ewald example)
Monomer ML only	yes	no	no	Sum of isolated molecular ML energies only	Decomposition/testing, not a complete condensed-phase potential
MM-only	no	no	yes	CGenFF/JAX/PyCHARMM MM terms without model evaluation	Pure-MM preparation/validation paths; not the default hybrid CLI assembly
JAX MM spoof	clone	clone	configurable	JAX CGenFF bonded clone occupies the ML slots for infrastructure parity	`--jax-mm-spoof` validation

--include-mm/--no-include-mm is the main public switch for doMM. doML_dimer is exposed by older/specialized runners as --skip-ml-dimers; the unified md-system paths normally keep it enabled.

Monomer ML + MM with native Ewald (fixed vs latent)¶

This is the smallest supported check that the Monomer ML + MM assembly composes with --lr-solver ewald for both Mode A (fixed) and Mode B (latent / q1) charges. It does not require a liquid box (Mode B is dimer-only) and does not need a trained checkpoint for the kernel-level smoke.

Surface	System	What it proves	Location
Analytic / no CHARMM	2 monomers × 2 atoms (+1 pad), 30 Å box	`hybrid_forward(..., lr_solver="ewald")` for `fixed` and `latent`; `e_mm` matches `compute_native_ewald_coulomb`	`examples/hybrid_mm_charges/monomer_ml_mm_ewald_example.py`
Unit regression	Same geometry, mocked charge head	Finite distinct `e_mm`; `ml_scale → 0` past the handoff	`tests/unit/test_hybrid_energy.py::test_ewald_monomer_ml_plus_mm_fixed_and_latent`
PyCHARMM MD (optional bonded)	`DCM:2` PBC smoke	Same assembly under `md-system` with CHARMM bonded left on	`md_fixed_ewald_dimer.yaml`, `md_latent_ewald_dimer.yaml`

# No checkpoint / no CHARMM — preferred first check
python examples/hybrid_mm_charges/monomer_ml_mm_ewald_example.py

# Fast regression (mocked)
uv run pytest tests/unit/test_hybrid_energy.py::test_ewald_monomer_ml_plus_mm_fixed_and_latent -q

Charge-mode taxonomy and train/MD YAML pairs live in Hybrid MM charges. MM bonded terms are orthogonal: native Ewald owns intermolecular Coulomb in E_MM, while PyCHARMM may still evaluate BOND/ANGL/DIHE on the PSF. The DCM:2 YAMLs keep that bonded contribution; the analytic example above is Coulomb-only (include_lj=False, no bonded topology).

Charge concepts: four different things¶

Charge concept	Controls	Where
Molecular total charge and spin/multiplicity	Electronic/model state for a complete structure	Dimer scan `--charge`, `--spin`; Spooky, MBD, PySCF, and related calculator constructors
PhysNet charge head	Predicted atomic charges used for dipoles and made available as `q_ML`	Checkpoint architecture (`charges=True`)
PhysNet internal electrostatics	Whether predicted charges contribute Coulomb energy inside `E_ML`	Model/checkpoint `include_electrostatics`; independent of MM charge mode
Hybrid MM charge mode	Charges used in intermolecular `E_MM` Coulomb	`--mm-charge-mode`; table below

Enabling a charge head does not by itself put q_ML into E_MM. Conversely, fixed MM charges can be used while the ML model still has internal learned electrostatics.

Hybrid MM charge modes¶

CLI mode	MM Coulomb charges	Charge head required	System size	Training parity	LR compatibility enforced by current setup
`fixed` (Mode A, default)	`q_CGenFF` from PSF/RTF	no	Any	Train + MD	All implemented LR solvers, subject to nonbond-mode requirements
`q0` (Q⁰)	Neutralized charges from isolated monomer forwards	yes	Any number of monomers	Same Q⁰ operator in train + MD	MIC and pure-JAX `ewald`; live ML charges are refused with `jax_pme`. External-solver combinations require dedicated parity validation before production use.
`latent` / `q1` (Mode B/Q¹)	Neutralized partner-perturbed charges from the AB forward	yes	Exactly two monomers	Train + dimer MD	Dimer-only; MIC or pure-JAX `ewald`; JAX-PME and chunked multi-GPU apply are refused
`fixed_plus_latent` (Mode C)	`q_CGenFF + neutralized Q¹`	yes	Exactly two monomers	Train + dimer MD	Same restrictions as `latent`; `--mm-charge-correction` is an alias
`latent_mean` (Mode D)	Frozen offline mean latent-charge template tiled over monomers	no live head	Homogeneous systems matching the template	MD-only approximation	Static charges can be used by the implemented LR solvers; requires `--mm-latent-charge-template`
`latent_dynamic` (Mode E)	Live weighted mean of Q¹ over active ML dimers	yes	Any number of monomers	MD-only heuristic	Requires `doML` and `doML_dimer`; JAX-PME and chunked ML apply are refused; validate other external-solvers explicitly

The conservative production rule is stricter than “the parser accepts it”: live position-dependent charges (q0, latent, fixed_plus_latent, latent_dynamic) need force/energy and train/MD parity checks for the exact LR path. The NVE finite-difference preflight freezes these charges where required because the implemented MM force is a Hellmann–Feynman derivative at fixed charge, not the total derivative of E(R, q(R)).

MM nonbond modes¶

`--mm-nonbond-mode`	Short-range/MM implementation	VDW	Coulomb	Supported drivers
`jax_mic` (default)	Switched JAX pair loop using molecular minimum-image geometry	JAX CGenFF LJ, normally switched through the handoff region	`mic`, `ewald`, or JAX-PME k-space plus switched pair short range	ASE and JAX-MD hybrid calculators; used inside PyCHARMM MLpot callback as well
`periodic_external`	Full-box external Coulomb with PyCHARMM periodic nonbond infrastructure	CHARMM IMAGE VDW by default; may be disabled	JAX-PME, nvalchemiops PME, ScaFaCoS, or pure-JAX Ewald	PyCHARMM-backed periodic MLpot paths; requires a periodic cell/runtime

periodic_external is not simply “a more accurate jax_mic.” It changes ownership of VDW and Coulomb terms, so switching between them is a scientific method change that belongs in the manifest.

Long-range solver compatibility¶

`--lr-solver`	Active method	`jax_mic`	`periodic_external`	Runtime notes
`auto`	Legacy alias resolving to `mic`	yes	Not a meaningful external choice	Record the resolved active solver, not only `auto`
`mic`	Truncated/switched minimum-image Coulomb	yes, default	No supported full-box external MIC mode	No external PME library
`ewald`	MMML pure-JAX full-box Ewald operator, train-matched	yes	yes	Requires PBC; no external PME package or CUDA requirement. Optional `--ewald-omit-self` selects the MIC/non-Ewald-trained compatibility operator (cross-monomer Ewald only: omit intramolecular Coulomb and the Gaussian self term). Default full-box Ewald retains both for Ewald-trained models. Distinct from `jax_pme --jax-pme-method ewald`. Dimer LR campaign tags: `pbc_hybrid_ewald` / `pbc_hybrid_ewald_omit_self`. Small-system Monomer ML + MM check for `fixed`/`latent`: below.
`jax_pme`	jax-pme Ewald, PME, or P3M; optional reciprocal r⁻⁶ dispersion in `jax_mic`	yes	yes	Optional `--jax-pme-method ewald\|pme\|p3m`; package availability checked at runtime
`nvalchemiops_pme`	nvalchemiops full-box PME	Not wired; resolves/notes MIC behavior in `jax_mic`	yes	Optional GPU-oriented dependency; use `periodic_external`
`scafacos`	ScaFaCoS full-box Coulomb	Not wired; resolves/notes MIC behavior in `jax_mic`	yes	Requires `libfcs`; method defaults to Ewald

The resolver can fall back when an optional LR implementation is unavailable (for example, requested JAX-PME to another available solver or MIC). Always record both lr_solver_requested and lr_solver_active and treat a fallback as a method change, not an invisible implementation detail.

MD execution drivers¶

`mmml md-system --backend`	Role	Calculator support
`ase`	ASE optimizers/integrators around the hybrid ASE calculator	Hybrid PhysNet/Spooky model paths and lambda TI modes supported by the selected setup
`jaxmd`	JAX-MD integrators and unified JAX execution	Hybrid calculator lowering; NVE/NHC-NVT and supported PBC setups; optional unified `zbl-mbd-multipoles` force field
`pycharmm`	CHARMM minimization/dynamics with MLpot callback	Full hybrid calculator, `jax_mic` or `periodic_external`, CHARMM IMAGE/VDW, external LR solvers
`auto`	Chooses a driver from setup	Record the resolved driver in provenance

Driver support also depends on the selected --setup; not every ensemble is implemented by every driver. For example, JAX-MD provides the supported NPT route, while PyCHARMM has its own staged minimization/heat/equilibration paths.

Review rule for new calculators¶

A calculator is not “supported everywhere” merely because it subclasses ASE Calculator. When adding one, update this matrix and state:

Public factory or CLI name.
Required checkpoint/executable/data assets and their content identity.
Implemented ASE properties and canonical units.
Supported surfaces and drivers.
Charge/spin semantics.
Compatibility with hybrid assembly, MM charge modes, and LR solvers.
Force/energy, serialization, and failure-record tests.

For the canonical scan, also update the CLI choices, calculator factory, provenance manifest, round-trip tests, and failure behavior together.