# 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)[source]

Module potential_module

Defined at Potential.fpp lines 201-3716

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 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])[source]

Defined at Potential.fpp lines 928-1093

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.

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

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.

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

check_state(atoms, tol=1e-15)

Check for any system changes since last calculation.

get_default_properties()[source]

Get the list of properties to be calculated by default

get_magnetic_moments(atoms=None)

Calculate magnetic moments projected onto atoms.

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)[source]

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)

Calculators that must write results to files with fixed names can override this method so that the directory is set to all of label.