pyneb package

Submodules

pyneb.fileio module

class pyneb.fileio.DPMLogger(classInst, logLevel=1, fName=None)

Bases: object

finalize(minPathDict, minIndsDict, distsDict, runTime, pathAsText=True)
log(previousIndsArr, distArr, updateRange)
class pyneb.fileio.DijkstraLogger(djkInst, logLevel=1, fName=None)

Bases: object

finalize(runTime, pathAsText=True)
log(variables, variableNames)
class pyneb.fileio.ForceLogger(classInst, logLevel, loggerSettings, fileExt)

Bases: object

flush()

Note that this must be called, as the self.log only writes the data in chunks. Any data falling outside of those chunks will be stored in self.logDict, but not written.

Parameters

  • variables (TYPE) – DESCRIPTION.

  • variableNames (TYPE) – DESCRIPTION.

Return type

None.

log(variablesDict)
write_early_stop_params(earlyStopParams)
write_fire_params(tStep, alpha, stepsSinceReset, fireParams)
write_runtime(runTime)
class pyneb.fileio.LoadDPMLogger(fName)

Bases: object

class pyneb.fileio.LoadDijkstraLogger(file)

Bases: object

class pyneb.fileio.LoadForceLog(file)

Bases: pyneb.fileio.LoadForceLogger

class pyneb.fileio.LoadForceLogger(file)

Bases: object

class pyneb.fileio.NDInterpLogger

Bases: object

class pyneb.fileio.VerletLogger(vltInst, logLevel)

Bases: object

pyneb.fileio.path_from_text(fName, returnHeads=False)
pyneb.fileio.path_to_text(path, fName, colHeads=None)

pyneb.solvers module

class pyneb.solvers.Dijkstra(initialPoint, coordMeshTuple, potArr, inertArr=None, target_func=<function TargetFunctions.action>, allowedEndpoints=None, trimVals=[0.0001, None], logLevel=1, fName=None)

Bases: object

Maintainer

Daniel

__init__(initialPoint, coordMeshTuple, potArr, inertArr=None, target_func=<function TargetFunctions.action>, allowedEndpoints=None, trimVals=[0.0001, None], logLevel=1, fName=None)

Some indexing is done to deal with the default shape of np.meshgrid. For D dimensions, the output is of shape (N2,N1,N3,…,ND), while the way indices are generated expects a shape of (N1,…,ND). So, I swap the first two indices by hand. See https://numpy.org/doc/stable/reference/generated/numpy.meshgrid.html #TODO: error handling (try getting an index)(?)

Note that indexing for Dijkstra internal functions are done in the order (N2,N1,N3,…), for simplicity. The indexing that is returned by self.__call__ is kept in this order by default.

Note that the value of the array at a certain index is the same regardless of the sort order of the indices, provided that the index order matches that used when creating np.meshgrid

Parameters

  • initialPoint (TYPE) – DESCRIPTION.

  • coordMeshTuple (TYPE) – DESCRIPTION.

  • potArr (TYPE) – DESCRIPTION.

  • inertArr (TYPE, optional) – DESCRIPTION. The default is None.

  • target_func (TYPE, optional) – DESCRIPTION. The default is action.

  • allowedEndpoints (TYPE, optional) – DESCRIPTION. The default is None.

  • trimVals (TYPE, optional) – DESCRIPTION. The default is [10**(-4),None].

Raises

ValueError – DESCRIPTION.

Return type

None.

minimum_endpoint(distanceDict)
class pyneb.solvers.DynamicProgramming(initialPoint, coordMeshTuple, potArr, inertArr=None, allowedMask=None, target_func=<function TargetFunctions.action>, allowedEndpoints=None, trimVals=[0.0001, None], logLevel=1, fName=None, logFreq=50)

Bases: object

__init__(initialPoint, coordMeshTuple, potArr, inertArr=None, allowedMask=None, target_func=<function TargetFunctions.action>, allowedEndpoints=None, trimVals=[0.0001, None], logLevel=1, fName=None, logFreq=50)
class pyneb.solvers.EulerLagrangeSolver(initialPath, eneg_func, mass_func=None, grad_approx=<function midpoint_grad>)

Bases: object

Maintainer

Daniel

__init__(initialPath, eneg_func, mass_func=None, grad_approx=<function midpoint_grad>)
solve()
class pyneb.solvers.EulerLagrangeVerifier(path, eneg_func, mass_func=None, grad_approx=<function midpoint_grad>)

Bases: object

Maintainer

Daniel

__init__(path, eneg_func, mass_func=None, grad_approx=<function midpoint_grad>)
Parameters

  • path (TYPE) – DESCRIPTION.

  • eneg_func (TYPE) – DESCRIPTION.

  • mass_func (TYPE, optional) – DESCRIPTION. The default is None.

  • grad_approx (Function, optional) – For computing gradients of the potential and inertia tensor. The default is midpoint_grad.

Raises

TypeError – DESCRIPTION.

Return type

None.

compare_lagrangian(nPts)
compare_lagrangian_squared()
class pyneb.solvers.LeastActionPath(potential, nPts, nDims, mass=None, endpointSpringForce=True, endpointHarmonicForce=True, target_func=<function TargetFunctions.action>, target_func_grad=<bound method GradientApproximations.forward_action_grad of <utilities.GradientApproximations object>>, nebParams={}, logLevel=1, loggerSettings={})

Bases: object

Computes the net force on a band, when minimizing an action-type functional, of the form

$$ S = int_{s_0}^{s_1} sqrt{2 M_{ij}dot{x}_idot{x}_j E(x(s))} ds. $$

Can be generalized to functionals of the form

$$ S = int_{s_0}^{s_1} f(s) ds $$

by choosing target_func differently. A common example is minimizing

$$ S = int_{s_0}^{s_1} M_{ij}dot{x}_idot{x}_j E(x(s)) ds, $$

with no square root inside of the integral.

potential

Evaluates the energy along the path

Type

function

nPts

The number of images in the path (path.shape[0])

Type

int

nDims

The number of coordinates (path.shape[1])

Type

int

mass

Evaluates the metric tensor M_{ij} along the path. The default is None, in which case M_{ij} is treated as the identity matrix at all points

Type

function

endpointSpringForce

Whether to turn on the endpoint spring force. Can be controlled for both endpoints individually. If a list of bools, the elements correspond to the first and the last endpoint. If a single bool, is applied to both endpoints. The default is True.

Type

bool or list of bools

endpointHarmonicForce

The same as endpointSpringForce, except for the harmonic force term. Disabling both forces keeps an endpoint fixed. The default is True.

Type

bool or list of bools

target_func

The functional to be minimized. The default is utilities.TargetFunctions.action

Type

function

target_func_grad

The approximation of the gradient of target_func. The default is utilities.GradientApproximations().forward_action_grad

Type

function

logger

Controls logging of the methods in this class

Type

instance of fileio.ForceLogger

nebParams

Contains the spring and harmonic force strengths, and the energy the endpoints are constrained to. Maintained for compatibility with self.logger

Type

dict

k

The spring force parameter

Type

float

kappa

The harmonic force parameter

Type

float

constraintEneg

The energy the endpoints are constrained to

Type

float

compute_force(points)

Computes the net force at every point in points

__init__(potential, nPts, nDims, mass=None, endpointSpringForce=True, endpointHarmonicForce=True, target_func=<function TargetFunctions.action>, target_func_grad=<bound method GradientApproximations.forward_action_grad of <utilities.GradientApproximations object>>, nebParams={}, logLevel=1, loggerSettings={})
Parameters

  • potential (function) – Evaluates the energy along the path. To be called as potential(path). Is passed to “target_func”.

  • nPts (int) – The number of images in the path (path.shape[0])

  • nDims (int) – The number of coordinates (path.shape[1])

  • mass (function, optional) – Evaluates the metric tensor M_{ij} along the path. To be called as mass(path). Is passed to “target_func”.The default is None, in which case $M_{ij}$ is treated as the identity matrix at all points

  • endpointSpringForce (bool or list of bools, optional) – Whether to turn on the endpoint spring force. Can be controlled for both endpoints individually. If a list of bools, the elements correspond to the first and the last endpoint. If a single bool, is applied to both endpoints. The default is True.

  • endpointHarmonicForce (bool or list of bools, optional) – The same as endpointSpringForce, except for the harmonic force term. Disabling both forces keeps an endpoint fixed. The default is True.

  • target_func (function, optional) – The functional to be minimized. Should take as arguments (path, potential, mass). Should return (action, potentialAtPath, massesAtPath). The default is utilities.TargetFunctions.action

  • target_func_grad (function, optional) –

    The approximation of the gradient of target_func. Should take as arguments

    (path, potentialFunc, potentialOnPath, massFunc, massOnPath, target_func),

    where target_func is the action integral approximation. Should return (gradOfAction, gradOfPes). The default is utilities.GradientApproximations().forward_action_grad

  • nebParams (dict, optional) –

    Contains the spring force and the harmonic oscillator potential parameters, as well as the energy the endpoints are constrained to. The default is {}, in which case the parameters are

    {“k”:10,”kappa”:20,”constraintEneg”:0}

  • logLevel (int, optional) – Controls how much information is tracked. Level 0 turns off logging. See fileio.ForceLogger, or a .lap file, for documentation on other tracked information

  • loggerSettings (dict, optional) – See fileio.ForceLogger for documentation

compute_force(points)

Computes the net force along the path

Parameters

points (np.ndarray) – The path to evaluate the force along. Of shape (self.nPts,self.nDims)

Returns

netForce – The force at each image on the path. Of shape (self.nPts,self.nDims)

Return type

np.ndarray

class pyneb.solvers.MinimumEnergyPath(potential, nPts, nDims, endpointSpringForce=True, endpointHarmonicForce=True, auxFunc=None, target_func=<function TargetFunctions.mep_default>, target_func_grad=<function potential_central_grad>, nebParams={}, logLevel=1, loggerSettings={})

Bases: object

Maintainer

Eric

__init__(potential, nPts, nDims, endpointSpringForce=True, endpointHarmonicForce=True, auxFunc=None, target_func=<function TargetFunctions.mep_default>, target_func_grad=<function potential_central_grad>, nebParams={}, logLevel=1, loggerSettings={})
Parameters

  • potential (Function) – To be called as potential(path). This is the PES function. Is passed to “target_func”.

  • endpointSpringForce (Bool or tuple of bools) – If a single bool, behavior is applied to both endpoints. If is a tuple of bools, the first stands for the index 0 on the path; the second stands for the index -1 on the path. TODO: possibly allow for a complicated function that returns a bool?

  • nPts (Int) – Number of points on the band, including endpoints.

  • nDims (Int) – Number of dimensions of the collective coordinates. For instance, when working with (Q20,Q30), nDims = 2.

  • target_func (Function, optional) – The function to take the gradient of. Should take as arguments (path, potential, AuxFunc). AuxFunc is used to add an optional potential to modify the existing potential surface. This function should return (potentialAtPath,AuxFuncAtPath). If no Aux function is needed, input None for the argument and AuxFuncAtPath will be None. The default is the PES potential (ie it just evaluates the potential).

  • target_func_grad (Function, optional) – Approximate derivative of the target function evaluated at every point. Should take as arguments points,potential,auxFunc) where target_func is a potential target function . Should return (gradOfPes, gradOfAux). If auxFunc is None, gradOfAux returns None

  • nebParams (Dict, optional) – Keyword arguments for the nudged elastic band (NEB) method. Controls the spring force and the harmonic oscillator potential. Default parameters are controlled by a dictionary in the __init__ method. The default is {}.

Return type

None.

compute_force(points)
class pyneb.solvers.VerletMinimization(nebObj, initialPoints)

Bases: object

Iterative algorithms for minimizing the force along a path, e.g. the least action path, or a minimum energy path.

__init__(nebObj, initialPoints)
Parameters

  • nebObj (TYPE) – DESCRIPTION.

  • initialPoints (TYPE) – DESCRIPTION.

Raises

  • AttributeError – DESCRIPTION.

  • ValueError – DESCRIPTION.

Return type

None.

fire(tStep, maxIters, fireParams={}, useLocal=True, earlyStop=True, earlyStopParams={}, earlyAbort=False, earlyAbortParams={})

Wrapper for fast inertial relaxation engine. FIRE step taken from http://dx.doi.org/10.1103/PhysRevLett.97.170201

Velocity update taken from https://en.wikipedia.org/wiki/Verlet_integration#Velocity_Verlet

TODO: consider making FIRE its own class, or allowing for attributes like fireParams and etc TODO: add maxmove parameter to prevent path exploding

Parameters

  • tStep (TYPE) – DESCRIPTION.

  • maxIters (TYPE) – DESCRIPTION.

  • fireParams (TYPE, optional) – DESCRIPTION. The default is {}.

  • useLocal (TYPE, optional) – DESCRIPTION. The default is False.

Raises

ValueError – DESCRIPTION.

Return type

None.

fire2(tStep, maxIters, fireParams={}, useLocal=False, earlyStop=False, earlyStopParams={})

Wrapper for fast inertial relaxation engine 2. FIRE step taken from http://dx.doi.org/10.1103/PhysRevLett.97.170201

Velocity update taken from https://en.wikipedia.org/wiki/Verlet_integration#Velocity_Verlet

Parameters

  • tStep (TYPE) – DESCRIPTION.

  • maxIters (TYPE) – DESCRIPTION.

  • fireParams (TYPE, optional) – DESCRIPTION. The default is {}.

  • useLocal (TYPE, optional) – DESCRIPTION. The default is False.

Raises

ValueError – DESCRIPTION.

Return type

None.

velocity_verlet(tStep, maxIters, dampingParameter=0)

Implements Algorithm 6 of https://doi.org/10.1021/acs.jctc.7b00360 with optional damping force.

TODO: that paper has many errors, esp. off-by-one errors. Could lead to issues. Consult http://dx.doi.org/10.1063/1.2841941 instead.

Parameters

  • tStep (TYPE) – DESCRIPTION.

  • maxIters (TYPE) – DESCRIPTION.

  • dampingParameter (TYPE, optional) – DESCRIPTION. The default is 0.

Returns

  • allPts (TYPE) – DESCRIPTION.

  • allVelocities (TYPE) – DESCRIPTION.

  • allForces (TYPE) – DESCRIPTION.

pyneb.utilities module

class pyneb.utilities.GradientApproximations

Bases: object

__init__()

When calling a method of GradientApproximations, we always supply a target_func, such as TargetFunctions.action. However, sometimes we only want the gradient wrt one term in the sum that makes up target_func. So, we map target_func to a function that evaluates exactly one component in the sum. This mapping is defined here.

Returns

  • None.

  • Maintainer: Daniel

discrete_action_grad(path, potential, potentialOnPath, mass, massOnPath, target_func)

Performs discretized action gradient, needs numerical PES still

Maintainer

Kyle

discrete_action_grad_const(path, potential, potentialOnPath, mass, massOnPath, target_func)

Performs discretized action gradient, needs numerical PES still

Maintainer

Kyle

discrete_element(mass, path, gradOfPes, dr, drp1, beff, beffp1, beffm1, pot, potp1, potm1)
Parameters

  • mass (function) – Callable mass function

  • path (float) – Point i

  • gradOfPes (float array) – Gradient of PES at point i

  • dr (float array) – dr = r_i - r_i-1

  • drp1 (float array) – drp1 = r_i+1 - r_i

  • beff (float) – Effective mass at point i

  • beffp1 (float) – Effective mass at point i+1

  • beffm1 (float) – Effective mass at point i-1

  • pot (float) – Potential at point i.

  • potp1 (float) – Potential at point i+1

  • potm1 (float) – Potential at point i-1

Returns

  • gradOfAction (float array) – Gradient of action at point i

  • Maintainer: Kyle

discrete_sqr_action_grad(path, potential, potentialOnPath, mass, massOnPath, target_func)

Performs discretized action gradient, needs numerical PES still

Maintainer

Kyle

discrete_sqr_action_grad_mp(path, potential, potentialOnPath, mass, massOnPath, target_func)

Performs discretized action gradient, needs numerical PES still

Maintainer

Kyle

forward_action_component_grad(path, potential, potentialOnPath, mass, massOnPath, target_func)

Requires an approximation of the action that just sums up values along the path, such as TargetFunctions.action. Then, this computes the forwards finite difference approximation of every term in the sum.

Note the difference with GradientApproximations().forward_action_grad: there, the full action is computed for every step. Here, only the component at that step is computed.

Does not return the gradient of the mass function, as that’s not used elsewhere.

Parameters

  • path (ndarray) – The path. Of shape (nPoints,nDims)

  • potential (function.) – Must take as input an array of shape path.shape

  • potentialOnPath (ndarray) – Potential on the path. Of shape (nPoints,).

  • mass (function or None) –

  • massOnPath (ndarray or None) – Mass on path. If not None, of shape (nPoints,nDims,nDims).

  • target_func (function) – Any term in TargetFunctions that is the sum of some constituent terms (e.g. TargetFunctions.action). Uses target_func.__name__ to select the gradient of a term in the sum, such as TargetFunctions.term_in_action_sum

Returns

  • gradOfAction (ndarray)

  • gradOfPes (ndarray)

  • Maintainer: Daniel

forward_action_grad(path, potential, potentialOnPath, mass, massOnPath, target_func)

Takes forwards finite difference approx of any action-like function. See e.g. TargetFunctions.action. Note that the full action is computed at every finite difference step.

Does not return the gradient of the mass function, as that’s not used elsewhere.

Parameters

  • path (ndarray) – The path. Of shape (nPoints,nDims)

  • potential – As allowed in TargetFunctions.action

  • potentialOnPath (ndarray) – Potential on the path. Of shape (nPoints,).

  • mass – As allowed in TargetFunctions.action

  • massOnPath (ndarray or None) – Mass on path. If not None, of shape (nPoints,nDims,nDims).

  • target_func (function) – Function whose gradient is being computed

Returns

  • gradOfAction (ndarray)

  • gradOfPes (ndarray)

  • Maintainer: Daniel

class pyneb.utilities.InterpolatedPath(discretePath, kwargs={})

Bases: object

Maintainer

Daniel

__init__(discretePath, kwargs={})

Note that when one considers a 1D curve embedded in 2D, e.g. in a plot of a function, one should specify ‘u’ in kwargs. Otherwise, ‘u’ will be computed based on the distance between points on the path, which will generally lead to a different plot than what is desired.

Parameters

  • discretePath (TYPE) – DESCRIPTION.

  • kwargs (TYPE, optional) – DESCRIPTION. The default is {}.

Return type

None.

compute_along_path(target_func, nImages, tfArgs=[], tfKWargs={})
class pyneb.utilities.NDInterpWithBoundary(gridPoints, gridVals, boundaryHandler='exponential', symmExtend=None, transformFuncName='identity', splKWargs={})

Bases: object

Interpolates a grid in D dimensions, with extra handling for points outside of the grid. The D>2 case is based on scipy.interpolate.RegularGridInterpolator

Maintainer

Daniel

__init__(gridPoints, gridVals, boundaryHandler='exponential', symmExtend=None, transformFuncName='identity', splKWargs={})

Initializes the class instance. Carries out basic error checking on inputs. Defines self._call as the method to evaluate a point that’s within the grid boundaries. It is also used in the boundary handlers, to evaluate e.g. the nearest allowed point once it is found.

Parameters

  • gridPoints (tuple of ndarrays) – The unique grid points. Each array must be sorted in ascending order.

  • gridVals (ndarray) – The grid values to be interpolated. Expected to be of shape (N2,N1,N3,…), as in the output of np.meshgrid.

  • boundaryHandler (str, optional) – How points outside of the interpolation region are handled. The default is ‘exponential’.

  • symmExtend (bool or ndarray of bools, optional) – Whether to symmetrically extend gridVals when evaluating. See notes. The default is None.

  • transformFuncName (string, optional) – The function to apply to the interpolated function after interpolating. The default is “identity”, in which no post-processing is applied.

  • splKWargs (dict, optional) – Extra arguments for spline interpolation, in the 2D case. The default is {}.

Return type

None.

Notes

The boundary handler is assumed to be the same for all dimensions, because I can’t think of a reasonable way to allow for different handling for different dimensions. I also see no reason why one would want to treat the dimensions differently.

Our use case is density functional theory, and our grid points are the multipole moments Qi in a constrained DFT calculation. It does not always make sense to symmetrically extend a potential energy surface: for Q30, it does, while for Q20, it does not. It also does not make sense to symmetrically extend the PES at the maximum value. So, symmExtend by default assumes Q30 is the second coordinate, and should only be extended symmetrically near Q30 = 0; otherwise, everything else is not extended at all.

Also assumes for symmetric extension that the lowest value is 0.

class pyneb.utilities.PositiveSemidefInterpolator(gridPoints, listOfVals, ndInterpKWargs={})

Bases: object

__init__(gridPoints, listOfVals, ndInterpKWargs={})
Parameters

  • gridPoints (tuple) –

    Elements are the unique coordinates of the grid. Shapes are

    (N1,N2,…,Nn).

  • listOfVals (list) –

    A positive semidefinite matrix M has unique values
    M = [[M00, M01, …, M0n],

    [M01, M11, …, M1n], …, [M0n, M1n, …, Mnn]].

    The components of listOfVals are the numpy arrays

    [M00, M01, …, M0n, M11, M12, …, M1n, …, Mnn].

    Each Mij is of shape (N2,N1,N3,…), as in the output of np.meshgrid.

  • ndInterpKWargs (TYPE, optional) – DESCRIPTION. The default is {}.

Return type

None.

class pyneb.utilities.SurfaceUtils

Bases: object

Defined for namespace purposes

Maintainer

Daniel

find_all_local_maximum()

Returns the indices corresponding to the local maximum values. Taken originally from https://stackoverflow.com/a/3986876

Finder checks along the cardinal directions. If all neighbors in those directions are greater than or equal to the current value, the index is returned as a minimum. For the border, the array is reflected about the axis. As a result, many indices are found that are not technically local minima. However, we do want the border results - in practice, nuclei often have a ground state at zero deformation in one collective coordinate; to find that, we must include the border indices.

Parameters

arr (Numpy array) – A D-dimensional array.

Returns

maxIndsOut – D arrays of length k, for k maxima found

Return type

Tuple of numpy arrays

static find_all_local_minimum(arr)

Returns the indices corresponding to the local minimum values. Taken originally from https://stackoverflow.com/a/3986876

Finder checks along the cardinal directions. If all neighbors in those directions are greater than or equal to the current value, the index is returned as a minimum. For the border, the array is reflected about the axis. As a result, many indices are found that are not technically local minima. However, we do want the border results - in practice, nuclei often have a ground state at zero deformation in one collective coordinate; to find that, we must include the border indices. To exclude them, one can then call SurfaceUtils.find_local_minimum.

Parameters

arr (Numpy array) – A D-dimensional array.

Returns

minIndsOut – D arrays of length k, for k minima found

Return type

Tuple of numpy arrays

static find_approximate_contours(coordMeshTuple, zz, eneg=0, show=False)

Finds 2D contours on a D-dimensional surface. Does so by considering 2D surfaces, using the first 2 indices of zz, and iterating over all other indices. At every set of indices, pyplot.contour is called, to get the 2D contour(s) on the surface at that level. The contours are not filled with the value of the coordinates with the other indices - i.e. each segment is of shape (k,2), regardless of the number of dimensions.

Parameters

  • coordMeshTuple (tuple of ndarray) – Coordinate mesh, e.g. output of np.meshgrid

  • zz (ndarray) – Potential on mesh

  • eneg (float, optional) – Energy of the desired contour. The default is 0.

  • show (bool, optional) – Whether to plot the contours. The default is False.

Raises

NotImplementedError – Does not work for 1 dimension.

Returns

allContours – Each element is the returned value of ax.contour.allsegs[0], i.e. a list consisting of 2D arrays describing the contour on that slize of zz

Return type

ndarray of lists

static find_endpoints_on_grid(coordMeshTuple, potArr, returnAllPoints=False, eneg=0, returnIndices=False)
Parameters

returnAllPoints (TYPE, optional) – DESCRIPTION. The default is False.

Returns

  • allowedEndpoints (TYPE) – DESCRIPTION.

  • allowedIndices (TYPE)

find_local_minimum(searchPerc=[0.25, 0.25], returnOnlySmallest=True)

Returns the indices corresponding to the local minimum values within a desired part of the PES.

Parameters

  • arr (Numpy array) – A D-dimensional array.

  • searchPerc (List) – Percentage of each coordinate that the minimum is allowed to be in. See Notes for a note on searchPerc

  • returnOnlySmallest (Bool. Default is True) – If True, returns only the (first) smallest value. If False, returns all minima in the searched region.

Returns

minIndsOut – D arrays of length k, for k minima found in the region. If returnOnlySmallest, returns a tuple, not a tuple of arrays

Return type

Tuple of numpy arrays

Notes

Note that, if we write searchPerc=[s1,s2], then s1 is the range for the first coordinate of arr. If arr was constructed to agree with np.meshgrid’s default indexing, then s1 will actually restrict the range of the second (physical) coordinate: np.meshgrid(X,Y,Z,…) returns arrays of shape (Y.len,X.len,Z.len,…)

static round_points_to_grid(coordMeshTuple, ptsArr)

Rounds an array of points to the nearest point on a grid.

Parameters

  • coordMeshTuple (tuple of ndarrays) – The grid. Taken as output of np.meshgrid

  • ptsArr (ndarray) – The points to round. Of shape (nPoints,nDims), where nDims is the number of coordinates.

Returns

  • indsOut (ndarray of ints) – The indices of the points. Of shape (nPoints,nDims). See notes.

  • gridValsOut (ndarray) – The nearest grid values. Of shape (nPoints,nDims).

Notes

Has standard complication from np.meshgrid - indexing is (N2,N1,N3,…), when the coordinates have lengths (N1,N2,N3,…). This returns the default indexing of np.meshgrid for coordMeshTuple. See e.g. https://numpy.org/doc/stable/reference/generated/numpy.meshgrid.html

class pyneb.utilities.TargetFunctions

Bases: object

static action(path, potential, masses=None)

TODO: docs Allowed masses:

-Constant mass; set masses = None -Array of values; set masses to a numpy array of shape (nPoints, nDims, nDims) -A function; set masses to a function

Allowed potential:

-Array of values; set potential to a numpy array of shape (nPoints,) -A function; set masses to a function

Computes action as

$ S = sum_{i=1}^{nPoints} sqrt{2 E(x_i) M_{ab}(x_i) (x_i-x_{i-1})^a(x_i-x_{i-1})^b} $

Maintainer

Daniel

static action_squared(path, potential, masses=None)
Parameters

  • path (ndarray) – np.ndarray of shape (Nimgs,nDim) containing postions of all images.

  • potential (object or ndarray) – Allowed potential: -Array of values; set potential to a numpy array of shape (nPoints,) -A function; set masses to a function

  • masses (object or ndarray, Optional) – Allowed masses: -Constant mass; set masses = None -Array of values; set masses to a numpy array of shape (nPoints, nDims, nDims) -A function; set masses to a function

Raises

ValueError – DESCRIPTION.

Returns

  • actOut (float)

  • potArr (ndarray) – ndarray of shape (Nimgs,1) containing the PES values for each image in path

  • massArr (ndarray) – ndarray of shape (Nimgs,nDim,nDim) containing the mass tensors for each image in path.

  • Maintainer: Eric

static mep_default(points, potential, auxFunc=None)

Essentially a wrapper function for the potential. Expected points to be a (nPts,nDim) matrix. Potential should be a function capable of returning a (nPts,nDim) matrix.

Parameters

  • points (TYPE) – DESCRIPTION.

  • potential (TYPE) – DESCRIPTION.

  • auxFunc (TYPE, optional) – DESCRIPTION. The default is None.

Raises

ValueError – DESCRIPTION.

Returns

  • energies (TYPE) – DESCRIPTION.

  • auxEnergies (TYPE) – DESCRIPTION.

  • Maintainer: Eric

static term_in_action_squared_sum(points, potential, masses=None)

TODO: docs Allowed masses:

-Constant mass; set masses = None -Array of values; set masses to a numpy array of shape (nPoints, nDims, nDims) -A function; set masses to a function

Allowed potential:

-Array of values; set potential to a numpy array of shape (nPoints,) -A function; set masses to a function

Computes action as

$ S = sum_{i=1}^{nPoints} sqrt{2 E(x_i) M_{ab}(x_i) (x_i-x_{i-1})^a(x_i-x_{i-1})^b} $

Maintainer

Daniel

static term_in_action_sum(points, potential, masses=None)

TODO: docs Allowed masses:

-Constant mass; set masses = None -Array of values; set masses to a numpy array of shape (nPoints, nDims, nDims) -A function; set masses to a function

Allowed potential:

-Array of values; set potential to a numpy array of shape (nPoints,) -A function; set masses to a function

Computes action as

$ S = sum_{i=1}^{nPoints} sqrt{2 E(x_i) M_{ab}(x_i) (x_i-x_{i-1})^a(x_i-x_{i-1})^b} $

Maintainer

Daniel

pyneb.utilities.beff_grad(func, points, dr, eps=1e-08)

Midpoint finite difference of B_eff mass.

Maintainer

Kyle

pyneb.utilities.get_crit_pnts(V_func, path, method='central')

WARNING: This function depends on a package called autograd for hessian calculation When using this function, you need to import numpy using: import autograd.numpy as np

This function finds the critical the MEP path must pass through by first finding the critical points of the potential function evaluated along the curve and then classifies using the eigenvalues of the Hessian. Returns minima, maxima, and saddle points indices along the path.

Parameters

  • V_func (object) – Energy Function that must have shape (nImgs,nDims).

  • path (ndarray) – coordinates of the path on the surface with shape (nImgs,nDims).

  • method (string) – differentiation method option for numdifftools. Options are ‘central’, ‘complex’, ‘multicomplex’, ‘forward’, ‘backward’. See https://numdifftools.readthedocs.io/en/latest/reference

Return type

3 arrays containing the indices of minima, maxima, and saddle points.

pyneb.utilities.mass_funcs_to_array_func(dictOfFuncs, uniqueKeys)

Formats a collection of functions for use in computing the inertia tensor. Assumes the inertia tensor is symmetric.

Parameters

  • dictOfFuncs (dict) – Contains functions for each component of the inertia tensor

  • uniqueKeys (list) –

    Labels the unique coordinates of the inertia tensor, in the order they are used in the inertia. For instance, if one uses (q20, q30) as the coordinates in this order, one should feed in [‘20’,’30’], and the inertia will be reshaped as

    [[M_{20,20}, M_{20,30}]

    [M_{30,20}, M_{30,30}]].

    Contrast this with feeding in [‘30’,’20’], in which the inertia will be reshaped as

    [[M_{30,30}, M_{30,20}]

    [M_{20,30}, M_{20,20}]].

Returns

  • func_out (function) – The inertia tensor. Can be called as func_out(coords).

  • Maintainer: Daniel

pyneb.utilities.midpoint_grad(func, points, eps=1e-08)

TODO: allow for arbitrary shaped outputs, for use with inertia tensor TODO: maybe only have one gradient approx ever

Midpoint finite difference. Probably best if not used with actual DFT calculations,

vs a forwards/reverse finite difference

Assumes func only depends on a single point (vs the action, which depends on

all of the points)

Maintainer

Eric

pyneb.utilities.potential_central_grad(points, potential, auxFunc=None)

Used in MEP for force updates. There, one only needs the gradient of the PES.

Parameters

  • points (TYPE) – DESCRIPTION.

  • potential (TYPE) – DESCRIPTION.

  • auxFunc (TYPE, optional) – DESCRIPTION. The default is None.

Returns

  • gradPES (TYPE) – DESCRIPTION.

  • gradAux (TYPE) – DESCRIPTION.

  • Maintainer: Eric

pyneb.utilities.shift_func(func_in, shift=0.0001)

Shifts func_in output down by shift. Especially for use with interpolators where the minimum of the interpolator may be a bit lower than the minimum of the array.

Parameters

  • func_in (function) –

  • shift (float) – The amount to shift by. The default is 10**(-4).

Returns

  • func_out (function) – The shifted function

  • Maintainer: Daniel

Module contents