Potential objects

ASE-compatible Calculator from a quip-potential object

class quippy.potential.Potential(args_str='', pot1=None, pot2=None, param_str=None, param_filename=None, atoms=None, calculation_always_required=False, calc_args=None, add_arrays=None, add_info=None, **kwargs)

Bases: Calculator

Module potential_module

Defined at Potential.fpp lines 201-3758

This module encapsulates all the interatomic potentials implemented in QUIP

A Potential object represents an interatomic potential, a tight binding model or an interface to an external code used to perform calculations. It is initialised from an args_str describing the type of potential, and an XML formatted string param_str giving the parameters.

Types of Potential:

args_str prefix	Description
IP	Interatomic Potential
TB	Tight Binding Model
FilePot	File potential, used to communicate with external program
CallbackPot	Callback potential, computation done by Python function
Sum	Sum of two other potentials
ForceMixing	Combination of forces from two other potentials

Types of interatomic potential available:

Types of tight binding potential available:

args_str prefix	Description
TB Bowler	Bowler tight binding model
TB DFTB	Density functional tight binding
TB GSP	Goodwin-Skinner-Pettifor tight binding model
TB NRL_TB	Naval Research Laboratory tight binding model

Examples of the XML parameters for each of these potential can be found in the src/Parameters

Pythonic interface to auto-generated quippy.potential_module.Potential class

directory of the QUIP git repository.

Methods

get_default_properties()	Get the list of properties to be calculated by default
set_default_properties(properties)	Set the list of properties to be calculated by default

band_structure()

Create band-structure object for plotting.

calculate(self, at[, energy, force, virial, local_energy, local_virial, args_str, error])

Defined at Potential.fpp lines 934-1101

Pythonic wrapper to quippy.potential_module.Potential.calc()

atoms: ase.atoms.Atoms object

Atoms object with which to calculate. This is converted to a quippy.atoms_module.Atoms object to pass to Fortran.

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

calc_args: argument string to pass to Fortran calc() routine.

This is appended to self.calc_args, if this is set.

add_arrays: list, str or True

Arrays to carry over from atoms.arrays to the Fortran atoms object when calling calculate() If the same argument is filled in calculate, then it will overwrite this. String arrays not supported. possible types:

None - only defaults: pos, Z, cell, pbc, momenta (as velo, if exists) str - single key list - all list elements as keys True - all of the arrays from atoms.arrays

add_info: list, str or True

Info to carry over from atoms.info to the Fortran atoms object when calling calculate() If the same argument is filled in calculate, then it will overwrite this. possible types:

None - only defaults: pos, Z, cell, pbc, momenta (as velo, if exists) str - single key list - all list elements as keys True - all of the values from atoms.info

Arrays can also be passed directly to the Fortran routine using the forces, virial, local_energy, local_virial arguments. These should be pre-allocated as Fortran-contigous arrays, e.g. forces = np.zeros((len(atoms), 3), order=’F’).

If present, vol_per_atom is used to convert from local_virial to per-atom stresses; this can either be a scalar or the name of an array in atoms.arrays. If not present the average volume per atom is used.

Additional keyword arguments are appended to calc_args.

Non-standard calculation results (such as gap_local_variance) are stored in self.extra_results.

Parameters:

thisPotential

atAtoms

energyfloat

forcefloat array

virialfloat array

local_energyfloat array

local_virialfloat array

args_strstr

errorint

Apply this Potential to the Atoms object

‘at’. Atoms%calc_connect is automatically called to update the

connecticvity information – if efficiency is important to you,

ensure that at%cutoff_skin is set to a non-zero value to decrease

the frequence of connectivity updates.

optional arguments determine what should be calculated and how

it will be returned. Each physical quantity has a

corresponding optional argument, which can either be an ‘True’

to store the result inside the Atoms object(i.e. in

Atoms%params’ or in ‘Atoms%properties’ with the

default name, a string to specify a different property or

parameter name, or an array of the the correct shape to

receive the quantity in question, as set out in the table

below.

================ ============= ================ =========================

Array argument Quantity Shape Default storage location

================ ============= ================ =========================

``energy`` Energy ``()`` ``energy`` param

``local_energy`` Local energy ``(at.n,)`` ``local_energy`` property

``force`` Force ``(3,at.n)`` ``force`` property

``virial`` Virial tensor ``(3,3)`` ``virial`` param

``local_virial`` Local virial ``(3,3,at.n)`` ``local_virial`` property

================ ============= ================ =========================

The ‘args_str’ argument is an optional string containing

additional arguments which depend on the particular Potential

being used.

Not all Potentials support all of these quantities: an error

will be raised if you ask for something that is not supported.

.. rubric:: args_str options

=============== ===== ===== ===========================================================================

Name Type Value Doc

=============== ===== ===== ===========================================================================

energy None If present, calculate energy and put it in field with this string as name

virial None If present, calculate virial and put it in field with this string as name

force None If present, calculate force and put it in field with this string as name

local_energy None If present, calculate local energy and put it in field with this string as

name

local_virial None If present, calculate local virial and put it in field with this string as

name

r_scale float 0.0 Distance rescale factor. Overrides r_scale init arg

E_scale float 0.0 Energy rescale factor. Overrides E_scale init arg

do_calc_connect bool T Switch on/off automatic calc_connect() calls.

=============== ===== ===== ===========================================================================

calculate_numerical_forces(atoms, d=0.001)

Calculate numerical forces using finite difference.

All atoms will be displaced by +d and -d in all directions.

calculate_numerical_stress(atoms, d=1e-06, voigt=True)

Calculate numerical stress using finite difference.

calculate_properties(atoms, properties)

This method is experimental; currently for internal use.

check_state(atoms, tol=1e-15)

Check for any system changes since last calculation.

get_default_properties()

Get the list of properties to be calculated by default

get_magnetic_moments(atoms=None)

Calculate magnetic moments projected onto atoms.

get_property(name, atoms=None, allow_calculation=True)

Get the named property.

get_stresses(atoms=None)

the calculator should return intensive stresses, i.e., such that stresses.sum(axis=0) == stress

read(label)

Read atoms, parameters and calculated properties from output file.

Read result from self.label file. Raise ReadError if the file is not there. If the file is corrupted or contains an error message from the calculation, a ReadError should also be raised. In case of succes, these attributes must set:

atoms: Atoms object

The state of the atoms from last calculation.

parameters: Parameters object

The parameter dictionary.

results: dict

Calculated properties like energy and forces.

The FileIOCalculator.read() method will typically read atoms and parameters and get the results dict by calling the read_results() method.

reset()

Clear all information from old calculation.

set(**kwargs)

Set parameters like set(key1=value1, key2=value2, …).

A dictionary containing the parameters that have been changed is returned.

Subclasses must implement a set() method that will look at the chaneged parameters and decide if a call to reset() is needed. If the changed parameters are harmless, like a change in verbosity, then there is no need to call reset().

The special keyword ‘parameters’ can be used to read parameters from a file.

set_default_properties(properties)

Set the list of properties to be calculated by default

set_label(label)

Set label and convert label to directory and prefix.

Examples:

• label=’abc’: (directory=’.’, prefix=’abc’)

• label=’dir1/abc’: (directory=’dir1’, prefix=’abc’)

• label=None: (directory=’.’, prefix=None)

default_parameters: Dict[str, Any] = {}

Default parameters

discard_results_on_any_change = False

Whether we purge the results following any change in the set() method.

ignored_changes: Set[str] = {}

Properties of Atoms which we ignore for the purposes of cache

implemented_properties: List[str] = ['energy', 'free_energy', 'forces', 'stress', 'stresses', 'energies']

Properties calculator can handle (energy, forces, …)