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.

Variables:

  • potential – The potential model used for PES calculations.

  • stress_weight – The stress weight factor to convert between units.

Initialize PESCalculator with a potential from maml.

Parameters:

  • potential (LMPStaticCalculator) – maml.apps.pes._lammps.LMPStaticCalculator

  • stress_unit (str) – The unit of stress. Default to “GPa”

  • stress_weight (float) – The conversion factor from GPa to eV/A^3, if it is set to 1.0, the unit is in GPa. Default to 1.0.

  • **kwargs – Additional keyword arguments passed to super().__init__().

_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 (ase.Atoms) – ase Atoms object

  • properties (list) – The list of properties to calculate

  • system_changes (list) – monitor which properties of atoms were changed for new calculation. If not, the previous calculation results will be loaded.

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 – The basis set used for initializing the ACE calculator. This can be provided as a string, Path object, ACEBBasisSet, ACECTildeBasisSet, or BBasisConfiguration.

  • kwargs – Additional configuration parameters to customize the ACE calculator. These keyword arguments are passed directly to the PyACECalculator instance during initialization.

Returns:

An instance of the Calculator class representing the initialized ACE 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 – Path to the trained DeepMD model file, provided as a string or a Path object.

  • kwargs – Additional options and configurations to pass into the DeepMD Calculator during initialization.

Returns:

An instance of the Calculator object initialized with the specified DeepMD model and optional configurations.

Return type:

Calculator

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 (str | Path) – Path to the configuration file for the GAP model.

  • kwargs (Any) – Additional keyword arguments for configuring the calculator.

Returns:

An instance of PESCalculator initialized with the GAPotential model.

Return type:

Calculator

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 (str | Path) – The path to the MATGL model file or directory.

  • kwargs – Additional keyword arguments used to configure the calculator.

Returns:

An instance of the PESCalculator initialized with the loaded MATGL model and configured with the given parameters.

Return type:

Calculator

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 (str | Path) – Path to the configuration file for the MTPotential.

  • elements (list) – List of element symbols used in the model. Each element should be a string representing a chemical element (e.g., “H”, “O”).

  • kwargs (Any) – Additional keyword arguments to configure the PESCalculator.

Returns:

A calculator object wrapping the MTPotential.

Return type:

Calculator

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 (str | Path) – The file path to the serialized NequIP model.

  • kwargs (Any) – Additional keyword arguments to be passed to the NequIPCalculator.from_deployed_model method.

Returns:

A Calculator instance initialized with the given model and parameters, suitable for ASE simulations.

Return type:

Calculator

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 (str | Path) – Path to the primary input file containing NNP configuration.

  • scaling_filename (str | Path) – Path to the scaling parameters file required for the NNP.

  • weights_filenames (list) – List of paths to weight files for the NNP.

  • kwargs (Any) – Additional keyword arguments passed to the Calculator constructor.

Returns:

A Calculator object initialized with the loaded NNP settings.

Return type:

Calculator

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 – Path to the parameter file required for SNAPotential configuration.

  • coeff_file – Path to the coefficient file required for SNAPotential configuration.

  • kwargs – Additional keyword arguments passed to the PESCalculator.

Returns:

A PESCalculator instance configured with the SNAPotential model.

Return type:

Calculator

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 – The name of the calculator to load or an instance of a Calculator.

  • kwargs – Keyword arguments that are passed to the internal calculator initialization routines for models matching the specified name. These options are calculator dependent.

Returns:

An instance of the loaded calculator.

Raises:

ValueError – If the name provided does not match any recognized calculator type.

get_ase_optimizer(optimizer: str | Optimizer) → Optimizer[source]

Retrieve an ASE optimizer instance based on the provided input. This function accepts either a string representing the name of a valid ASE optimizer or an instance/subclass of the Optimizer class. If a string is provided, it checks the validity of the optimizer name, and if valid, retrieves the corresponding optimizer from ASE. An error is raised if the optimizer name is invalid.

If an Optimizer subclass or instance is provided as input, it is returned directly.

Parameters:

optimizer (str | Optimizer) – The optimizer to be retrieved. Can be a string representing a valid ASE optimizer name or an instance/subclass of the Optimizer class.

Returns:

The corresponding ASE optimizer instance or the input Optimizer instance/subclass.

Return type:

Optimizer

Raises:

ValueError – If the optimizer name provided as a string is not among the valid ASE optimizer names defined by VALID_OPTIMIZERS.

is_ase_optimizer(key: str | Optimizer) → bool[source]

Determines whether the given key is an ASE optimizer. A key can either be a string representing the name of an optimizer class within ase.optimize or directly be an optimizer class that subclasses Optimizer.

If the key is a string, the function checks whether it corresponds to a class in ase.optimize that is a subclass of Optimizer.

Parameters:

key – The key to check, either a string name of an ASE optimizer class or a class object that potentially subclasses Optimizer.

Returns:

True if the key is either a string corresponding to an ASE optimizer subclass name in ase.optimize or a class that is a subclass of Optimizer. Otherwise, returns False.