ipsuite.models package

Submodules

ipsuite.models.base module

Base class for all MLModel Implementations.

class ipsuite.models.base.MLModel(*args, **kwargs)

Bases: AnalyseAtoms

Parent class for all MLModel Implementations.

get_calculator(**kwargs) → Calculator

Get a model specific ase calculator object.

Returns

calc:

ase calculator object

property lammps_pair_coeff: List[str]

Get the lammps pair_coeff command attribute.

See https://docs.lammps.org/pair_coeff.html

Returns

a list of pair_coeff attributes. E.g. [’ * * model/deployed_model.pth B C F H N’]

property lammps_pair_style: str

Get the lammps pair_style command attribute.

See https://docs.lammps.org/pair_style.html Returns ——- This can be e.g. ‘quip’ or ‘allegro’

predict(atoms_list: List[Atoms]) → List[Atoms]

Predict energy, forces and stresses.

based on what was used to train for given atoms objects.

Parameters

atoms_list: typing.List[ase.Atoms]

list of atoms objects to predict on

Returns

Prediction: typing.List[ase.Atoms]

Atoms with updated calculators

use_energy: bool = True

use_forces: bool = True

use_stresses: bool = False

static write_data_to_file(file, atoms_list: List[Atoms])

Save e.g. train / test data to a file.

Parameters

file: str|Path

path to save to.

atoms_list: list[Atoms]

atoms that should be saved.

ipsuite.models.ensemble module

class ipsuite.models.ensemble.EnsembleCalculator(calculators: List[Calculator], **kwargs)

Bases: Calculator

calculate(atoms=None, properties=None, system_changes=['positions', 'numbers', 'cell', 'pbc', 'initial_charges', 'initial_magmoms'])

Do the calculation.

properties: list of str

List of what needs to be calculated. Can be any combination of ‘energy’, ‘forces’, ‘stress’, ‘dipole’, ‘charges’, ‘magmom’ and ‘magmoms’.

system_changes: list of str

List of what has changed since last calculation. Can be any combination of these six: ‘positions’, ‘numbers’, ‘cell’, ‘pbc’, ‘initial_charges’ and ‘initial_magmoms’.

Subclasses need to implement this, but can ignore properties and system_changes if they want. Calculated properties should be inserted into results dictionary like shown in this dummy example:

self.results = {'energy': 0.0,
                'forces': np.zeros((len(atoms), 3)),
                'stress': np.zeros(6),
                'dipole': np.zeros(3),
                'charges': np.zeros(len(atoms)),
                'magmom': 0.0,
                'magmoms': np.zeros(len(atoms))}

The subclass implementation should first call this implementation to set the atoms attribute and create any missing directories.

class ipsuite.models.ensemble.EnsembleModel(*, name: str | None = None, always_changed: bool = False, models: List[ipsuite.models.base.MLModel])

Bases: IPSNode

get_calculator(**kwargs) → Calculator

Property to return a model specific ase calculator object.

Returns

calc:

ase calculator object

models: List[MLModel]

predict(atoms_list: List[Atoms]) → List[Atoms]

Predict energy, forces and stresses.

based on what was used to train for given atoms objects.

Parameters

atoms_list: typing.List[ase.Atoms]

list of atoms objects to predict on

Returns

typing.List[ase.Atoms]

Atoms with updated calculators

run() → None

Module contents

IPS allows for easy use and comparison of different machine learning interatomic potentials. Below you can find all models currently interfaced with this framework. A model’s run method performs training on the provided data. All models provide an ASE calculator, which can be used for inference and analysis of predictions.

Note that each model is an extra dependency and needs to be installed accordingly. See getting started for more information. If you would like to add other models to IPS, please consider this guide.

class ipsuite.models.CP2KModel(config: str | ~pathlib.Path, files: list[str | ~pathlib.Path] = <factory>, cmd: str | None = None)

Bases: object

CP2K ASE calculator model.

Parameters

configstr | Path

Path to the CP2K input file in YAML format. See https://github.com/cp2k/cp2k-input-tools for more information on the input file format.

fileslist[str | Path]

List of files to copy to the cp2k directory. These files are typically basis sets and potential files.

cmdstr | None

Path to the cp2k executable. If not set, the environment variable IPSUITE_CP2K_SHELL is used.

Examples

>> import ipsuite as ips >> project = ips.Project() >> cp2k = ips.CP2KModel( .. config=”cp2k.yaml”, .. files=[“GTH_BASIS_SETS”, “GTH_POTENTIALS”], .. ) >> with project: .. water = ips.Smiles2Conformers(smiles=”O”, numConfs=100) .. box = ips.MultiPackmol( .. data=[water.frames], count=[16], density=1000, n_configurations=11, .. ) .. ips.ApplyCalculator( .. data=box.frames, .. model=cp2k, .. ) >> project.build()

cmd: str | None = None

config: str | Path

files: list[str | Path]

get_calculator(*, directory: str | Path | None = None, **kwargs) → CP2K | CustomCP2K

get_input_script() → dict

Return the input script.

class ipsuite.models.EnsembleModel(*, name: str | None = None, always_changed: bool = False, models: List[ipsuite.models.base.MLModel])

Bases: IPSNode

get_calculator(**kwargs) → Calculator

Property to return a model specific ase calculator object.

Returns

calc:

ase calculator object

models: List[MLModel]

predict(atoms_list: List[Atoms]) → List[Atoms]

Predict energy, forces and stresses.

based on what was used to train for given atoms objects.

Parameters

atoms_list: typing.List[ase.Atoms]

list of atoms objects to predict on

Returns

typing.List[ase.Atoms]

Atoms with updated calculators

run() → None

class ipsuite.models.GenericASEModel(module: str, class_name: str, kwargs: dict[str, Any] | None = None, parameter_paths: str | Path | list[str | Path] | None = None, file_paths: str | Path | list[str | Path] | None = None)

Bases: object

Generic ASE calculator.

Load any ASE calculator from a module and class name.

Parameters

modulestr

Module name containing the calculator class. For LJ this would be ‘ase.calculators.lj’.

class_namestr

Class name of the calculator. For LJ this would be ‘LennardJones’.

kwargsdict, default=None

Additional keyword arguments to pass to the calculator. For LJ this could be {‘epsilon’: 1.0, ‘sigma’: 1.0}.

parameter_pathsstr, Path, list[str|Path], default=None

Path to configuration files for the calculator, e.g. cp2k.yaml.

file_pathsstr, Path, list[str|Path], default=None

Path to files needed by the calculator, e.g. GTH_BASIS_SETS.

property available: bool

class_name: str

file_paths: str | Path | list[str | Path] | None = None

get_calculator(**kwargs) → Calculator

kwargs: dict[str, Any] | None = None

module: str

parameter_paths: str | Path | list[str | Path] | None = None

class ipsuite.models.MACEMPModel(model: str | Path | None = None, device: str = '', default_dtype: str = 'float32', dispersion: bool = False, damping: Literal['zero', 'bj', 'zerom', 'bjm'] = 'bj', dispersion_xc: str = 'pbe', dispersion_cutoff: float = 21.167088422553647, model_path: Path | None = None)

Bases: object

Interface for the MACE model.

For more information, see: - https://github.com/ACEsuit/mace

damping: Literal['zero', 'bj', 'zerom', 'bjm'] = 'bj'

default_dtype: str = 'float32'

device: str = ''

dispersion: bool = False

dispersion_cutoff: float = 21.167088422553647

dispersion_xc: str = 'pbe'

get_calculator(**kwargs)

Get an xtb ase calculator.

model: str | Path | None = None

model_path: Path | None = None

class ipsuite.models.MLModel(*args, **kwargs)

Bases: AnalyseAtoms

Parent class for all MLModel Implementations.

data: list[ase.Atoms]

get_calculator(**kwargs) → Calculator

Get a model specific ase calculator object.

Returns

calc:

ase calculator object

property lammps_pair_coeff: List[str]

Get the lammps pair_coeff command attribute.

See https://docs.lammps.org/pair_coeff.html

Returns

a list of pair_coeff attributes. E.g. [’ * * model/deployed_model.pth B C F H N’]

property lammps_pair_style: str

Get the lammps pair_style command attribute.

See https://docs.lammps.org/pair_style.html Returns ——- This can be e.g. ‘quip’ or ‘allegro’

predict(atoms_list: List[Atoms]) → List[Atoms]

Predict energy, forces and stresses.

based on what was used to train for given atoms objects.

Parameters

atoms_list: typing.List[ase.Atoms]

list of atoms objects to predict on

Returns

Prediction: typing.List[ase.Atoms]

Atoms with updated calculators

use_energy: bool = True

use_forces: bool = True

use_stresses: bool = False

static write_data_to_file(file, atoms_list: List[Atoms])

Save e.g. train / test data to a file.

Parameters

file: str|Path

path to save to.

atoms_list: list[Atoms]

atoms that should be saved.

class ipsuite.models.ORCAModel(simpleinput: str = 'B3LYP def2-TZVP enGrad TightSCF', blocks: str = '%pal nprocs 2 end', cmd: str | None = None)

Bases: object

ORCA ASE calculator model.

Parameters

simpleinputstr

The ORCA input string. For example: “B3LYP def2-TZVP enGrad TightSCF” to compute the energy and forces of a system using the B3LYP functional with the def2-TZVP basis set. See [1]_ for more information.

blocksstr

The ORCA blocks string to select the number of processors and other settings. For example: “%pal nprocs 2 end”.

cmdstr | None

The command to run ORCA. If not set, the environment variable IPSUITE_ORCA_SHELL is used.

Examples

>> import ipsuite as ips >> project = ips.Project() >> orca = ips.ORCAModel( .. simpleinput=”B3LYP def2-TZVP enGrad TightSCF”, .. blocks=”%pal nprocs 2 end”, .. ) >> with project: .. water = ips.Smiles2Conformers(smiles=”O”, numConfs=100) .. ips.ApplyCalculator( .. data=water.frames, .. model=orca, .. ) >> project.build()

[1]

https://orca-manual.mpi-muelheim.mpg.de/index.html

blocks: str = '%pal nprocs 2 end'

cmd: str | None = None

get_calculator(directory: str | Path, **kwargs) → Calculator

simpleinput: str = 'B3LYP def2-TZVP enGrad TightSCF'

class ipsuite.models.TBLiteModel(method: str = 'GFN2-xTB', verbosity: int = 0, charge: int = 0, multiplicity: int = 1)

Bases: object

A model for the TBLite calculator [1]_.

Parameters

methodstr

The method to use for the calculator.

verbosityint

The verbosity level of the calculator.

chargeint

The charge of the structure

multiplicityint

The spin multiplicity of the structure

[1]

https://tblite.readthedocs.io/en/latest/

Examples

>> import ipsuite as ips >> project = ips.Project() >> tblite = ips.TBLiteModel(method=”GFN2-xTB”) >> with project: .. water = ips.Smiles2Conformers(smiles=”O”, numConfs=100) .. box = ips.MultiPackmol( .. data=[water.frames], count=[16], density=1000, n_configurations=11, .. ) .. ips.ApplyCalculator( .. data=box.frames, .. model=tblite, .. ) >> project.build()

charge: int = 0

get_calculator(**kwargs)

Get an xtb ase calculator.

method: str = 'GFN2-xTB'

multiplicity: int = 1

verbosity: int = 0

class ipsuite.models.TorchDFTD3(xc: str, damping: str, cutoff: float, abc: bool, cnthr: float, dtype: str, device: str | None = None, skin: float = 0.0)

Bases: object

Compute D3 correction terms using torch-dftd.

Attributes

xc : str damping : str cutoff : float abc : bool

ATM 3-body interaction

cnthrfloat

Coordination number cutoff distance in angstrom

dtypestr

Data type used for the calculation.

devicestr

Device used for the calculation. Defaults to “cuda” if available, otherwise “cpu”.

skinfloat

If > 0, switches to a D3 implementation that reuses neighborlists. This can significantly improve performance.

abc: bool

cnthr: float

cutoff: float

damping: str

device: str | None = None

dtype: str

get_calculator(**kwargs)

skin: float = 0.0

xc: str