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]

Loads a calculator instance based on the provided name or an existing calculator object. The method supports multiple pre-built universal models and aliases for ease of use. If an existing calculator object is passed instead of a name, it will directly return that calculator instance. Supported FPs include SOTA potentials such as M3GNet, CHGNet, TensorNet, MACE, GRACE, SevenNet, ORB, etc.

This method is designed to provide a universal interface to load various calculator types, which may belong to different domains and packages. It auto-resolves aliases, provides default options for certain calculators, and raises errors for unsupported inputs.

Parameters:

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

  • **kwargs – Model-specific options passed to the underlying loader.

Returns:

ASE calculator instance.

Raises:

ValueError – If name is not a recognized universal model.

class UNIVERSAL_CALCULATORS(value)[source]

Bases: Enum

CHGNet = 'CHGNet'[source]
DeePMD = 'DeePMD'[source]
FAIRChem = 'FAIRChem'[source]
GRACE = 'GRACE'[source]
M3GNet = 'M3GNet'[source]
MACE = 'MACE'[source]
MatterSim = 'MatterSim'[source]
ORB = 'ORB'[source]
PBE = 'PBE'[source]
PETMAD = 'PETMAD'[source]
SevenNet = 'SevenNet'[source]
TensorNet = 'TensorNet'[source]
TensorPotential = 'TensorPotential'[source]
r2SCAN = 'r2SCAN'[source]
to_ase_atoms(structure: Atoms | Structure | Molecule) → Atoms[source]

Converts a given structure into an ASE Atoms object. This function checks if the input structure is already an ASE Atoms object. If not, it converts a pymatgen Structure object to an ASE Atoms object using the AseAtomsAdaptor.

Parameters:

structure – ASE Atoms, pymatgen Structure, or Molecule.

Returns:

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).