matcalc.utils module

Some utility methods, e.g., for getting calculators from well-known sources.

class PESCalculator(potential: LMPStaticCalculator, stress_unit: Literal['eV/A3', 'GPa'] = 'GPa', stress_weight: float = 1.0, **kwargs: Any)[source]

Bases: Calculator

Class for simulating and calculating potential energy surfaces (PES) using various machine learning and classical potentials. It extends the ASE Calculator API, allowing integration with the ASE framework for molecular dynamics and structure optimization.

PESCalculator provides methods to perform energy, force, and stress calculations using potentials such as MTP, GAP, NNP, SNAP, ACE, NequIP, DeePMD and MatGL (M3GNet, TensorNet, CHGNet). The class includes utilities to load compatible models for each potential type, making it a versatile tool for materials modeling and molecular simulations.

potential[source]

MAML LAMMPS static potential backend.

stress_weight[source]

Factor applied to stress (includes unit conversion).

Initialize PESCalculator with a potential from maml.

Parameters:

  • potential – MAML LMPStaticCalculator instance.

  • stress_unit – "GPa" or "eV/A3" for returned stress units.

  • stress_weight – Multiplier on stress after unit conversion (default 1.0).

  • **kwargs – Forwarded to ase.calculators.calculator.Calculator.

_abc_impl = <_abc._abc_data object>[source]
calculate(atoms: Atoms | None = None, properties: list | None = None, system_changes: list | None = None) → None[source]

Perform calculation for an input Atoms.

Parameters:

  • atoms – Structure to evaluate.

  • properties – ASE property list to compute (defaults to all).

  • system_changes – ASE change list; if unchanged, cached results may be reused.

implemented_properties: list[str] = ['energy', 'forces', 'stress'][source]

Properties calculator can handle (energy, forces, …)

static load_ace(basis_set: str | Path | ACEBBasisSet | ACECTildeBasisSet | BBasisConfiguration, **kwargs: Any) → Calculator[source]

Load an ACE (Atomic Cluster Expansion) calculator using the specified basis set.

This method utilizes the PyACE library to create and initialize a PyACECalculator instance with a given basis set. The provided basis set can take various forms including file paths, basis set objects, or configurations. Additional customization options can be passed through keyword arguments.

Parameters:

  • basis_set – ACE basis (path, or PyACE basis / configuration object).

  • **kwargs – Forwarded to PyACECalculator.

Returns:

Initialized PyACE ASE calculator.

static load_deepmd(model_path: str | Path, **kwargs: Any) → Calculator[source]

Loads a Deep Potential Molecular Dynamics (DeePMD) model and returns a Calculator object for molecular dynamics simulations.

This method imports the deepmd.calculator.DP class and initializes it with the given model path and optional keyword arguments. The resulting Calculator object is used to perform molecular simulations based on the specified DeePMD model.

The function requires the DeePMD-kit library to be installed to properly import and utilize the DP class.

Parameters:

  • model_path – Trained DeePMD model path.

  • **kwargs – Forwarded to DeePMD DP.

Returns:

DeePMD ASE calculator instance.

static load_gap(filename: str | Path, **kwargs: Any) → Calculator[source]

Loads a Gaussian Approximation Potential (GAP) model from the given file and returns a corresponding Calculator instance. GAP is a machine learning-based potential used for atomistic simulations and requires a specific config file as input. Any additional arguments for the calculator can be passed via kwargs, allowing customization.

Parameters:

  • filename – GAP configuration file path.

  • **kwargs – Forwarded to PESCalculator.

Returns:

PESCalculator wrapping the GAP model.

static load_matgl(path: str | Path, **kwargs: Any) → Calculator[source]

Loads a MATGL model from the specified path and initializes a PESCalculator with the loaded model and additional optional parameters.

This method uses the MATGL library to load a model from the given file path or directory. It then configures a calculator using the loaded model and the provided keyword arguments.

Parameters:

  • path – Path to the MatGL model file or pretrained model name.

  • **kwargs – Forwarded to the MatGL ASE calculator.

Returns:

Configured ASE calculator for the MatGL model.

static load_mtp(filename: str | Path, elements: list, **kwargs: Any) → Calculator[source]

Load a machine-learned potential (MTPotential) from a configuration file and create a calculator object to interface with it.

This method initializes an instance of MTPotential using a provided configuration file and elements. It returns a PESCalculator instance, which wraps the initialized potential model.

Parameters:

  • filename – MTP configuration file path.

  • elements – Element symbols for the potential (e.g. ["Cu"]).

  • **kwargs – Forwarded to PESCalculator.

Returns:

PESCalculator wrapping the MTP model.

static load_nequip(model_path: str | Path, **kwargs: Any) → Calculator[source]

Loads and returns a NequIP Calculator instance from the specified model path. This method facilitates the integration of machine learning models into ASE by loading a model for atomic-scale simulations.

Parameters:

  • model_path – Path to the deployed NequIP model.

  • **kwargs – Forwarded to NequIPCalculator.from_deployed_model.

Returns:

NequIP ASE calculator instance.

static load_nnp(input_filename: str | Path, scaling_filename: str | Path, weights_filenames: list, **kwargs: Any) → Calculator[source]

Loads a neural network potential (NNP) from specified configuration files and creates a Calculator object configured with the potential. This function allows for customizable keyword arguments to modify the behavior of the resulting Calculator.

Parameters:

  • input_filename – NNP input configuration path.

  • scaling_filename – NNP scaling parameters path.

  • weights_filenames – Paths to NNP weight files.

  • **kwargs – Forwarded to PESCalculator.

Returns:

PESCalculator wrapping the NNP model.

static load_snap(param_file: str | Path, coeff_file: str | Path, **kwargs: Any) → Calculator[source]

Load a SNAP (Spectral Neighbor Analysis Potential) configuration and create a corresponding Calculator instance.

This static method initializes a SNAPotential instance using the provided configuration files and subsequently generates a PESCalculator based on the created potential model and additional keyword arguments.

Parameters:

  • param_file – SNAP parameter file path.

  • coeff_file – SNAP coefficient file path.

  • **kwargs – Forwarded to PESCalculator.

Returns:

PESCalculator wrapping the SNAP model.

static load_universal(name: str | Calculator, **kwargs: Any) → Calculator[source]

Load a foundation potential calculator by its canonical name.

Names follow the unified convention <Architecture>-<Dataset>-<Optional Version> (e.g. TensorNet-MatPES-PBE-2025.2, MACE-MPA-0-medium). The full list of canonical names is the keys of MODEL_REGISTRY; short / legacy spellings in MODEL_ALIASES resolve to a canonical name. Lookups are case-insensitive.

If name is already a Calculator, it is returned unchanged.

Parameters:

  • name – Canonical model name, alias, or an existing ASE calculator instance.

  • **kwargs – Provider-specific options. These override the defaults stored in the registry entry (e.g. device="cuda" for ORB / FAIRChem).

Returns:

An ASE Calculator instance.

Raises:

  • ValueError – If name is not a recognized model.

  • ImportError – If the model is recognized but the provider’s optional dependency is not installed.

class UNIVERSAL_CALCULATORS(value)[source]

Bases: Enum

_install_hint(provider: str) → str[source]

Return a human-friendly install hint for a missing provider dependency.

_load_deepmd(kwargs: dict[str, Any]) → Calculator[source]
_load_fairchem(kwargs: dict[str, Any]) → Calculator[source]
_load_grace(kwargs: dict[str, Any]) → Calculator[source]
_load_mace_mp(kwargs: dict[str, Any]) → Calculator[source]
_load_matgl(kwargs: dict[str, Any]) → Calculator[source]
_load_mattersim(kwargs: dict[str, Any]) → Calculator[source]
_load_orb(kwargs: dict[str, Any]) → Calculator[source]
_load_petmad(kwargs: dict[str, Any]) → Calculator[source]
_load_sevennet(kwargs: dict[str, Any]) → Calculator[source]
_resolve_canonical(name: str) → str | None[source]

Resolve name (alias, canonical, or case-variant) to a canonical model name.

Returns None if the name cannot be resolved.

_suggest_models(name: str, n: int = 3) → list[str][source]

Return the closest candidate model names for an unrecognised input.

to_ase_atoms(structure: Atoms | Structure | Molecule) → Atoms[source]

Converts a given structure into an ASE Atoms object. If the input is already an Atoms, a shallow copy is returned so that downstream code (which routinely attaches a calculator and runs optimizers in-place) cannot mutate a caller-owned object — important for parallel calc_many execution where joblib workers must not share state.

Parameters:

structure – ASE Atoms, pymatgen Structure, or Molecule.

Returns:

Fresh ASE Atoms for the same system.

to_pmg_molecule(structure: Atoms | Structure | Molecule | IMolecule) → IMolecule[source]

Converts a given structure of type Atoms or Structure into a Molecule object. If the input structure is already of type Molecule, it is returned unchanged. If the input structure is of type Atoms, it is converted to a Molecule using the AseAtomsAdaptor.

Parameters:

structure – ASE Atoms, pymatgen Structure / Molecule, or interface molecule type.

Returns:

Pymatgen Molecule representation.

to_pmg_structure(structure: Atoms | Structure) → Structure[source]

Converts a given structure of type Atoms or Structure into a Structure object. If the input structure is already of type Structure, it is returned unchanged. If the input structure is of type Atoms, it is converted to a Structure using the AseAtomsAdaptor.

Parameters:

structure – ASE Atoms or pymatgen Structure.

Returns:

Pymatgen Structure (unchanged if already a structure).