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 calculator 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, dftd3=None)[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 | None) – Atoms to attach the calculator to
label (str | None) – Label for this calclator
debug (bool) – Flag to toggle debug mode. Prints GPUMD output. Defaults to False.
dftd3 (dict[str, Any] | None) – Settings for the DFT-D3 dispersion correction with Becke-Johnson damping, added to the energy, forces and virials of a potential model. The keys are functional, potential_cutoff and coordination_number_cutoff, the cutoffs in Å, for example dict(functional='pbe', potential_cutoff=12, coordination_number_cutoff=6). The coordination number cutoff must not exceed the potential cutoff. An unsupported functional raises ValueError when the calculator is created. The energy is truncated at the potential cutoff without a switching function, as in GPUMD. Energy and forces change by a step as a pair crosses it, about 1e-4 eV per pair at 12 Å, and a molecular dynamics run does not conserve the energy exactly. Place the potential cutoff between neighbor shells. A cutoff on a shell includes or excludes the whole shell depending on rounding, which makes the energy of a crystal depend on the supercell it is computed in. Defaults to None.

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

property dftd3: dict[str, Any] | None#: Settings for the DFT-D3 dispersion correction, fixed when the calculator is created. None if no correction is applied.

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

Calculates (if needed) and returns the Born effective charges. Note that this requires a qNEP model.

Parameters:

atoms (Atoms) – System for which to calculate properties, by default None.
properties (list[str]) – Properties to calculate, by default None.
system_changes (list[str]) – Changes to the system since last call, by default all_changes.

Return type:

ndarray

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) – System for which to calculate properties, by default None
properties (list[str]) – Properties to calculate, by default None
system_changes (list[str]) – Changes to the system since last call, by default all_changes

Return type:

ndarray

get_dipole_gradient(displacement=0.01, method='central difference', charge=1.0, atoms=None)[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.
atoms (Atoms) – System for which to compute the gradient. A copy is attached to the calculator. Defaults to None, in which case the structure that is already attached is used.

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) – System for which to calculate properties, by default None
properties (list[str]) – Properties to calculate, by default None
system_changes (list[str]) – Changes to the system since last call, by default all_changes

Return type:

ndarray

get_polarizability_gradient(displacement=0.01, component='full', atoms=None)[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 (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.
atoms (Atoms) – System for which to compute the gradient. A copy is attached to the calculator. Defaults to None, in which case the structure that is already attached is used.

Return type:

ndarray

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=None, gpu_identifier_index=0, dftd3=None)[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, or the value of the CALORINE_GPUMD_COMMAND environment variable if set.
gpu_identifier_index (int | None) – 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: 0
dftd3 (dict[str, Any] | None) – Settings for the DFT-D3 dispersion correction, which is applied to every run of this calculator, meaning single-point calculations as well as run_custom_md(). The keys are functional, potential_cutoff and coordination_number_cutoff, the two cutoffs in units of Angstrom. Example: dict(functional='pbe', potential_cutoff=12, coordination_number_cutoff=6). GPUMD carries the list of functionals, documented under the dftd3 keyword at https://gpumd.org, and implements the correction for a single GPU only. The dispersion energy is truncated at the potential cutoff without a switching function, so a cutoff that coincides with a neighbor shell of the structure makes the energy and the pressure step as an atom crosses it. Choose a cutoff that falls between shells. Default: None

Example

>>> calc = GPUNEP('nep.txt')
>>> atoms.calc = calc
>>> atoms.get_potential_energy()

property dftd3: dict[str, Any] | None#

Settings for the DFT-D3 dispersion correction, None if the calculator applies none.

The settings are fixed when the calculator is created, since the results already obtained were computed with them.

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

Calculates (if needed) and returns the Born effective charges. Note that this requires a qNEP model.

Parameters:

atoms (Atoms) – System for which to calculate properties, by default None.
properties (list[str]) – Properties to calculate, by default None.
system_changes (list[str]) – Changes to the system since last call, by default all_changes.

Return type:

ndarray

get_charges_and_becs_from_file()[source]#

Reads the charges and the Born effective charges from the last frame of charges_and_bec.xyz, which a charge model writes.

Returns:: Charges in e, of shape (len(atoms),), and Born effective charges of shape (len(atoms), 9) in row-major full-3x3 order.

get_forces_from_file()[source]#

Reads the forces from the last frame of movie.xyz.

Returns:: Forces in eV/Å, of shape (len(atoms), 3).

get_potential_energy_and_stresses_from_file()[source]#

Reads the potential energy and the stresses from the last row of thermo.out, taking them by column name.

Returns:: Potential energy in eV and the stress tensor in eV/Å^3, the latter in ASE Voigt order (xx, yy, zz, yz, xz, xy).
Raises:: ValueError – If the last row of thermo.out holds no energy or no stress.

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. A dftd3 keyword raises here if the calculator carries a dispersion correction of its own. Example:
```
[('dump_thermo', 100),
 ('dump_xyz', (1000, 'movie.xyz')),
 ('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. This requires parameters to contain a dump_xyz keyword writing to movie.xyz, since that is the file read back.
only_prepare (bool) –

If True the necessary input files will be written
but the MD 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