pymatgen.analysis.diffusion.neb.pathfinder module

Algorithms for NEB migration path analysis.

class ChgcarPotential(chgcar, smear=False, normalize=True)

Bases: StaticPotential

Implements a potential field based on the charge density output from VASP.

Parameters:

• chgcar – Chgcar object based on a VASP run of the structure of interest (Chgcar.from_file(“CHGCAR”))

• smear – Whether or not to apply a Gaussian smearing to the potential

• normalize – Whether or not to normalize the potential to range from 0 to 1

class DistinctPathFinder(structure, migrating_specie, max_path_length=None, symprec=0.1, perc_mode='>1d')

Bases: object

Determines symmetrically distinct paths between existing sites. The path info can then be used to set up either vacancy or interstitial diffusion (assuming site positions are known). Note that this works mainly for atomic mechanism, and does not work for correlated migration.

Parameters:

• structure – Input structure that contains all sites.

• migrating_specie (Specie-like) – The specie that migrates. E.g., “Li”.

• max_path_length (float) – Maximum length of NEB path in the unit of Angstrom. Defaults to None, which means you are setting the value to the min cutoff until finding 1D or >1D percolating paths.

• symprec (float) – Symmetry precision to determine equivalence.

• perc_mode (str) – The percolating type. Default to “>1d”, because usually it is used to find possible NEB paths to form percolating networks. If you just want to check the min 1D percolation, set it to “1d”.

get_paths()

Returns:

[MigrationHop] All distinct migration paths.

write_all_paths(fname, nimages=5, **kwargs)

Write a file containing all paths, using hydrogen as a placeholder for the images. H is chosen as it is the smallest atom. This is extremely useful for path visualization in a standard software like VESTA.

Parameters:

• fname (str) – Filename

• nimages (int) – Number of images per path.

• **kwargs – Passthrough kwargs to path.get_structures.

class FreeVolumePotential(struct, dim, smear=False, normalize=True)

Bases: StaticPotential

Implements a potential field based on geometric distances from atoms in the structure - basically, the potential is lower at points farther away from any atoms in the structure.

Parameters:

• struct – Unit cell on which to base the potential

• dim – Grid size for the potential

• smear – Whether or not to apply a Gaussian smearing to the potential

• normalize – Whether or not to normalize the potential to range from 0 to 1

class IDPPSolver(structures)

Bases: object

A solver using image dependent pair potential (IDPP) algo to get an improved initial NEB path. For more details about this algo, please refer to Smidstrup et al., J. Chem. Phys. 140, 214106 (2014).

Initialization.

Parameters:

structures (list of pmg_structure) – Initial guess of the NEB path (including initial and final end-point structures).

classmethod from_endpoints(endpoints, nimages: int = 5, sort_tol: float = 1.0, interpolate_lattices: bool = False)

A class method that starts with end-point structures instead. The initial guess for the IDPP algo is then constructed using linear interpolation.

Parameters:

• endpoints (list of Structure objects) – The two end-point structures.

• nimages (int) – Number of images between the two end-points.

• sort_tol (float) – Distance tolerance (in Angstrom) used to match the atomic indices between start and end structures. Need to increase the value in some cases.

• interpolate_lattices (bool) – Whether to interpolate lattices between the start and end structures.

static get_unit_vector(vec)

Calculate the unit vector of a vector.

Parameters:

vec – Vector.

run(maxiter=1000, tol=1e-05, gtol=0.001, step_size=0.05, max_disp=0.05, spring_const=5.0, species=None)

Perform iterative minimization of the set of objective functions in an NEB-like manner. In each iteration, the total force matrix for each image is constructed, which comprises both the spring forces and true forces. For more details about the NEB approach, please see the references, e.g. Henkelman et al., J. Chem. Phys. 113, 9901 (2000).

Parameters:

• maxiter (int) – Maximum number of iterations in the minimization process.

• tol (float) – Tolerance of the change of objective functions between consecutive steps.

• gtol (float) – Tolerance of maximum force component (absolute value).

• step_size (float) – Step size associated with the displacement of the atoms during the minimization process.

• max_disp (float) – Maximum allowed atomic displacement in each iteration.

• spring_const (float) – A virtual spring constant used in the NEB-like relaxation process that yields so-called IDPP path.

• species (list of string) – If provided, only those given species are allowed to move. The atomic positions of other species are obtained via regular linear interpolation approach.

Returns:

[Structure] Complete IDPP path (including end-point structures)

class MigrationHop(isite: Site, esite: Site, symm_structure: SymmetrizedStructure, host_symm_struct: SymmetrizedStructure = None, symprec: float = 0.001)

Bases: MSONable

A convenience container representing a migration path.

Parameters:

• isite – Initial site

• esite – End site

• symm_structure – SymmetrizedStructure

• host_symm_struct – SymmetrizedStructure of the host structure, used to for its spacegroup

• symprec – used to determine equivalence.

get_sc_structures(vac_mode: bool, min_atoms: int = 80, max_atoms: int = 240, min_length: float = 10.0, tol: float = 1e-05) → tuple[Structure, Structure, Structure]

Construct supercells that represents the start and end positions for migration analysis.

Parameters:

• vac_mode – If true simulate vacancy diffusion.

• max_atoms – Maximum number of atoms allowed in the supercell.

• min_atoms – Minimum number of atoms allowed in the supercell.

• min_length – Minimum length of the smallest supercell lattice vector.

• tol – toleranace for identifying isite/esite within base_struct

Returns:

Start, End, Base Structures.

If not vacancy mode, the base structure is just the host lattice. If in vacancy mode, the base structure is the fully intercalated structure

get_structures(nimages=5, vac_mode=True, idpp=False, **idpp_kwargs)

Generate structures for NEB calculation.

Parameters:

• nimages (int) – Defaults to 5. Number of NEB images. Total number of structures returned in nimages+2.

• vac_mode (bool) – Defaults to True. In vac_mode, a vacancy diffusion mechanism is assumed. The initial and end sites of the path are assumed to be the initial and ending positions of the vacancies. If vac_mode is False, an interstitial mechanism is assumed. The initial and ending positions are assumed to be the initial and ending positions of the interstitial, and all other sites of the same specie are removed. E.g., if NEBPaths were obtained using a Li4Fe4P4O16 structure, vac_mode=True would generate structures with formula Li3Fe4P4O16, while vac_mode=False would generate structures with formula LiFe4P4O16.

• idpp (bool) – Defaults to False. If True, the generated structures will be run through the IDPPSolver to generate a better guess for the minimum energy path.

• **idpp_kwargs – Passthrough kwargs for the IDPPSolver.run.

Returns:

[Structure] Note that the first site of each structure is always the migrating ion. This makes it easier to perform subsequent analysis.

property length

Returns: (float) Length of migration path.

write_path(fname, **kwargs)

Write the path to a file for easy viewing.

Parameters:

• fname (str) – File name.

• **kwargs – Kwargs supported by NEBPath.get_structures.

class MixedPotential(potentials, coefficients, smear=False, normalize=True)

Bases: StaticPotential

Implements a potential that is a weighted sum of some other potentials.

Parameters:

• potentials – List of objects extending the StaticPotential superclass

• coefficients – Mixing weights for the elements of the potentials list

• smear – Whether or not to apply a Gaussian smearing to the potential

• normalize – Whether or not to normalize the potential to range from 0 to 1.

class NEBPathfinder(start_struct, end_struct, relax_sites, v, n_images=20, mid_struct=None)

Bases: object

General pathfinder for interpolating between two structures, where the interpolating path is calculated with the elastic band method with respect to the given static potential for sites whose indices are given in relax_sites, and is linear otherwise.

If you use PathFinder algorithm for your research, please consider citing the following work:

Ziqin Rong, Daniil Kitchaev, Pieremanuele Canepa, Wenxuan Huang, Gerbrand
Ceder, The Journal of Chemical Physics 145 (7), 074112

Parameters:

• start_struct – Starting structure

• end_struct – End structure to interpolate

• relax_sites – List of site indices whose interpolation paths should be relaxed

• v – Static potential field to use for the elastic band relaxation

• n_images – Number of interpolation images to generate

• mid_struct – (optional) additional structure between the start and end structures to help.

property images

Returns a list of structures interpolating between the start and endpoint structures.

interpolate()

Finds a set of n_images from self.s1 to self.s2, where all sites except for the ones given in relax_sites, the interpolation is linear (as in pymatgen.core.structure.interpolate), and for the site indices given in relax_sites, the path is relaxed by the elastic band method within the static potential V.

If a mid point is defined we will interpolate from s1–> mid –>s2 The final number of images will still be n_images.

plot_images(outfile)

Generates a POSCAR with the calculated diffusion path with respect to the first endpoint.

Parameters:

outfile – Output file for the POSCAR.

static string_relax(start, end, V, n_images=25, dr=None, h=3.0, k=0.17, min_iter=100, max_iter=10000, max_tol=5e-06)

Implements path relaxation via the elastic band method. In general, the method is to define a path by a set of points (images) connected with bands with some elasticity constant k. The images then relax along the forces found in the potential field V, counterbalanced by the elastic response of the elastic band. In general the endpoints of the band can be allowed to relax also to their local minima, but in this calculation they are kept fixed.

Parameters:

• start – Starting point of the path calculation given in discrete coordinates with respect to the grid in V.

• end – Endpoints of the path calculation.

• V – potential field through which to calculate the path

• n_images – number of images used to define the path. In general anywhere from 20 to 40 seems to be good.

• dr – Conversion ratio from discrete coordinates to real coordinates for each of the three coordinate vectors

• h – Step size for the relaxation. h = 0.1 works reliably, but is slow. h=10 diverges with large gradients but for the types of gradients seen in CHGCARs, works pretty reliably

• k – Elastic constant for the band (in real units, not discrete)

• min_iter – Minimum number of iterations to perform. Defaults to 100.

• max_iter – Number of optimization steps the string will take before exiting (even if unconverged). Defaults to 10000.

• max_tol – Convergence threshold such that if the string moves by less than max_tol in a step, and at least min_iter steps have passed, the algorithm will terminate. Depends strongly on the size of the gradients in V, but 5e-6 works reasonably well for CHGCARs.

class StaticPotential(struct, pot)

Bases: object

Defines a general static potential for diffusion calculations. Implements grid-rescaling and smearing for the potential grid. Also provides a function to normalize the potential from 0 to 1 (recommended).

Parameters:

• struct – atomic structure of the potential

• pot – volumentric data to be used as a potential

gaussian_smear(r)

Applies an isotropic Gaussian smear of width (standard deviation) r to the potential field. This is necessary to avoid finding paths through narrow minima or nodes that may exist in the field (although any potential or charge distribution generated from GGA should be relatively smooth anyway). The smearing obeys periodic boundary conditions at the edges of the cell.

:param r - Smearing width in Cartesian coordinates, in the same units

as the structure lattice vectors

get_v()

Returns the potential.

normalize()

Sets the potential range 0 to 1.

rescale_field(new_dim)

Changes the discretization of the potential field by linear interpolation. This is necessary if the potential field obtained from DFT is strangely skewed, or is too fine or coarse. Obeys periodic boundary conditions at the edges of the cell. Alternatively useful for mixing potentials that originally are on different grids.

Parameters:

new_dim – tuple giving the numpy shape of the new grid