Calculators

The calculator module provides a unified interface to MLIP and classical backends.

Calculator factory

amorphgen.utils.calculators.get_calculator(model='mace-mpa-0', device='auto', model_path=None, **kwargs)[source]

Build and return an ASE calculator for the given foundation model.

This is the unified entry point for all supported MLFF backends. The returned object is always a standard ASE calculator that can be attached to any ase.Atoms object.

Parameters:

model (str) –
Short name identifying the model. Examples:
- MACE: "mace-mpa-0", "mace-mh-1", "mace-omat-0"
- CHGNet: "chgnet"
- SevenNet: "sevennet", "7net-mf-ompa", "7net-l3i5"
- Classical: "lennard-jones", "buckingham"
Use list_models() or --list-models to see all options. Ignored if model_path is provided (defaults to MACE backend).
device (str) – "cuda" or "cpu".
model_path (str, optional) – Path to a local .model file (e.g. a fine-tuned MACE model). Takes priority over model. Currently only MACE .model files are supported for custom paths.
**kwargs – Extra keyword arguments forwarded to the backend-specific calculator constructor.

Returns:

A ready-to-use ASE calculator.

Return type:

ase.calculators.calculator.Calculator

Raises:

ValueError – If the model name is not recognised by any backend.
ImportError – If the required backend package is not installed.
FileNotFoundError – If model_path points to a non-existent file.

Examples

>>> calc = get_calculator("mace-mpa-0", device="cuda")
>>> calc = get_calculator("chgnet", device="cpu")
>>> calc = get_calculator("7net-mf-ompa", device="cuda")
>>> calc = get_calculator(model_path="/data/my_finetuned.model")
>>> calc = get_calculator("buckingham", classical_params={...})

amorphgen.utils.calculators.list_models()[source]

Print all available foundation models to stdout.

Return type:: None

Backend detection

amorphgen.utils.calculators._detect_backend(model)[source]

Determine which backend a model name belongs to.

Returns one of: “mace”, “chgnet”, “sevennet”, “classical”. Raises ValueError if the model is not recognised.

Parameters:: model (str)
Return type:: str

MACE models

The following MACE foundation models are available via get_calculator():

Key	Variant
`mace-mp-0a-small/medium/large`	MP-0a (initial release)
`mace-mp-0b-small/medium/large`	MP-0b (improved pair repulsion)
`mace-mp-0b2-small/medium/large`	MP-0b2 (high-pressure stability)
`mace-mp-0b3-small/medium/large`	MP-0b3 (fixed phonons)
`mace-mpa-0`	Latest MPA model

SevenNet models

Key	Variant
`sevennet`, `7net-mf-ompa`	Multi-fidelity foundation (OMat+MPtrj+Alexandria) — recommended
`7net-mf-0`	Multi-fidelity baseline
`7net-omat`	OMat-only
`7net-l3i5`	Improved equivariant features
`7net-0`	Original release (Jul 2024)
`7net-omni`	Multi-task

Multi-fidelity (mf) variants accept a modal kwarg ('mpa' default, or 'omat24'):

calc = get_calculator("7net-mf-ompa", device="auto")              # PBE
calc = get_calculator("7net-mf-ompa", device="auto", modal="omat24")  # PBE+U

Use amorphgen --list-models or list_models() for the complete list.

Classical potentials

Built-in pair potentials for initial structure preparation. No extra install needed.

Model name	Potential	Parameters required
`lennard-jones` / `lj`	4eps[(sig/r)^12 - (sig/r)^6]	`epsilon`, `sigma` per pair
`buckingham` / `buck`	A*exp(-r/rho) - C/r^6 + Coulomb	`A`, `rho`, `C` per pair + charges

Parameters are passed via classical_params in YAML config or Python API:

calc = get_calculator("buckingham", classical_params={
    "params": {("Si", "O"): {"A": 18003.76, "rho": 0.2052, "C": 133.54}},
    "charges": {"Si": 2.4, "O": -1.2},
    "cutoff": 10.0,
})

class amorphgen.utils.classical.LennardJonesCalculator(*args, **kwargs)[source]

Bases: Calculator

Lennard-Jones pair potential calculator (vectorized).

V(r) = 4 * epsilon * [(sigma/r)^12 - (sigma/r)^6]

Parameters:

params (dict) – Per-pair LJ parameters, e.g. {(“Ar”, “Ar”): {“epsilon”: 0.0104, “sigma”: 3.40}} Pairs are symmetric: (“A”,”B”) == (“B”,”A”).
cutoff (float) – Cutoff distance in Angstrom.
device (str) – “cpu” (default, vectorized NumPy) or “cuda”/”mps” (PyTorch GPU).

implemented_properties = ['energy', 'forces']

calculate(atoms=None, properties=['energy'], system_changes=ase.calculators.calculator.all_changes)[source]

class amorphgen.utils.classical.BuckinghamCalculator(*args, **kwargs)[source]

Bases: Calculator

Buckingham + Coulomb pair potential calculator (rigid-ion, vectorized).

V(r) = A * exp(-r/rho) - C/r^6 + q_i * q_j / (4*pi*eps0*r)

The Coulomb term uses a Wolf summation for convergence under PBC. This is an approximation to full Ewald – accurate for amorphous structures but not for crystalline long-range order.

Parameters:

params (dict) – Per-pair Buckingham parameters, e.g. {(“Si”, “O”): {“A”: 13702.905, “rho”: 0.193817, “C”: 54.681}}
charges (dict) – Per-element charges in electron units, e.g. {“Si”: 2.4, “O”: -1.2}
cutoff (float) – Cutoff distance in Angstrom.
alpha (float) – Wolf summation damping parameter (1/Angstrom). Default 0.2 works well for cutoff >= 8 A.
coulomb (bool) – If True, include Coulomb interactions. Default True.
device (str) – “cpu” (default, vectorized NumPy) or “cuda”/”mps” (PyTorch GPU).

implemented_properties = ['energy', 'forces']

calculate(atoms=None, properties=['energy'], system_changes=ase.calculators.calculator.all_changes)[source]

Deprecated aliases

amorphgen.utils.calculators.get_mace_calculator(model='mace-mpa-0', device='cuda', model_path=None, **kwargs)[source]

Build and return a MACE calculator.

Deprecated since version 2.0.0: Use get_calculator() instead, which supports MACE and all other backends (CHGNet, SevenNet).

Parameters:

model (str) – MACE model short name (e.g. "mace-mpa-0").
device (str) – "cuda" or "cpu".
model_path (str, optional) – Path to a local .model file.
**kwargs – Forwarded to MACECalculator or mace_mp().

Return type:

ASE calculator