API Reference¶
atsim.potentials
¶
Pair Potential Tabulation¶

class
atsim.potentials.
Potential
(speciesA, speciesB, potentialFunction)¶ 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. This callable is also used when calculating forces \(\frac{dU}{dr}\) through theforce()
method. Forces are calculated by using a simple finite difference method to find the linear gradient of the energy for a given separation.
__init__
(speciesA, speciesB, potentialFunction)¶ Create a Potential object from a python function or callable that returns energy at a given separation.
Parameters:  speciesA – Label of first species in the potential pair
 speciesB (str) – Label of second species in the potential pair
 potentialFunction – Python callable which accepts a single parameter (separation) and returns energy for that separation

energy
(r)¶ Parameters: r – Separation Returns: Energy for given separation

force
(r, h=1e06)¶ Calculate force for this potential at a given separation.
Force is calculated as dU/dr by performing numerical differentiation of function.
Parameters:  r (float) – Separation
 h (float) – Distance increment used when calculating energy derivative centred on r
Returns: dU/dr at given separation
Return type: float

speciesA
¶

speciesB
¶


atsim.potentials.
writePotentials
(outputType, potentialList, cutoff, gridPoints, out=<open file '<stdout>', mode 'w'>)¶ Tabulates pairpotentials 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 QuickStart: DL_POLY.
 This function creates output that can be written to a
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
andspeciesB
attributes of thePotential
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
wherespeciesA
= Xe andspeciesB
= O the block title would be:OXe
.  If
speciesA
= B andspeciesB
= O the block title would be:BO
.
 For a
within LAMMPSthe block title is used as the
keyword
argument to the pair_style tablepair_coeff
directive.
For a working example see QuickStart: LAMMPS
Parameters:  outputType (str) – The type of output that should be created can be one of:
DL_POLY
orLAMMPS
 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
Embedded Atom Method Tabulation¶

class
atsim.potentials.
EAMPotential
(species, atomicNumber, mass, embeddingFunction, electronDensityFunction, latticeConstant=0.0, latticeType='fcc')¶ 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 manybody component of an Embedded Atom potential Model.

__init__
(species, atomicNumber, mass, embeddingFunction, electronDensityFunction, latticeConstant=0.0, latticeType='fcc')¶ Create EAMPotential object.
Note on electronDensityFunction parameter
In the conventional Embedded Atom Method each
EAMPotential
encapsulates a single density function (density functions are mixed by the simulation code for alloy systems). In such cases theelectronDensityFunction
constructor parameter is a single python callable.The FinnisSinclair extension of the Embdedded Atom Method allows density functions for specific pairs of species to be used. This requires a callable to be given for each species pair. This is achieved by passing a dictionary of callables/functions to the
electronDensityFunction
constructor parameter. This has the general form:{ SPECIES_1 : DENSITY_FUNCTION_1, SPECIES_2 : DENSITY_FUNCTION_2, ... SPECIES_N : DENSITY_FUNCTION_N}
Where the keys
SPECIES_N
represent the species of atoms surrounding a central atom with thespecies
passed to theEAMPotential
constructor andDENSITY_FUNCTION_N
is a unary function that takes the separation between the central atom and the surrounding atom and returns the electron density due to the surrounding atom.Example: For a binary system containing Al and Cu, the
EAMPotential
constructor may be invoked as follows to create an object representing Al for use with the FinnisSinclair style EAM tabulation functions:alPotential = EAMPotential( "Al", 13, 26.98, embeddingFunction, {"Al" : density_Al_Al, # specifies AlAl density function "Cu" : density_Al_Cu, # specifies AlCu density function })
See also
 For working examples of how to use
EAMPotential
with the conventional Embedded Atom Model:  For complete examples using the FinnisSinclair version of the method:
Parameters:  species – Species label
 atomicNumber – Atomic number
 mass – Atomic mass
 embeddingFunction – Python callable that retuns embedding values as function of density
 electronDensityFunction – Python callable that returns density as function of separation in angstroms.
For write functions that accept multiple density functions (e.g.
writeSetFLFinnisSinclair()
andwriteTABEAMFinnisSinclair()
) a dictionary mapping species to a function object is expected for this parameter. See above.  latticeConstant – Lattice constant for this species
 latticeType – Lattice type e.g. ‘fcc’ for this
 For working examples of how to use

electronDensity
(separation)¶ Gives the ‘electron’ density for an atom separated from current species by
separation
.This is a passthrough 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.

embeddingValue
(density)¶ Method that returns energy for given electron density.
This method simply passes
density
to the callable stored in theembeddingFunction
and returns its value.Parameters: density (float) – Electron density. Returns: Energy for given density (as given by self.embeddingFunction
).Return type: float


atsim.potentials.
writeFuncFL
(nrho, drho, nr, dr, eampots, pairpots, out=<open file '<stdout>', mode 'w'>, title='')¶ Creates a DYNAMO
funcfl
formatted file suitable for use with lammps pair_style eam potential form. For the pair_style eam/alloy seewriteSetFL()
.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 pairpotential, 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 XX interaction (where X is the species represented by EAMPotential ineampots
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=<open file '<stdout>', mode 'w'>, comments=['', '', ''], cutoff=None)¶ Creates EAM potential in the DYNAMO
setfl
format. This format is suitable for use with theLAMMPS
pair_style eam/alloy.See also
For a working example using this function see Example 2a: Tabulate AlCu 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=<open file '<stdout>', mode 'w'>, comments=['', '', ''], cutoff=None)¶ Creates FinnisSinclar EAM potential in the DYNAMO
setfl
format. The format should be used with theLAMMPS
eam/fs pair_style.The
EAMPotential
instances within theeampots
list are expected to provide individual density functions for each species pair in the species being tabulated. SeeEAMPotential.__init__()
for how these are specified to theEAMPotential
constructors.See also
For a working example using this function see Example 3a: Tabulate AlFe FinnisSinclair 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.
writeTABEAM
(nrho, drho, nr, dr, eampots, pairpots, out=<open file '<stdout>', mode 'w'>, title='')¶ Create
TABEAM
file for use with theDL_POLY
simulation code.See also
For a working example using this function see Example 2b: Tabulate AlCu 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=<open file '<stdout>', mode 'w'>, title='')¶ Create Exended EAM variant of DL_POLY
TABEAM
file.The
EAMPotential
instances within theeampots
list are expected to provide individual density functions for each species pair in the species being tabulated. SeeEAMPotential.__init__()
for how these are specified to theEAMPotential
constructors.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 AlFe FinnisSinclair 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
EAMPotential
objects  pairpots (list) – Potentials List of
Potential
objects  out (file object) – Python file object to which
TABEAM
data should be written  title (str) – Title of TABEAM file
Miscellaneous Functions¶

atsim.potentials.
plot
(filename, lowx, highx, func, steps=10000)¶ 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 – Xaxis lower value
 highx – Xaxis upper value
 func – Function to be plotted
 steps – Number of data points to be plotted

atsim.potentials.
plotToFile
(fileobj, lowx, highx, func, steps=10000)¶ 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 – Xaxis lower value
 highx – Xaxis upper value
 func – Function to be plotted
 steps – Number of data points to be plotted

atsim.potentials.
plotPotentialObject
(filename, lowx, highx, potentialObject, steps=10000)¶ 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 – Xaxis lower value
 highx – Xaxis upper value
 func –
atsim.potentials.Potential
object.  steps – Number of data points to be plotted

atsim.potentials.
plotPotentialObjectToFile
(fileobj, lowx, highx, potentialObject, steps=10000)¶ 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 – Xaxis lower value
 highx – Xaxis upper value
 func –
atsim.potentials.Potential
object.  steps – Number of data points to be plotted

atsim.potentials.
plus
(a, b)¶ 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.
Example:
Parameters:  a – First callable
 b – Second callable
Returns: Function that when evaulated returns
a(r) + b(r)

class
atsim.potentials.
SplinePotential
(startPotential, endPotential, detachmentX, attachmentX)¶ Callable to allow splining of one potential to another

__init__
(startPotential, endPotential, detachmentX, attachmentX)¶ Joins
startPotential
toendPotential
using exponential spline of the form:\[U(r_{ij}) = \exp \left( B_0 + B_1 r_{ij} + B_2 r_{ij}^2 + B_3 r_{ij}^3 + B_4 r_{ij}^4 + B_5 r_{ij}^5 \right)\]The spline coefficients \(B_{0...5}\) can be obtained using the
splineCoefficients()
property.Parameters:  startPotential – Function defining potential for rij <= detachmentX
 endPotential – Function defining potential for rij => attachmentX
 detachmentX – rij value at which startPotential should end
 attachmentX – rij value at which splines join endPotential

attachmentX
¶ Returns: Point at which spline should end

detachmentX
¶ Returns: Point at which spline should start

endPotential
¶ Returns: Function defining potential for separations > attachmentX

interpolationFunction
¶ Returns: Exponential spline function connecting startPotential and endPotential for separations detachmentX
< rij <attachmentX

splineCoefficients
¶ Returns: Tuple containing the six coefficients of the spline polynomial

startPotential
¶ Returns: Function defining potential for separations < detachmentX

atsim.potentials.potentialforms
¶
Functions representing different potential forms.
The functions contained herein are function factories returning a function that takes separation as its sole argument.

atsim.potentials.potentialforms.
bornmayer
(A, rho)¶ Return a BornMayer potential function for the given parameters
\[U(r_{ij}) = A \exp \left( \frac{r_{ij}}{\rho} \right)\]Parameters:  A – Potential parameter
 rho – Potential parameter \(\rho\)
Returns: Function that will evaluate BornMayer potential for given A and rho parameters

atsim.potentials.potentialforms.
buck
(A, rho, C)¶ Returns a Buckingham potential function for a given set of A, rho and C parameters
\[U(r_{ij}) = A \exp \left( \frac{r_{ij}}{\rho} \right)  \frac{C}{r_{ij}^6}\]Parameters:  A – Buckingham A parameter
 rho – Buckingham rho parameter \(\rho\)
 C – Buckingham C parameter
Returns: Function that will evaulate Buckingham potential for given A, rho and C

atsim.potentials.potentialforms.
coul
(qi, qj)¶ Coulomb potential (including \(4\pi \epsilon_0\) term).
\[U(r_{ij}) = \frac{ q_i q_j }{4 \pi \epsilon_0 r_{ij} }\]Note
Constant value appropriate for \(r_{ij}\) in angstroms and energy in eV.
Parameters:  qi – Charge on species i
 qj – Charge on species j
Returns: Coulomb callable

atsim.potentials.potentialforms.
hbnd
(A, B)¶ Returns a function with the DL_POLY hbnd form:
\[U(r_{ij}) = \frac{A}{r_{ij}^{12}}  \frac{B}{r_{ij}^{10}}\]Parameters:  A – Potential A parameter
 B – Potentials’ B parameter
Returns: Function that will evaulate energy for potential of hbnd form for given A and B parameters

atsim.potentials.potentialforms.
lj
(epsilon, sigma)¶ LennardJones 126 potential.
\[U(r_{ij}) = 4 \epsilon \left( \frac{\sigma^{12}}{r_{ij}^{12}}  \frac{\sigma^6}{r_{ij}^6} \right)\]Parameters:  epsilon – Epsilon parameter \(\epsilon\)
 sigma – Sigma parameter \(\sigma\)
Returns: Lennard Jones callable

atsim.potentials.potentialforms.
morse
(gamma, r_star, D)¶ Return morse function parametrised with gamma, r_start and D.
Potential function is (where r is interatomic separation):
\[U(r_{ij}) = D \left[ \exp \left( 2 \gamma (r_{ij}  r_*) \right)  2 \exp \left( \gamma (r  r_*) \right) \right]\]Parameters:  gamma – Potential parameter \(\gamma\)
 r_star – Potential parameter \(r_*\)
 D – Potential parameter
Returns: Morse potential callable

atsim.potentials.potentialforms.
zbl
(z1, z2)¶ ZBL potential.
ZieglerBiersackLittmark screened nuclear repulsion for describing high energy interactions.
Parameters:  z1 – Atomic number of species i
 z2 – Atomic number of species j
Returns: ZBL callable