ASE calculators

calorine provides two ASE calculators for NEP calculations, one that uses the GPU implementation and one that uses the CPU implementation of NEP. For smaller calculations the CPU calculators is usually more performant. For very large simulations and for comparison the GPU calculator can be useful as well. The GPU calculator can also be used to set up molecular dynamics simulations with GPUMD using the run_custom_md method.

CPU calculator

class calorine.calculators.CPUNEP(model_filename, atoms=None, label=None, debug=False)[source]

This class provides an ASE calculator for nep_cpu, the in-memory CPU implementation of GPUMD.

Parameters:

  • model_filename (str) – Path to file in nep.txt format with model parameters

  • atoms (Atoms) – Atoms to attach the calculator to

  • label (str) – Label for this calclator

  • debug (bool, optional) – Flag to toggle debug mode. Prints GPUMD output. Defaults to False.

Raises:

  • FileNotFoundError – Raises FileNotFoundError if model_filename does not point to a valid file.

  • ValueError – Raises ValueError atoms are not defined when trying to get energies and forces.

Example

>>> calc = CPUNEP('nep.txt')
>>> atoms.calc = calc
>>> atoms.get_potential_energy()
get_descriptors(atoms=None, properties=None, system_changes=['positions', 'numbers', 'cell', 'pbc', 'initial_charges', 'initial_magmoms'])[source]

Calculates the descriptor tensor for the current structure. This is a wrapper function for calculate().

Parameters:

  • atoms (Atoms, optional) – System for which to calculate properties, by default None

  • properties (List[str], optional) – Properties to calculate, by default None

  • system_changes (List[str], optional) – Changes to the system since last call, by default all_changes

Return type:

descriptors with shape (number_of_atoms, descriptor_components)

get_dipole_gradient(displacement=0.01, method='central difference', charge=1.0)[source]

Calculates the dipole gradient using finite differences.

Parameters:

  • displacement (float) – Displacement in Å to use for finite differences. Defaults to 0.01 Å.

  • method (str) – Method for computing gradient with finite differences. One of ‘forward difference’ and ‘central difference’. Defaults to ‘central difference’

  • charge (float) – System charge in units of the elemental charge. Used for correcting the dipoles before computing the gradient. Defaults to 1.0.

Return type:

dipole gradient with shape (N, 3, 3) where N are the number of atoms.

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

Calculates the polarizability tensor for the current structure. The model must have been trained to predict the polarizability. This is a wrapper function for calculate().

Parameters:

  • atoms (Atoms, optional) – System for which to calculate properties, by default None

  • properties (List[str], optional) – Properties to calculate, by default None

  • system_changes (List[str], optional) – Changes to the system since last call, by default all_changes

Return type:

polarizability with shape (3, 3)

get_polarizability_gradient(displacement=0.01, component='full')[source]

Calculates the dipole gradient for a given structure using finite differences. This function computes the derivatives using the second-order central difference method with a C++ backend.

Parameters:

  • displacement (float) – Displacement in Å to use for finite differences. Defaults to 0.01.

  • component (Union[str, List[str]]) – Component or components of the polarizability tensor that the gradient should be computed for. The following components are available: x, y, z, full Option full computes the derivative whilst moving the atoms in each Cartesian direction, which yields a tensor of shape (N, 3, 3, 3), where N is the number of atoms. Multiple components may be specified. Defaults to full.

Return type:

polarizability gradient with shape (N, C, 3, 3) with C components chosen.

set_atoms(atoms)[source]

Updates the Atoms object.

Parameters:

atoms (Atoms) – Atoms to attach the calculator to

GPU calculator

class calorine.calculators.GPUNEP(model_filename, directory=None, label='GPUNEP', atoms=None, command='gpumd', gpu_identifier_index=0)[source]

This class provides an ASE calculator for NEP calculations with GPUMD.

This calculator writes files that are input to the gpumd executable. It is thus likely to be slow if many calculations are to be performed.

Parameters:

  • model_filename (str) – Path to file in nep.txt format with model parameters.

  • directory (str) – Directory to run GPUMD in. If None, a temporary directory will be created and removed once the calculations are finished. If specified, the directory will not be deleted. In the latter case, it is advisable to do no more than one calculation with this calculator (unless you know exactly what you are doing).

  • label (str) – Label for this calculator.

  • atoms (Atoms) – Atoms to attach to this calculator.

  • command (str) – Command to run GPUMD with. Default: gpumd

  • gpu_identifier_index (int) – Index that identifies the GPU that GPUNEP should be run with. Typically, NVIDIA GPUs are enumerated with integer indices. See https://docs.nvidia.com/cuda/cuda-c-programming-guide/index.html#env-vars. Set to None in order to use all available GPUs. Note that GPUMD exit with an error when running with more than one GPU if your system is not large enough. Default: 1

Example

>>> calc = GPUNEP('nep.txt')
>>> atoms.calc = calc
>>> atoms.get_potential_energy()
run_custom_md(parameters, return_last_atoms=False, only_prepare=False)[source]

Run a custom MD simulation.

Parameters:

  • parameters (List[Tuple[str, Any]]) –

    Parameters to be specified in the run.in file. The potential keyword is set automatically, all other keywords need to be set via this argument. Example:

    [('dump_thermo', 100),
 ('dump_position', 1000),
 ('velocity', 300),
 ('time_step', 1),
 ('ensemble', ['nvt_ber', 300, 300, 100]),
 ('run', 10000)]

  • return_last_atoms (bool) – If True the last saved snapshot will be returned.

  • only_prepare (bool) –

    If True the necessary input files will be written

    but theMD run will not be executed.

Returns:

The last snapshot if return_last_atoms is True.

set_atoms(atoms)[source]

Set Atoms object. Used also when attaching calculator to Atoms object.

set_directory(directory)[source]

Set path to a new directory. This makes it possible to run several calculations with the same calculator while saving all results