ASE front end¶

calculator ¶

FastMACECalculator and fm.calc: the ASE calculator, compiled tier (SPEC §7.4, §7.7 level 0).

ASE calls a calculator once per step, so this front end gets the compiled tier at most (§8.2): a compiled model, exact edge counts, no CUDA graphs. Full speed needs FastMACE to own the MD loop (fm.md, the fastmace.ase integrators). The calculator builds nothing itself: at the first calculation, and again whenever the species or the atom count change, it makes a one-off evaluation plan through the minimal planner (MinimalPlanner.plan_evaluation: compiled, with stress, no workload) and gets that plan's MACEForceField from build_evaluation. Each plan's superset is its structure's species (owner decision D3), so new species get a fresh plan; the plans share one compiled-model cache. Evaluation plans compile with a dynamic edge dimension (EngineConfig.dynamic_edges, 2-T13), so relaxations, phonopy and NEB, whose edge counts change between calls, pay one compile.

FastMACECalculator ¶

Bases: Calculator

FastMACECalculator(model, *, head=None, rewrites="auto", precision="float32", dispersion=None): energy, free_energy, forces and Voigt stress in ASE units; full 3D PBC only (§7.6).

model: an fm.load result or a label of the model table (a checkpoint path or URL needs fm.load or fm.calc with sha256=/trusted=, since the trust decision needs one); head selects a head of a label's checkpoint, and must match a loaded model's head;
rewrites: "auto" or a RewriteConfig; precision: the force precision, "float32" or "float64". Energies are accumulated in float64 (§7.3);
dispersion: None, "d3bj" or an fm.D3, as fm.ForceField takes it (MACE plus D3, SPEC §11.2; 3b-T04). dispersion is then the complete record. With D3 there are no per-atom energies (D3's energy is not split by atom here).

energies (per atom) is listed only for models whose energy terms are all atom-resolved; PolarMACE's k-space electrostatics are not (§7.3). Non-periodic or mixed-PBC atoms raise PlanRefused (rule 1); gas-phase molecules need MACE's MACECalculator (§4.3).

plan is the current evaluation plan (None before the first calculation) and notes what the calculator recorded, the compatibility-tier note first; the note is printed once.

calc ¶

calc(
    model: Any, *, head: str | None = None, **options: Any
) -> FastMACECalculator

atoms.calc = fm.calc("mh1", head="matpes_r2scan"): a FastMACECalculator for model (label, path or URL, loaded as fm.load does); prints the compatibility-tier note once.

options: fm.load's sha256, trusted, download, charge and spin_multiplicity, and the calculator's rewrites, precision and dispersion.

md ¶

ASE MD scripts on the graph engine: fastmace.ase.Langevin, LangevinBAOAB and the phase 4 classes (SPEC §7.7 level 1).

An ASE script is ported by changing the import and adding model=. Each class takes the argument names and units of its ASE 3.27 class (SUPPORTED) and refuses the rest with the reason (REFUSED); any other argument is a TypeError naming it. The FastMACE additions are keyword-only (ADDITIONS). The shim never reinterprets an ASE argument: friction, the pressures and the time constants are in ASE units, and the conversion to the public integrator record is the only arithmetic (the record's to_config converts back, so a value may differ by one ulp).

The centre of mass (owner decision D2, conductor's answer to 4-T10): a class whose ASE original takes fixcm (Langevin, NVTBerendsen, NPTBerendsen) passes it through and follows decision 37, as fastmace.ase.Langevin does (LangevinBAOAB keeps its phase 1b mapping). A class whose ASE original has no fixcm (VelocityVerlet, Bussi, NoseHooverChainNVT, IsotropicMTKNPT, MTKNPT) removes no centre of mass, as ASE, and counts ASE's degrees of freedom: its keyword-only dof defaults to "ase"; dof="auto" (or "fastmace") is FastMACE's convention instead, the total momentum removed and 3N - 3 counted (fixcm="auto": with FixAtoms no momentum is removed and 3(N - n_fixed) counted, 4-T04). FixAtoms runs where owner decision 44 allows it (NVE, CSVR, NVT Berendsen, Langevin; with fixcm=False for the classes that take ASE's fixcm, whose default True is refused with it); rule 1 refuses it elsewhere at the first run, with the reason.

Nothing here builds an engine: the classes build a fm.Simulation at the first run or step, which plans, runs the optional gate (owner decision D1: check="gate") and builds through the minimal planner (SPEC §5). The setup report is printed then.

run(n) advances the Simulation in chunks that end where an observer is due (ASE's attach rule: every interval steps from step 0, or once at step |interval| for interval <= 0). Before the observers of a step the committed state is written into atoms with a single-point results cache as atoms.calc; after them, changed positions or momenta changed species, masses, initial charges, positions or momenta become one event through Simulation.update (SPEC §8.5; species in the superset), and any other change raises PlanRefused with its reason. The shortest observer interval is the workload's host_callbacks_every (rule 9). trajectory= and logfile= keep their ASE meaning (one ASE Trajectory, ASE's MDLogger format) and are written from the Simulation's asynchronous snapshots; every other file goes to output.

Langevin ¶

Bases: _Dynamics

ASE 3.27's ase.md.langevin.Langevin on FastMACE's graph engine (Langevin, SPEC §10.2).

Langevin(atoms, timestep, temperature=None, friction=None, fixcm=True, *, temperature_K=None, trajectory=None, logfile=None, loginterval=1, append_trajectory=False, model=None, force_field=None, head=None, seed=None, output=None, check="skip", dispersion=None, fixcm_projection="auto"): ASE's arguments and units (timestep and 1/friction in ASE time units, temperature in eV, deprecated as in ASE); rng, a non-default comm/communicator and master are refused. The additions are those of fm.md, and fixcm_projection (fm.integrators.Langevin's; decision 37). With fixcm, "auto" resolves to the mass-weighted projection: the log then reads its frames with ASE's FixCom, so its temperature counts 3N - 3 (the trajectory frames stay unconstrained). fixcm_projection="ase" is ASE's Langevin exactly (its noise stream, 3N). FixAtoms runs with fixcm=False (ASE's default fixcm=True is refused with it, owner decision 44); the log and the trajectory frames carry the constraint, so temperatures count 3(N - n_fixed).

LangevinBAOAB ¶

Bases: _Dynamics

ASE 3.27's ase.md.langevinbaoab.LangevinBAOAB on FastMACE's graph engine (BAOAB NPT, §10.2).

LangevinBAOAB(atoms, timestep, *, temperature_K, externalstress, hydrostatic=False, T_tau=None, P_tau=None, P_mass=None, P_mass_factor=1.0, disable_cell_langevin=False, trajectory=None, logfile=None, loginterval=1, append_trajectory=False, model=None, ...), ASE units throughout: externalstress in eV/Å³ (a scalar, 3 diagonal, 6 Voigt components or a symmetric 3×3), T_tau and P_tau in ASE time. Mapped to fm.integrators.LangevinBAOAB with friction_per_fs = fs / T_tau and cell_mode = "hydrostatic" if hydrostatic else "full".

Refused: no externalstress (fixed-cell BAOAB: use Langevin), no temperature_K (NVE/NPH, phase 4), an explicit P_mass (P_mass_factor scales ASE's heuristic), rng, a non-default comm/communicator and master.

VelocityVerlet ¶

Bases: _Dynamics

ASE 3.27's ase.md.verlet.VelocityVerlet on FastMACE's graph engine (NVE, SPEC §10.2).

VelocityVerlet(atoms, timestep, trajectory=None, logfile=None, loginterval=1, *, append_trajectory=False, model=None, ..., dof="ase"): timestep in ASE time units, the momenta the structure's. Mapped to fm.integrators.NVE; dof as the module docstring says. The workload's max_temperature_K is fm.md's for NVE (quick.nve_max_temperature_K).

Bussi ¶

Bases: _Dynamics

ASE 3.27's ase.md.bussi.Bussi on FastMACE's graph engine (CSVR, SPEC §10.2).

Bussi(atoms, timestep, temperature_K, taut, *, trajectory=None, ..., seed=None, dof="ase"): timestep and taut in ASE time units. Mapped to fm.integrators.CSVR with tau_fs = taut / fs; the noise is ASE's stream from seed (conductor's choice 3), so rng is refused. A zero initial kinetic energy raises ValueError, as ASE's Bussi.

NoseHooverChainNVT ¶

Bases: _Dynamics

ASE 3.27's ase.md.nose_hoover_chain.NoseHooverChainNVT on FastMACE's graph engine (NHC, §10.2).

NoseHooverChainNVT(atoms, timestep, temperature_K, tdamp, tchain=3, tloop=1, *, trajectory=None, logfile=None, loginterval=1, append_trajectory=False, model=None, ..., dof="ase"): timestep and tdamp in ASE time units. Mapped to fm.integrators.NoseHooverChain with tdamp_fs = tdamp / fs; dof as the module docstring says. comm other than ASE's default and master are refused.

IsotropicMTKNPT ¶

Bases: _MTKDynamics

ASE 3.27's ase.md.nose_hoover_chain.IsotropicMTKNPT on FastMACE's graph engine (MTK, hydrostatic).

IsotropicMTKNPT(atoms, timestep, temperature_K, pressure_au, tdamp, pdamp, tchain=3, pchain=3, tloop=1, ploop=1, *, trajectory=None, ..., dof="ase"): pressure_au in eV/Å³, timestep, tdamp and pdamp in ASE time units. Mapped to fm.integrators.MTK(cell_mode="hydrostatic") with pressure_GPa = pressure_au / GPa. Experimental: not yet qualified, as BAOAB (§10.2).

MTKNPT ¶

Bases: _MTKDynamics

ASE 3.27's ase.md.nose_hoover_chain.MTKNPT on FastMACE's graph engine (MTK, full cell).

Arguments as IsotropicMTKNPT; mapped to fm.integrators.MTK(cell_mode="full"). Experimental: not yet qualified, as BAOAB (§10.2).

NVTBerendsen ¶

Bases: _Dynamics

ASE 3.27's ase.md.nvtberendsen.NVTBerendsen on FastMACE's graph engine (Berendsen, SPEC §10.2).

NVTBerendsen(atoms, timestep, temperature=None, taut=None, fixcm=True, *, temperature_K=None, trajectory=None, ...): temperature in K (an alias of temperature_K, as ASE's), timestep and taut in ASE time units. Mapped to fm.integrators.Berendsen without a pressure; fixcm follows decision 37 (module docstring). Non-canonical: equilibration only.

NPTBerendsen ¶

Bases: _Dynamics

ASE 3.27's ase.md.nptberendsen.NPTBerendsen on FastMACE's graph engine (Berendsen NPT, §10.2).

NPTBerendsen(atoms, timestep, temperature=None, *, temperature_K=None, pressure=None, pressure_au=None, taut=0.5 ps, taup=1 ps, compressibility=None, compressibility_au=None, fixcm=True, trajectory=None, ...): ASE's arguments, units and defaults (taut and taup default to ASE's 500 fs and 1000 fs, so a ported script keeps them). Exactly one of pressure (bar, deprecated as in ASE) and pressure_au (eV/Å³); compressibility (1/bar, deprecated) or compressibility_au (Å³/eV). Mapped to fm.integrators.Berendsen with pressure_GPa = pressure_au / GPa and compressibility_per_GPa = compressibility_au * GPa; fixcm follows decision 37. Non-canonical: equilibration only; the barostat is experimental: not yet qualified.

Inhomogeneous_NPTBerendsen ¶

Bases: NPTBerendsen

ASE 3.27's ase.md.nptberendsen.Inhomogeneous_NPTBerendsen on FastMACE's graph engine.

Inhomogeneous_NPTBerendsen(*args, mask=(1, 1, 1), **kwargs): NPTBerendsen's arguments and mask, the three 0/1 flags of the scaled cell directions. Mapped to fm.integrators.Berendsen with mask (cell_mode="full": each cell vector scaled on its own, the angles kept).

optimize ¶

ASE relaxation scripts on the graph engine: fastmace.ase.LBFGS and FIRE (SPEC §7.7; decision 48).

An ASE script is ported by changing the import and adding model=. Each class takes the argument names, units and defaults of its ASE 3.27 class (SUPPORTED) and refuses the rest with the reason (REFUSED): restart other than None (a relaxation writes no restart files, conductor's choice 5), LBFGS's use_line_search=True, FIRE's deprecated maxmove and position_reset_callback, and a non-default comm/master. The FastMACE additions are keyword-only (ADDITIONS).

atoms is an Atoms (fixed cell) or ase.filters.FrechetCellFilter(atoms, ...) (variable cell, read into fm.optimize.FrechetCell); every other filter (UnitCellFilter, ExpCellFilter, StrainFilter, ...) is refused with the reason (decision 48).

Nothing here builds an engine: the classes build a fm.Simulation(optimizer=...) at the first run, irun or step, and run(fmax, steps) is Simulation.relax in chunks that end where an observer or a trajectory frame is due (ASE's attach rule). logfile is ASE's optimiser log (ASE's Log, "-" by default as ASE's), one line per step from the relaxation's per-step energies and max forces; trajectory= is one ASE Trajectory with a frame every loginterval steps. Before the observers of a step the relaxed state is written into atoms (positions and cell) with a single-point results cache as atoms.calc. An observer that changes atoms raises: the optimiser's history would no longer describe the structure (conductor's answer to 4-T10).

LBFGS ¶

Bases: _Optimizer

ASE 3.27's ase.optimize.LBFGS on FastMACE's graph engine (fm.optimize.LBFGS, SPEC §10.3).

LBFGS(atoms, restart=None, logfile="-", trajectory=None, maxstep=None, memory=100, damping=1.0, alpha=70.0, use_line_search=False, *, append_trajectory=False, loginterval=1, model=None, force_field=None, head=None, check="skip", dispersion=None): maxstep in Å (None is ASE's 0.2), alpha in eV/Å² as ASE's. atoms an Atoms or a FrechetCellFilter.

FIRE ¶

Bases: _Optimizer

ASE 3.27's ase.optimize.FIRE on FastMACE's graph engine (fm.optimize.FIRE, SPEC §10.3).

FIRE(atoms, restart=None, logfile="-", trajectory=None, dt=0.1, maxstep=None, maxmove=None, dtmax=1.0, Nmin=5, finc=1.1, fdec=0.5, astart=0.1, fa=0.99, a=0.1, downhill_check=False, position_reset_callback=None, *, append_trajectory=False, loginterval=1, model=None, ...): ASE's arguments and defaults (dt and dtmax in ASE time units, maxstep in Å, None is ASE's 0.2). Refused: the deprecated maxmove (use maxstep) and position_reset_callback (decision 48).