atsim.potentials

A collection of classes and functions related to defining potentials

Package Contents

Classes

Potential(speciesA, speciesB, potentialFunction, h=1e-06) Class used to describe a potential to the writePotentials() function.
EAMPotential(species, atomicNumber, mass, embeddingFunction, electronDensityFunction, latticeConstant=0.0, latticeType=’fcc’) Class used to describe a particular species within EAM potential models.
SplinePotential(startPotential, endPotential, detachmentX, attachmentX) Callable to allow splining of one potential to another using an exponential spline
Multi_Range_Defn(range_type, start, potential_form, **kwargs)
TableReader(fileobject) Callable that allows pretabulated data to be used with a Potential object.

Functions

gradient(func, h=1e-06) Function wrapper that returns derivative of func.
num_deriv(r, func, h=1e-06) Returns numerical derivative of the callable func
deriv(r, func, h=1e-06) Evaluates the derivative of a unary callable, func at a value of r.
writeTABEAM(nrho, drho, nr, dr, eampots, pairpots, out=sys.stdout, title=’’) Create TABEAM file for use with the DL_POLY simulation code.
writeTABEAMFinnisSinclair(nrho, drho, nr, dr, eampots, pairpots, out=sys.stdout, title=’’) Create Exended EAM variant of DL_POLY TABEAM file.
writeFuncFL(nrho, drho, nr, dr, eampots, pairpots, out=sys.stdout, title=’’) Creates a DYNAMO funcfl formatted file suitable for use with lammps pair_style eam
writeSetFL(nrho, drho, nr, dr, eampots, pairpots, out=sys.stdout, comments=[‘’, ‘’, ‘’], cutoff=None) Creates EAM potential in the DYNAMO setfl format. This format is suitable for
writeSetFLFinnisSinclair(nrho, drho, nr, dr, eampots, pairpots, out=sys.stdout, comments=[‘’, ‘’, ‘’], cutoff=None) Creates Finnis-Sinclar EAM potential in the DYNAMO setfl format. The format should be used with the
potential(func) Decorator for callables that should be tagged as potential-forms or potential-functions
is_potential(obj) Identifies if an object is a potential-form or potential-function
buck4(A, rho, C, r_detach, r_min, r_attach) Returns a potential form describing the four-range Buckingham potential.
create_Multi_Range_Potential_Form(*range_tuples, **kwargs) Creates Multi_Range_Potential_Form or sub-class instance, from list of Multi_Range_Defn
plus(a, b) Takes two functions and returns a third which when evaluated returns the result of a(r) + b(r)
product(a, b) Takes two callables and returns a third which when evaluated returns the result of a(r) * b(r)
pow(a, b) Takes two callables and returns a third which when evaluated returns the result of a(r)**b(r)
plotToFile(fileobj, lowx, highx, func, steps=10000) Convenience function for plotting the potential functions contained herein.
plot(filename, lowx, highx, func, steps=10000) Convenience function for plotting the potential functions contained herein.
plotPotentialObject(filename, lowx, highx, potentialObject, steps=10000) Convenience function for plotting energy of pair interactions
plotPotentialObjectToFile(fileobj, lowx, highx, potentialObject, steps=10000) Convenience function for plotting energy of pair interactions
writePotentials(outputType, potentialList, cutoff, gridPoints, out=sys.stdout) Tabulates pair-potentials in formats suitable for multiple simulation codes.
class atsim.potentials.Potential(speciesA, speciesB, potentialFunction, h=1e-06)[source]

Bases: object

Class used to describe a potential to the writePotentials() function.

Potential objects encapsulate a python function or callable which is used by the energy() method to calculate potential energy.

The force() method returns \(\frac{-dU}{dr}\). If the energy callable provides .deriv() and .deriv2() methods these are used for evaluating the first and second derivatives of energy with respect to sepration. This allows analytical derivatives to be defined to the Potential object. When not defined, numerical derivatives are used instead.

The gradient() function is used to wrap the energy callable so that the correct derivative implementation is used.

speciesA
speciesB
potentialFunction
energy(self, r)
Parameters:r – Separation
Returns:Energy for given separation
force(self, r)

Calculate force for this potential at a given separation.

If this object’s potentialFunction has a .deriv() method this will be used to calculate force (allowing analytical derivatives to be specified).

If potentialFunction doesn’t have a deriv method then a numerical derivative of the potential function will be returned instead.

Parameters:r (float) – Separation
Returns:-dU/dr at given separation
Return type:float
class atsim.potentials.EAMPotential(species, atomicNumber, mass, embeddingFunction, electronDensityFunction, latticeConstant=0.0, latticeType='fcc')[source]

Bases: object

Class used to describe a particular species within EAM potential models.

This class is a container for the functions and attributes necesary for describing the many-body component of an Embedded Atom potential Model.

embeddingValue(self, density)

Method that returns energy for given electron density.

This method simply passes density to the callable stored in the embeddingFunction and returns its value.

Parameters:density (float) – Electron density.
Returns:Energy for given density (as given by self.embeddingFunction).
Return type:float
electronDensity(self, separation)

Gives the ‘electron’ density for an atom separated from current species by separation.

This is a pass-through method to callable stored in current instance’s electronDensityFunction attribute.

Parameters:separation (float.) – Separation (in angstroms) between atom represented by this object and another atom.
Returns:Contribution to electron density due to given pair separation.
Return type:float.
class atsim.potentials.SplinePotential(startPotential, endPotential, detachmentX, attachmentX)[source]

Bases: atsim.potentials.spline.Custom_SplinePotential

Callable to allow splining of one potential to another using an exponential spline

atsim.potentials.gradient(func, h=1e-06)[source]

Function wrapper that returns derivative of func.

If the callable, func provides a .deriv(r) method this will be used to evaluate the derivative of the function, if not the returned function will use num_deriv() in gradient evaluation.

If the callable additionally provides a .deriv2(r) method, representing its second derivative, the function returned by this routine will have a deriv() method which will delegate to func.deriv2() when called.

By providing .deriv() and .deriv2() on the func callable analytical descriptions of a potential’s first and second derivatives may be specified.

Parameters:
  • func – Function to be wrapped
  • h – Step size used when performing numerical differentiation
Returns:

Function that returns derivative of func
atsim.potentials.num_deriv(r, func, h=1e-06)[source]

Returns numerical derivative of the callable func

Parameters:
  • r – Value at which derivative of func should be evaluated.
  • func – Function whose gradient is to be evaluated.
  • h – Step size used when performing numerical differentiation.
Returns:

Numerical derivative of func at r.
atsim.potentials.deriv(r, func, h=1e-06)[source]

Evaluates the derivative of a unary callable, func at a value of r.

If the object func has a unary method deriv(r), this will be used to evauluate the derivative (allowing analytical derivatives to be used).

If func does not have a specific deriv(r) method then its numerical-derivative of will be taken by calling num_deriv()

Parameters:
  • r – Value at which derivative of func should be evaluated.
  • func – Function whose derivative is to be evaluated.
  • h – Step size used when performing numerical differentiation.
Returns:

Derivative of func at r.
atsim.potentials.writeTABEAM(nrho, drho, nr, dr, eampots, pairpots, out=sys.stdout, title='')[source]

Create TABEAM file for use with the DL_POLY simulation code.

See also

For a working example using this function see Example 2b: Tabulate Al-Cu Alloy Potentials Using writeTABEAM() for DL_POLY

Parameters:
  • nrho (int) – Number of entries in tabulated embedding functions
  • drho (float) – Step size between consecutive embedding function entries
  • nr (int) – Number of entries in tabulated pair potentials and density functions
  • dr (float) – Step size between entries in tabulated pair potentials and density functions
  • eampots – Potentials List of potentials.EAMPotential objects
  • pair – Potentials List of potentials.Potential objects
  • out (file object) – Python file object to which TABEAM data should be written
  • title (str) – Title of TABEAM file
atsim.potentials.writeTABEAMFinnisSinclair(nrho, drho, nr, dr, eampots, pairpots, out=sys.stdout, title='')[source]

Create Exended EAM variant of DL_POLY TABEAM file.

The EAMPotential instances within the eampots list are expected to provide individual density functions for each species pair in the species being tabulated. See __init__() for how these are specified to the EAMPotential constructor.

Note

The Extended EAM variant for which this function creates TABEAM files (i.e. metal potential type = eeam) is only supported in DL_POLY versions >= 4.05.

See also

For a working example using this function see Example 3b: Tabulate Al-Fe Finnis-Sinclair Potentials Using writeTABEAMFinnisSinclair() for DL_POLY

Parameters:
  • nrho (int) – Number of entries in tabulated embedding functions
  • drho (float) – Step size between consecutive embedding function entries
  • nr (int) – Number of entries in tabulated pair potentials and density functions
  • dr (float) – Step size between entries in tabulated pair potentials and density functions
  • eampots – Potentials List of atsim.potentials.EAMPotential objects
  • pairpots (list) – Potentials List of atsim.potentials.Potential objects
  • out (file object) – Python file object to which TABEAM data should be written
  • title (str) – Title of TABEAM file
atsim.potentials.writeFuncFL(nrho, drho, nr, dr, eampots, pairpots, out=sys.stdout, title='')[source]

Creates a DYNAMO funcfl formatted file suitable for use with lammps pair_style eam potential form. For the pair_style eam/alloy see writeSetFL().

See also

For a working example using this function see Example 1: Using writeFuncFL() to Tabulate Ag Potential for LAMMPS

Parameters:
  • nrho (int) – Number of points used to describe embedding function
  • drho (float) – Step size between rho values used to describe embedding function
  • nr (int) – Number of points used for the pair-potential, and density functions
  • dr (float) – Step size between r values in effective charge and density functions
  • eampots (list) – List containing a single EAMPotential instance for species to be tabulated.
  • pairpots (list) – List containing a single PairPotential instance for the X-X interaction (where X is the species represented by EAMPotential in eampots list)
  • out (file object) – Python file object to which eam table file will be written
  • title (str) – Title to be written as table file header
atsim.potentials.writeSetFL(nrho, drho, nr, dr, eampots, pairpots, out=sys.stdout, comments=['', '', ''], cutoff=None)[source]

Creates EAM potential in the DYNAMO setfl format. This format is suitable for use with the LAMMPS pair_style eam/alloy.

See also

For a working example using this function see Example 2a: Tabulate Al-Cu Alloy Potentials Using writeSetFL() for LAMMPS

Parameters:
  • nrho (int) – Number of points used to describe embedding function
  • drho (float) – Increment used when tabulating embedding function
  • nr (int) – Number of points used to describe density and pair potentials
  • dr (float) – Separation increment used when tabulating density function and pair potentials
  • eampots (list) – Instances of lammps.writeEAMTable.EAMPotential() which encapsulate information about each species
  • pairpots (list) – Instance of potentials.Potential, these describe repulsive pair potential component of EAM potential
  • out (file object) – Python file object into which EAM potential data should be written
  • comments (list) – List containing three strings, these form the header of the created file
  • cutoff (float) – Pair potential and density cutoff, if None then value of nr * dr is used.
atsim.potentials.writeSetFLFinnisSinclair(nrho, drho, nr, dr, eampots, pairpots, out=sys.stdout, comments=['', '', ''], cutoff=None)[source]

Creates Finnis-Sinclar EAM potential in the DYNAMO setfl format. The format should be used with the LAMMPS eam/fs pair_style.

The EAMPotential instances within the eampots list are expected to provide individual density functions for each species pair in the species being tabulated. See atsim.potentials.EAMPotential.__init__() for how these are specified to the atsim.potentials.EAMPotential constructor.

See also

For a working example using this function see Example 3a: Tabulate Al-Fe Finnis-Sinclair Potentials Using writeSetFLFinnisSinclair() for LAMMPS

Parameters:
  • nrho (int) – Number of points used to describe embedding function
  • drho (float) – Increment used when tabulating embedding function
  • nr (int) – Number of points used to describe density and pair potentials
  • dr (float) – Separation increment used when tabulating density function and pair potentials
  • eampots (list) – Instances of lammps.writeEAMTable.EAMPotential() which encapsulate information about each species
  • pairpots (list) – Instance of potentials.Potential, these describe repulsive pair potential component of EAM potential
  • out (file object) – Python file object into which EAM potential data should be written
  • comments (list) – List containing three strings, these form the header of the created file
  • cutoff (float) – Pair potential and density cutoff. If None then value of nr * dr is used.
atsim.potentials.potential(func)[source]

Decorator for callables that should be tagged as potential-forms or potential-functions

atsim.potentials.is_potential(obj)[source]

Identifies if an object is a potential-form or potential-function

atsim.potentials.buck4(A, rho, C, r_detach, r_min, r_attach)[source]

Returns a potential form describing the four-range Buckingham potential.

The potential form is:

\[\begin{split}V(r_{ij}) = \begin{cases} A \exp(-r_{ij}/\rho) , & 0 \leq r_{ij} \leq r_\text{detach}\\ a_0 + a_1 r_{ij} +a_2 r_{ij}^2+a_3 r_{ij}^3+a_4 r_{ij}^4+a_5 r_{ij}^5, & r_\text{detach} < r_{ij} < r_\text{min}\\ b_0 +b_1 *r_{ij}+b_2*r_{ij}^2+b_3*r_{ij}^3 , & r_\text{min} \leq r_{ij} < r_\text{attach}\\ -\frac{C}{r_{ij}^6} , & r_{ij} \geq r_\text{attach}\\ \end{cases}\end{split}\]

In other words this is a Buckingham potential in which the Born-Mayer component acts at small separations and the disprsion term acts at larger separation. These two parts are linked by a fifth then third order polynomial (with a minimum formed in the spline at \(r_ ext{min}\)).

The spline parameters are subject to the constraints that \(V(r_{ij})\), first and second derivatives must be equal at the boundary points and the function must have a stationary point at r_min.

See also

  • atsim.potentials.Buck4_Spline
  • atsim.potentials.Buck4_SplinePotential

Note

Due to the complexity of calculating the spline-coefficients this potential form does not have an equivalent in the atsim.potentials.potentialfunctions module.

Parameters:
  • A – A potential parameter.
  • rho – potential parameter.
  • C – C parameter.
  • r_detach – Separation where spline starts.
  • r_min – Location of stationary point.
  • r_attach – End of splined region.
Returns:

Splined potential.
atsim.potentials.buck[source]
atsim.potentials.bornmayer[source]
atsim.potentials.coul[source]
atsim.potentials.constant[source]
atsim.potentials.exponential[source]
atsim.potentials.hbnd[source]
atsim.potentials.lj[source]
atsim.potentials.morse[source]
atsim.potentials.polynomial[source]
atsim.potentials.sqrt[source]
atsim.potentials.tang_toennies[source]
atsim.potentials.zbl[source]
atsim.potentials.zero[source]
atsim.potentials.exp_spline[source]
atsim.potentials.create_Multi_Range_Potential_Form(*range_tuples, **kwargs)[source]

Creates Multi_Range_Potential_Form or sub-class instance, from list of Multi_Range_Defn instances in range_tuples.

If any Multi_Range_Defn object’s .has_deriv2 are True then an instance of Multi_Range_Potential_Form_Deriv2 is returned.

If any Multi_Range_Defn object’s .has_deriv property is True but all .has_deriv2 are False then an instance of Multi_Range_Potential_Form_Deriv is returned.

If non of the Multi_Range_Defn objects provide analytical deriv or deriv2 methods, return Multi_Range_Potential_Form.

Parameters:
  • range_tuples – List of Multi_Range_Defn instances.
  • kwargs – Keyword arguments passed to Multi_Range_Potential_Form constructor.
Returns:

See above
class atsim.potentials.Multi_Range_Defn(range_type, start, potential_form, **kwargs)[source]

Bases: object

range_type
start
potential_form
has_deriv

Returns True if the potential callable provides an analytical derivative through a .deriv() method.

has_deriv2

Returns True if the potential callable provides an analytical derivative through a .deriv2() method.

deriv(self, r)
deriv2(self, r)
atsim.potentials.plus(a, b)[source]

Takes two functions and returns a third which when evaluated returns the result of a(r) + b(r)

This function is useful for combining existing potentials.

Derivatives:

If either of the potential callables (a and b) provide a .deriv() method the function returned by plus() will also have a .deriv() method. This allows analytical derivatives to be specified. If only one of a or b provide .deriv() then the derivative of the other callable will be evaluated numerically.

If neither function has a .deriv() method then the function returned here will also not have a .deriv() method.

Example:

To combine buck() and hbnd() functions from the atsim.potentials.potentialforms module to give:

A*(-r/rho) + C/r**6 + D/r**12 - E/r**10

this function can then be used as follows:

plus(buck(A,rho,C), hbnd(D,E))
Parameters:
  • a – First callable
  • b – Second callable
Returns:

Function that when evaulated returns a(r) + b(r)
atsim.potentials.product(a, b)[source]

Takes two callables and returns a third which when evaluated returns the result of a(r) * b(r)

This function is useful for combining existing potentials.

Derivatives:

If either of the potential callables (a and b) provide a .deriv() method the function returned by product() will also have a .deriv() method. This allows analytical derivatives to be specified. If only one of a or b provide .deriv() then the derivative of the other callable will be evaluated numerically.

If neither function has a .deriv() method then the function returned here will also not have a .deriv() method.

Parameters:
  • a – First callable
  • b – Second callable
Returns:

Function that when evaulated returns a(r) * b(r)
atsim.potentials.pow(a, b)[source]

Takes two callables and returns a third which when evaluated returns the result of a(r)**b(r)

This function is useful for combining existing potentials.

Derivatives:

If either of the potential callables (a and b) provide a .deriv() method the function returned by pow() will also have a .deriv() method. This allows analytical derivatives to be specified. If only one of a or b provide .deriv() then the derivative of the other callable will be evaluated numerically.

If neither function has a .deriv() method then the function returned here will also not have a .deriv() method.

Parameters:
  • a – First callable
  • b – Second callable
Returns:

Function that when evaulated returns a(r)**b(r) (a to the power of b)
class atsim.potentials.TableReader(fileobject)[source]

Bases: object

Callable that allows pretabulated data to be used with a Potential object.

datReader[source]
Returns:_tablereaders.DatReader associated with this callable
__call__(self, separation)[source]
atsim.potentials.plotToFile(fileobj, lowx, highx, func, steps=10000)[source]

Convenience function for plotting the potential functions contained herein.

Data is written to a text file as two columns (r and E) separated by spaces with no header.

Parameters:
  • fileobj – Python file object into which data should be plotted
  • lowx – X-axis lower value
  • highx – X-axis upper value
  • func – Function to be plotted
  • steps – Number of data points to be plotted
atsim.potentials.plot(filename, lowx, highx, func, steps=10000)[source]

Convenience function for plotting the potential functions contained herein.

Data is written to a text file as two columns (r and E) separated by spaces with no header.

Parameters:
  • filename – File into which data should be plotted
  • lowx – X-axis lower value
  • highx – X-axis upper value
  • func – Function to be plotted
  • steps – Number of data points to be plotted
atsim.potentials.plotPotentialObject(filename, lowx, highx, potentialObject, steps=10000)[source]

Convenience function for plotting energy of pair interactions given by instances of atsim.potentials.Potential obtained by calling potential .energy() method.

Data is written to a text file as two columns (r and E) separated by spaces with no header.

Parameters:
  • filename – File into which data should be plotted
  • lowx – X-axis lower value
  • highx – X-axis upper value
  • func – atsim.potentials.Potential object.
  • steps – Number of data points to be plotted
atsim.potentials.plotPotentialObjectToFile(fileobj, lowx, highx, potentialObject, steps=10000)[source]

Convenience function for plotting energy of pair interactions given by instances of atsim.potentials.Potential obtained by calling potential .energy() method.

Data is written to a text file as two columns (r and E) separated by spaces with no header.

Parameters:
  • fileobj – Python file object into which data should be plotted
  • lowx – X-axis lower value
  • highx – X-axis upper value
  • func – atsim.potentials.Potential object.
  • steps – Number of data points to be plotted
exception atsim.potentials.UnsupportedTabulationType[source]

Bases: Exception

Exception thrown by writePotentials() when unknown tabulation type specified

atsim.potentials.writePotentials(outputType, potentialList, cutoff, gridPoints, out=sys.stdout)[source]

Tabulates pair-potentials in formats suitable for multiple simulation codes.

  • The outputType parameter can be one of the following:

    • DL_POLY:

      • This function creates output that can be written to a TABLE and used within DL_POLY.
      • for a working example see Quick-Start: DL_POLY.

    • GULP:

    • LAMMPS:

      • Creates files readable by LAMMPS pair_style table

      • Each file can contain multiple potentials:

        • the block representing each potential has a title formed from the speciesA and speciesB attributes of the Potential instance represented by the block. These are sorted into their natural order and separated by a hyphen to form the title.

        • Example:

          • For a Potential where speciesA = Xe and speciesB = O the block title would be: O-Xe.
          • If speciesA = B and speciesB = O the block title would be: B-O.

        • within LAMMPSthe block title is used as the keyword argument to the pair_style table pair_coeff directive.

Parameters:
  • outputType (str) – The type of output that should be created can be one of: DL_POLY or LAMMPS
  • potentialList (list) – List of Potential objects to be tabulated.
  • cutoff (float) – Largest separation to be tabulated.
  • gridPoints (int) – Number of rows in tabulation.
  • out (file) – Python file like object to which tabulation should be written