NudgedElasticBand

class NudgedElasticBand(configuration_list, image_distance=None, generate_images=None, number_of_intermediate_images=None, wrap_pbc=None, endpoint_energies=None, endpoint_forces=None, endpoint_stresses=None, use_min_image_convention=False)

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 | ImageDependentPairPotential) – Auto-generate intermediate images between specified configurations where necessary, such that no distance between successive images is greater than the image_distance parameter. Variable-cell NEBs only work with LinearInterpolation.
  Default: LinearInterpolation.

• number_of_intermediate_images (int) – The number of images between the endpoints. Mutually exclusive with image_distance. Requires configuration_list to contain exactly two configurations.

• wrap_pbc (bool) – For some plugins (e.g. VASP) the atoms have been wrapped back inside the box during the simulation. This means that the distance between images must be PBC aware. Setting this argument to True takes the wrapping into account.
  Default: False.

• endpoint_energies (sequence(2) of 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 (sequence(2) of 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_stresses (sequence(2) of PhysicalQuantity of type stress) – The stresses of the NEB endpoints may be supplied if they are known. This speeds up calculations.
  Default: Stress not known.

• use_min_image_convention (bool) – Whether to compute the minimum image convention distance between the initial and final configurations.
  Default: False.

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.

additionalMinima()

Method to determine additional minima besides the endpoints.

Returns:

A list containing the indices of images that are minima on the reaction coordinate excluding the endpoints.

Return type:

list of type int | None

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

compare(other, the_type=True, elements=True, ghosts=True, cell=True, positions=True, regions=True, tags=True, velocities=False, bonds=False, throws=False, msg='Compared NEB configurations differ.\n')

A method to compare two NEB configurations by comparing their images. It is possible to turn some comparisons off. If the comparison passes all the activated checks, the method returns True, otherwise False…

Parameters:

• other (NudgedElasticBand) – The other configuration to compare with.

• the_type (bool) – Whether or not to compare the type.
  Default: True.

• elements (bool) – Whether or not to compare the elements.
  Default: True.

• ghosts (bool) – Whether or not to compare the ghosts.
  Default: True.

• cell (bool) – Whether or not the compare the cells.
  Default: True.

• positions (bool) – Whether or not to compare the positions.
  Default: True.

• regions (bool) – Whether or not to compare the regions.
  Default: True.

• tags (bool) – Whether or not to compare the tags.
  Default: True.

• velocities (bool) – Whether or not to compare the velocities.
  Default: False.

• bonds (bool) – Whether or not to compare the bonds.
  Default: False.

• throws (bool) – Whether or not an exception should be raised on differences.
  Default: False.

• msg (str) – The message to use when throwing exceptions.
  Default: Compared configurations differ.\n.

Returns:

True, if configurations are identical.

Return type:

bool

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

constraintCorrections()

Returns:

a dictionary containing the correction to energy, forces and stresses, if any, introduced by constraints during an NEB optimization.

Return type:

dict

copy()

Returns:

A copy of the current configuration.

Return type:

NudgedElasticBand

deleteAtoms(*args, **kwargs)

Remove atoms from a NEB.

All arguments and keyword arguments are passed on.

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(include_constraints=True)

Parameters:

include_constraints (bool) – If this object was generated by an NEB optimization with constraints, determine whether the output energies should include constraint corrections or not.

Returns:

The energies of the images. None will be returned if the energies are not available.

Return type:

PhysicalQuantity of type energy | None

enthalpies(include_constraints=True)

Parameters:

include_constraints (bool) – If this object was generated by an NEB optimization with constraints, determine whether the output enthalpies should include constraint corrections or not.

Returns:

The enthalpies of the images. None will be returned if the enthalpies are not available.

Return type:

PhysicalQuantity of type energy | None

forces(include_constraints=True)

Parameters:

include_constraints (bool) – If this object was generated by an NEB optimization with constraints, determine whether the output forces should include constraint corrections or not.

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

forwardBarrier(include_constraints=True)

Calculate the forward barrier of the NEB using the maximum energy image.

Parameters:

include_constraints (bool) – If this object was generated by an NEB optimization with constraints, determine whether the output energies should include constraint corrections or not.

Returns:

The forward barrier.

Return type:

PhysicalQuantity of type energy

ghostAtoms()

Returns:

The list of ghost atoms.

Return type:

list of ints

hermiteSpline(x, y, npoints=20)

Calculates a piecewise cubic Hermite spline.

Parameters:

• x (array) – The x coordinates.

• y (array) – The values for each x coordinate.

• npoints (int) – The number of interpolated points between each input coordinate.

Returns:

The new grid of x coordinates and the value of the interpolant.

Return type:

2-tuple

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

nlinfo()

Returns:

The NudgedElasticBand information.

Return type:

dict

numberOf()

Returns:

The image distance.

Return type:

PhysicalQuantity of type length

reactionCoordinates()

Returns:

The distance from the first image along the series of images.

Return type:

PhysicalQuantity of type length

refine(first, last, image_distance=None, number_of_intermediate_images=None, interpolation_algorithm=None)

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.
  Default: 0.5*Angstrom.

• number_of_intermediate_images (int) – The number of images between the endpoints. Mutually exclusive with image_distance.

• interpolation_algorithm (LinearInterpolation | ImageDependentPairPotential | HalgrenLipscomb) – The type of interpolation to use.
  Default: LinearInterpolation.

reinterpolate(interpolation_method, constraints=None, progress_bar=None)

Re-interpolate the current NEB using the given method.

Parameters:

• interpolation_method (LinearInterpolation | HalgrenLipscomb | ImageDependentPairPotential) – The interpolation method to use.

• constraints (list of ints) – List of atom indices that are kept fixed during interpolation.
  Default: [].

• progress_bar (Class with a 'setValue' method) – The progress to update while interpolating.

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.

resetConstraintCorrections()

Reset the dictionary containing constraint corrections.

resetOptimizationState()

Resets the saved optimization state.

reverseBarrier(include_constraints=True)

Calculate the reverse barrier of the NEB using the maximum energy image.

Parameters:

include_constraints (bool) – If this object was generated by an NEB optimization with constraints, determine whether the output energies should include constraint corrections or not.

Returns:

The reverse barrier.

Return type:

PhysicalQuantity of type energy

saveOptimizationState(step, optimizer, previous_max_image)

Saves the current optimization state. This is used during the NEB optimization process and its restart functionality.

Parameters:

• step (int) – The iteration number in the NEB optimization.

• optimizer (LBFGSOptimizer | FIREOptimizer) – The optimizer method object from the NEB optimization.

• previous_max_image (int) – Maximum image from the previous optimization step.

• previous_coordinates (array) – Coordinates of each NEB image in the previous optimization step.

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:

• calculator (Calculator | None) – The calculator that should be attached to the configuration.

• initial_state (MoleculeConfiguration | BulkConfiguration | DeviceConfiguration | SurfaceConfiguration with an attached calculator | None) – The initial state to be used for this configuration.
  Default: No initial state.

• initial_spin (InitialSpin | None) – The initial spin to be used for this configuration.
  Default: InitialSpin(), except when used with a calculator of type HuckelCalculator, SlaterKosterCalculator, SemiEmpiricalCalculator, DeviceHuckelCalculator, DeviceSlaterKosterCalculator, DeviceSemiEmpiricalCalculator. In this case InitialSpin([0., 0., ...]) is used, i.e. the scaled spins for each atom are set to 0.

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 | None) – The metatext string that should be set. A value of “None” can be given to remove the current metatext.

shiftAtoms(*args, **kwargs)

Shift atoms.

All arguments and keyword arguments are passed on.

split(image_indices=None)

Method to split the present NEB into multiple smaller NEBs.

Parameters:

image_indices (Sequence of type int) – The list of images to split at. Allowed are only values in the set of intermediate images (i.e, excluding the endpoints). The sequence is automatically sorted and duplicates are removed. The specified images become the endpoints of the new NEBs.
Default: Automatically determined by the additional minima found between the endpoints

Returns:

A list of split NEBs.

Return type:

Sequence of type NudgedElasticband

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(include_constraints=True)

Parameters:

include_constraints (bool) – If this object was generated by an NEB optimization with constraints, determine whether the output stresses should include constraint corrections or not.

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

totalDistance()

Returns:

The total distance from first to last image.

Return type:

PhysicalQuantity of type length

uniqueElements()

Returns:

The unique elements contained in the nudged elastic band.

Return type:

list of PeriodicTableElement

uniqueString()

Return a unique string representing the state of the object.

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:

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 [1][2].

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.

• See also OptimizeNudgedElasticBand()

[1]

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.

[2]

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.