Local-Source ASE Calculators

The local-source ASE calculators are implemented in mace_scf/calculators/localsources.py.

These calculators wrap one-shot local-source models. They predict source coefficients and evaluate electrostatics once; there is no SCF loop.

Classes

  • MACELocalCharges

  • MACELocalSplitCharges

  • MACEFixedChargeBaseline

Minimal Example

from ase.io import read
from mace_scf.calculators.localsources import MACELocalCharges

atoms = read("input.xyz")

calc = MACELocalCharges(
    model_path="nonpol.model",
    device="cuda",
    pbc_handling="slab",
)

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

Model-Specific Examples

MACELocalSplitCharges can read per-atom formal charges when the model was trained to use them:

from mace_scf.calculators.localsources import MACELocalSplitCharges

calc = MACELocalSplitCharges(
    model_path="local_symmetric_charges.model",
    device="cuda",
    formal_charges_key="formal_oxidation_states", # not needed if you trained with per-species formal charges
    external_field_key="homogeneous_field",
    pbc_handling="slab",
)

MACEFixedChargeBaseline uses the fixed-charge information stored in the trained model:

from mace_scf.calculators.localsources import MACEFixedChargeBaseline

calc = MACEFixedChargeBaseline(
    model_path="fixed_charge_baseline.model",
    device="cuda",
    pbc_handling="pbc",
)

Boundary Handling

pbc_handling selects the electrostatic boundary treatment used by the calculator:

  • realspace

  • pbc

  • slab

  • molecule_in_box

  • mixed_periodic

See boundary conditions for the meaning of these modes, including the distinction between realspace and molecule_in_box.

The calculator setting can differ from the value used during training. This is sometimes useful for testing, but it changes the electrostatic semantics of the calculation. For production use, choose a calculator pbc_handling value that matches the boundary treatment intended during training.

Common choices:

# Bulk periodic system
calc = MACELocalCharges(
    model_path="nonpol.model",
    device="cuda",
    pbc_handling="pbc",
)

# Slab system
calc = MACELocalSplitCharges(
    model_path="local_symmetric_charges.model",
    device="cuda",
    pbc_handling="slab",
)

# Non-periodic molecule or cluster, open-boundary electrostatics
calc = MACELocalCharges(
    model_path="nonpol.model",
    device="cuda",
    pbc_handling="realspace",
)

# Molecule or cluster treated in a periodic box with correction
calc = MACELocalCharges(
    model_path="nonpol.model",
    device="cuda",
    pbc_handling="molecule_in_box",
)

# Mixed dataset containing multiple boundary-condition classes
calc = MACELocalSplitCharges(
    model_path="local_symmetric_charges.model",
    device="cuda",
    pbc_handling="mixed_periodic",
)

Results

After calculation, calc.results includes:

  • energy

  • free_energy

  • forces

  • stress

  • partial_charges

  • partial_dipoles

  • density_coefficients

  • dipole

  • external_field

  • fermi_level

  • optional polarizability

density_coefficients follow the atomic multipole ordering described in atomic multipoles. partial_dipoles are Cartesian. external_field is the value loaded into the model input batch.

Torch Compilation