NudgedElasticBand

class NudgedElasticBand(configuration_list, image_distance=None, generate_images=None, wrap_pbc=None, endpoint_energies=None, endpoint_forces=None, endpoint_stress=None)

Nudged Elastic Band as a series of configurations.

Parameters:
  • configuration_list (list of MoleculeConfiguration | BulkConfiguration | DeviceConfiguration | SurfaceConfiguration) – A list configurations that must be included in the series of configurations. Must hold at least two configurations. Additionally, all configurations must be of the same type, with the same elements, and with the same spatial regions.
  • image_distance (PhysicalQuantity of type length) – Distance between the coordinates of successive configurations in the series of configurations if auto-generation is enabled.
    Default: 0.5*Angstrom
  • generate_images (bool | LinearInterpolation | HalgrenLipscomb | ImageDependentPairPotential) – Auto-generate intermediate images between specified configurations where necessary, such that no distance between successive images is greater than the image_distance parameter.
    Default: LinearInterpolation
  • wrap_pbc (bool) – Sets how to calculate the distance between the images. For some plugins (e.g. VASP) the atoms have been wrapped back inside of the box during the simulation. This means that the distance between images must be PBC aware.
    Default: False
  • endpoint_energies (PhysicalQuantity of type energy) – The energies of the NEB endpoints may be supplied if they are known. This speeds up calculations.
    Default: Energies not known.
  • endpoint_forces (PhysicalQuantity of type force) – The forces of the NEB endpoints may be supplied if they are known. This speeds up calculations.
    Default: Forces not known.
  • endpoint_stress (PhysicalQuantity of type stress) – The stress of the NEB endpoints may be supplied if they are known. This speeds up calculations.
    Default: Stress not known.
addTags(tags, indices=None)

Add a set of tags, to atoms matching a collection of indices, for each NEB image.

Parameters:
  • tags (list | str) – The list of tags to add to matching atoms.
  • indices (list | int | None) – The list of indices to match atoms against. If None, then all atoms are matched.
    Default: All indices.
bonds()

Get the list of bond connections to can be used for bonded potentials in ATK-ForceField. The same bond list applies to all images

Returns:An array with the the two atom indices for each bond along with the vector which periodic images this bond connects.
Return type:array
calculator()
Returns:The calculator attached to the first image.
Return type:Calculator
calculators()
Returns:A list of all attached calculators.
Return type:list of Calculator
cartesianCoordinates()
Returns:The coordinates of the all the images in the NEB. A MxNx3 array is returned where M is the number of images and N is the number of atoms per image.
Return type:PhysicalQuantity of type length
configurationCopy(new_coordinates=None, copy_calculator=False)

Copy the NEB, with new coordinates.

Parameters:
  • new_coordinates (PhysicalQuantity of length units | None) – The new coordinates to set, given as a MxNx3 array where M is the number of images and N is the number of atoms in each image.
    Default: Leave coordinates unchanged.
  • copy_calculator (bool) – Copy the calculator and set the initial_state/initial_spin appropriately.
    Default: False
Returns:

A copy of the current NEB

Return type:

NudgedElasticBand

configurationType()
Returns:The type of configurations stored in the nudged elastic band.
Return type:MoleculeConfiguration | BulkConfiguration | DeviceConfiguration | SurfaceConfiguration
copy()
Returns:A copy of the current configuration.
Return type:NudgedElasticBand
dielectricRegions()
Returns:The dielectric regions in the configuration.
Return type:list of BoxRegion | SphereRegion | TubeRegion
elements()
Returns:The elements in the nudged elastic band.
Return type:list of PeriodicTableElement
energies()
Returns:The energies of the images. None will be returned if the energies are not available.
Return type:PhysicalQuantity of type energy | None
enthalpies()
Returns:The enthalpies of the images. None will be returned if the enthalpies are not available.
Return type:PhysicalQuantity of type energy | None
forces()
Returns:The forces of the images. If there are M images and N atoms a MxNx3 array of forces will be returned. None will be returned if the forces are not available.
Return type:PhysicalQuantity of type force | None
ghostAtoms()
Returns:The list of ghost atoms.
Return type:list of ints
image(index)
Parameters:index (int) – The index of the image.
Returns:The configuration at the specified index.
Return type:MoleculeConfiguration | BulkConfiguration | DeviceConfiguration | SurfaceConfiguration
imageDistance()
Returns:The image distance.
Return type:PhysicalQuantity of type length
images()
Returns:All configurations in the nudged elastic band.
Return type:list of MoleculeConfiguration | BulkConfiguration | DeviceConfiguration | SurfaceConfiguration
indicesFromTags(tags)

List the indices associated with a given collection of tags.

Parameters:tags (list | str) – A list of tags for which all matching indices should be extracted.
Returns:The list of indices corresponding to the specified tag name(s).
Return type:list of ints
maxEnergyImageIndex()
Returns:The index of the image with the highest energy.
Return type:int
metallicRegions()
Returns:The metallic regions for the configuration.
Return type:list of BoxRegion | SphereRegion | TubeRegion
metatext()
Returns:The metatext of the object or None if no metatext is present.
Return type:str | unicode | None
reactionCoordinates()
Returns:The distance from the first image along the series of images.
Return type:PhysicalQuantity of type length
refine(first, last, image_distance)

Refine a section of the reaction path. Any images between the specified starting and ending images are dropped in favor of the new refinement images.

Parameters:
  • first (int) – The starting image index in the reaction sub-path being refined.
  • last (int) – The ending image index in the reaction sub-path being refined.
  • image_distance (PhysicalQuantity of type length) – The maximum distance between successive configurations.
removeTags(tags=None, indices=None, purge=False)

Remove a set of tags from atoms matching a collection of indices.

Parameters:
  • tags (list | str) – The list of tags to add to matching atoms.
    Default: All tags.
  • indices (list | int) – The list of indices to match atoms against.
    Default: All indices.
  • purge (bool) – When removing tags from the configuration, delete the tag completely when not associated with any atoms anymore.
    Default: False
setBravaisLattice(*args, **kwargs)

Method for setting the Bravais lattice. Only nudged elastic bands containing bulk configurations are affected.

Parameters:
  • bravais_lattice (BravaisLattice) – The new lattice.
  • image_index (int) – Image index of the BulkConfiguration to be modified.
    Default: all images
  • conserve_coordinates (Cartesian | Fractional) – The type of coordinates to conserve.
    Default: Cartesian
setCalculator(calculator, initial_state=None, initial_spin=None)

Attach a calculator to the NudgedElasticBand.

Parameters:
setCartesianCoordinates(cartesian_coordinates, skip_checks=False)

Set the Cartesian coordinates for the atoms in each image.

Parameters:
  • cartesian_coordinates (PhysicalQuantity of type length) – The new coordinates of the atoms in each image.
  • skip_checks (bool) – Skip argument type checking and just directly assign the value.
    Default: False
setDielectricRegions(*args, **kwargs)

Set the dielectric regions for the configuration.

Parameters:dielectric_regions (list of BoxRegion | SphereRegion | TubeRegion) – The list of dielectric regions to set.
setMetallicRegions(*args, **kwargs)

Set the metallic regions for the configuration.

Parameters:metallic_regions (list of BoxRegion | SphereRegion | TubeRegion) – The list of metallic regions to set.
setMetatext(metatext)

Set a given metatext string on the object.

Parameters:metatext (str | unicode | None) – The metatext string that should be set. A value of “None” can be given to remove the current metatext.
startSeriesCalculation()

Start series calculation, in which the calculator is not copied with __call__.

stopSeriesCalculation()

Stop series calculation, and re-enable copying of the calculator with __call__.

stresses()
Returns:The residual stress of the images, i.e. the actual stress minus the target stress is returned. If there are M images a Mx3x3 array of stress will be returned. None will be returned if the stress is not (has not been) calculated (e.g. in case of a molecular or fixed cell NEB).
Return type:PhysicalQuantity of type stress | None
symbols()
Returns:The element symbols of the configuration.
Return type:list of str
tags(indices=None)

List the tags associated with a given collection of indices. The list returned is the set union of tags associated with the given indices. If no collection of indices is provided, then all tags on the configuration are returned.

Parameters:indices (list | int) – The indices to check.
Default: All indices.
Returns:The set union of tags present on the provided indices.
Return type:set
tangents()
Returns:The normalized NEB tangent directions. This is a (num_images, num_atoms + 3, 3) array.
Return type:ndarray of type float
targetPressure()
Returns:The target pressure if set.
Return type:PhysicalQuantity of type pressure | None
uniqueElements()
Returns:The unique elements contained in the nudged elastic band.
Return type:list of PeriodicTableElement
update(log_filename_prefix=<class 'NL.ComputerScienceUtilities.NLFlag._NLFlag.Automatic'>)

Update all images using the calculator stored on the class.

The number of processes used to calculate the energy and forces on each image is determined by the ParallelParameters object that has been set on the attached calculator. By default, the update is parallelized over images and then over the per-image calculation.

The output from the calculation for each image will be logged to a separate file. Each file’s name is set by log_filename_prefix with the image ID as a suffix. If the log files already exist they will be appended to.

Parameters:
  • target_stress (PhysicalQuantity of type pressure | None) – The target stress of the system given as a 3x3 internal stress tensor. If None is given, then the target stress is set to zero.
  • log_filename_prefix (Automatic | str | None) – The logging output from each image will be written to filenames starting with this value. If it is set to Automatic then the prefix will be the name of the calling python script. If it is set to None, then all output will be written to stdout.
    Default: Automatic
variableCell()
Returns:Whether this is a VC-NEB Configuration.
Return type:Bool

Usage Examples

Setup a nudged elastic band calculation for conversion of ethane to ethene, i.e.

\[\mathrm{C}_2\mathrm{H}_6 \rightarrow \mathrm{C}_2\mathrm{H}_4 +\mathrm{H}_2\]
# Find the reaction path
optimized_neb = OptimizeNudgedElasticBand(
        neb_configuration,
        max_forces=0.05*eV/Ang)

neb_c6h6.py

Calculate the TotalEnergy for all images in a nudged elastic band configuration:

# Define elements.
elements = [Oxygen, Hydrogen, Hydrogen]

# Define coordinates.
c0 = [[  0.00,   0.00,   0.12],
      [  0.00,   0.76,  -0.48],
      [  0.00,  -0.76,  -0.48]]*Angstrom

c1 = [[  0.00,   0.00,   1.20],
      [  0.00,   0.76,  -0.48],
      [  0.00,  -0.76,  -0.48]]*Angstrom

# Set up a list of configurations.
configuration_list = [ MoleculeConfiguration(elements,c) for c in [c0,c1] ]

# Create the NudgedElasticBand object.
neb = NudgedElasticBand(configuration_list)

# Set a calculator on the configurations in the NEB - for analysis.
neb.setCalculator(LCAOCalculator())

# Create a Trajectory with a TotalEnergy analysis carried out on each configuration.
t = MakeTrajectory(neb, TotalEnergy)

maketrajectory2.py

Variable Cell NEB

A variable cell NEB is constructed when using bulk configurations that have different unit cells. When used with OptimizeNudgedElasticBand() both the atomic and lattice degrees of freedom are optimized. Great care must be taken when constructing the initial and final images. Just as in the regular NEB algorithm, the atom indices in the initial and final structure must match. Atom #1 in the initial structure will be moved to atom #1 in the final structure. This means that you cannot simply take two different crystal structures with the same number of atoms and expect the resulting pathway to be correct.

See the Variable Cell NEB section on the OptimizeNudgedElasticBand page for more information on variable cell NEB calculations.

Notes

The NudgedElasticBand configuration sets up a reaction path for a nudged elastic band calculation [HUJonsson00][SXC+12].

When generate_images is True the automatically generated images are created using a linear interpolation between the endpoints. Periodic boundary conditions are not considered in this interpolation, i.e. the interpolated pathway will not follow the minimum image convention.

[HUJonsson00]G. Henkelman, B. P. Uberuaga, and H. Jónsson. A climbing image nudged elastic band method for finding saddle points and minimum energy paths. J. Chem. Phys., 2000.
[SXC+12]Daniel Sheppard, Penghao Xiao, William Chemelewski, Duane D. Johnson, and Graeme Henkelman. A generalized solid-state nudged elastic band method. The Journal of Chemical Physics, 136(7):074103, 2012. doi:10.1063/1.3684549.