Calculator Backends & Capability Matrix

This page summarizes the calculator layer documented for the MAPLE 0.1.4 development branch. It is a development capability guide, not a public release announcement. Use it to choose a backend and to understand the protocol expected from new calculators.

Development note

Backend capability gates are enforced before or during calculator construction: periodic inputs fail fast for molecular wrappers, unsupported Hessian modes are rejected, and typoed backend options fail loudly for shipped calculators.

Backend Capability Matrix

Molecular / HVP

ANI

ani2x ani1x ani1ccx ani1xnr

PBC no Charge no D4 yes HVP gas-phase

PBC: No; periodic atoms fail fast.
Charge / mult: No; values are not honored by the backend.
Hessian: Analytic and numerical (gas phase). Implicit-solvent Hessians are unsupported.
Solvent / D4: Experimental GBSA, energy-only; D4 is supported.
Model files: MAPLE-hosted checkpoints auto-download; explicit model_path is accepted.

Charged molecules

AIMNet2

aimnet2 aimnet2nse

PBC no Charge yes D4 no HVP no

PBC: No; periodic atoms fail fast. coulomb_method=ewald is disabled.
Charge / mult: Yes.
Hessian: Analytic and numerical (gas phase). Implicit-solvent Hessians are unsupported.
Solvent / D4: Experimental GBSA, energy-only; D4 is not supported.
Model files: MAPLE-hosted checkpoints auto-download; explicit model_path is accepted.

Molecular MACE

MACE-OFF / EGRET

maceoff23s maceoff23m maceoff23l egret

PBC no Charge no D4 no HVP no

PBC: No; periodic atoms fail fast.
Charge / mult: No.
Hessian: Analytic and numerical (gas phase). Implicit-solvent Hessians are unsupported.
Solvent / D4: Experimental GBSA, energy-only; D4 is not supported.
Model files: maceoff23m and egret can auto-download; maceoff23s and maceoff23l require a local file or model_path.

MACE-OMol

maceomol

PBC no Charge no D4 no HVP no

PBC: No; periodic atoms fail fast.
Charge / mult: No.
Hessian: Analytic and numerical (gas phase). Implicit-solvent Hessians are unsupported.
Solvent / D4: Experimental GBSA, energy-only; D4 is not supported.
Model files: Requires a local checkpoint in the model directory or explicit model_path.

Development backend

MACE-Polar

macepols macepolm macepoll

PBC no Charge yes D4 no HVP no

PBC: No; periodic atoms fail fast. No external-field interface is exposed.
Charge / mult: Yes; multiplicity is converted to unpaired-electron spin as mult - 1.
Hessian: Analytic and numerical (gas phase). Implicit-solvent Hessians are unsupported.
Solvent / D4: Experimental GBSA, energy-only; D4 is not supported.
Model files: Requires a local checkpoint in the model directory or explicit model_path.

Periodic / FAIR-Chem

UMA

uma

PBC yes Charge omol D4 no HVP no

PBC: Yes through FAIR-Chem. Non-periodic input uses omol; periodic input must specify a non-omol task. Stress / virial requests are rejected until validated.
Charge / mult: omol only; non-omol tasks reject non-default charge / multiplicity. FAIR-Chem receives spin multiplicity as mult.
Hessian: Numerical only (gas phase). Implicit-solvent Hessians are unsupported.
Solvent / D4: Experimental GBSA, energy-only; D4 is not supported.
Model files: Resolved from checkpoint_path, a local maple/function/calculator/model/uma-*.pt file, or FAIR-Chem's official loading path.

Selection Rules

Periodic materials or catalysis: use uma and set an explicit FAIR-Chem task such as omat, oc20, oc22, oc25, omc, or odac. Do not request stress or virial output yet.
Charged or open-shell molecules: use aimnet2 for molecular systems, or uma with the omol task. Treat charged/open-shell UMA chemistry as a result to verify against references.
D4 dispersion: use ANI. Other shipped backends reject or ignore D4 because it is not part of their MAPLE calculator contract.
HVP-enabled Dimer: ANI is the only shipped backend with get_hvp(), and it is gas-phase only. If a selected backend lacks HVP support, use a different transition-state method or a future finite-difference Dimer path once validated.
Implicit-solvent Hessians: GBSA Hessians (analytic or numerical) are not supported; Hessians are available only in gas phase.

Developer Backend Contract

MAPLE calculators are registered classes that satisfy a small ASE-style protocol. A backend does not have to inherit the shared base class as long as it exposes the same public surface and class attributes.

Authoring source of truth

This page is a website summary. The full developer checklist and runnable template live in the MAPLE source tree at maple/function/calculator/AUTHORING.md.

Registration is required

A custom calculator is not selectable by #model=... until its class is registered. Define lowercase MODEL_NAMES keys and decorate the class with @register_calculator; plugin loading only imports the module so this registration code can run.

from maple.function.calculator import CalcABC, register_calculator

@register_calculator
class MyCalculator(CalcABC):
    MODEL_NAMES = ("mymodel",)
    MODEL_ENERGY_UNIT = "eV"
    SUPPORTED_HESSIAN_MODES = ("numerical",)
    SUPPORTS_CHARGE_MULT = False
    SUPPORTS_PBC = False
    CHECKPOINT_FILENAME = None
    REQUIRES_LOCAL_MODEL_FILE = True
    OPTION_KEYS = ()
    MODEL_PATH_OPTION = "model_path"

Surface	Contract
`calculate(atoms, properties, system_changes)`	ASE entry point. Store energy, free energy, forces, and optional Hessian in `results` through the shared finalization path where possible.
`get_hessian(atoms, delta=0.002)`	Returns a `(3N, 3N)` array in Hartree / Å². Numerical mode uses the shared finite-difference helper; analytic mode is backend-specific.
`get_hvp(atoms, n)`	Optional. Implement only for the HVP-enabled Dimer path and return `(Hn, forces, energy)` in Hartree units. The default raises `NotImplementedError`.
`MODEL_NAMES`	Lowercase registry keys. Duplicate registration is a real error and raises instead of overwriting.
`MODEL_ENERGY_UNIT`	Declare `eV` or `hartree` honestly. `_finalize_results` performs the energy/force conversion; custom calculators should not multiply by `EV2HARTREE` in the calculate path.
`SUPPORTED_HESSIAN_MODES`	Subset of `analytic` and `numerical`. Unsupported requested modes fail before production work begins.
`SUPPORTS_CHARGE_MULT` / `SUPPORTS_PBC`	Declare whether the backend honors charge / multiplicity and validated periodic inputs. Do not mark PBC true unless the backend builds a validated periodic graph or neighbor list.
`CHECKPOINT_FILENAME` / `REQUIRES_LOCAL_MODEL_FILE`	Tell the factory whether MAPLE can auto-download a checkpoint or must require a local file.
`OPTION_KEYS` / `MODEL_PATH_OPTION`	Reject misspelled backend options loudly, and route explicit user model paths to the constructor kwarg that actually consumes them.

Plugin Discovery and Model Paths

Input header: #model=mymodel(module=my_lab.maple_plugin, model_path=/tmp/m.pt) imports the plugin module, which must register a calculator class for mymodel, then passes the explicit model path through the backend contract.
Environment variable: MAPLE_CALCULATOR_PLUGINS=my_lab.maple_plugin,other.plugin imports plugin modules once per process before calculator construction; each module must run its own @register_calculator registrations.
Python entry points: [project.entry-points."maple.calculators"] is documented as a preview shape for future packagers, not a current discovery layer.

Energy API Migration

The old backend-specific calc.get_energy(...) entry points are not part of the public calculator API. Downstream code should use ASE's standard pattern:

atoms.calc = calc
energy = atoms.get_potential_energy()

This keeps energy access consistent across backends whose legacy get_energy signatures did not agree.