# 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 the force() 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 Energy for given separation
force(r, h=1e-06)

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 -dU/dr at given separation float
speciesA
speciesB
atsim.potentials.writePotentials(outputType, potentialList, cutoff, gridPoints, out=<open file '<stdout>', mode 'w'>)

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.
• 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.

• For a working example see Quick-Start: LAMMPS

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

### 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 many-body 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 the electronDensityFunction constructor parameter is a single python callable.

The Finnis-Sinclair 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 the species passed to the EAMPotential constructor and DENSITY_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 Finnis-Sinclair style EAM tabulation functions:

alPotential = EAMPotential(
"Al",
13,
26.98,
embeddingFunction,
{"Al" : density_Al_Al, # specifies Al-Al density function
"Cu" : density_Al_Cu, # specifies Al-Cu density function
})


• For working examples of how to use EAMPotential with the conventional Embedded Atom Model:
• For complete examples using the Finnis-Sinclair 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() and writeTABEAMFinnisSinclair()) 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
electronDensity(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. Contribution to electron density due to given pair separation. float.
embeddingValue(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. Energy for given density (as given by self.embeddingFunction). 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 see writeSetFL().

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=<open file '<stdout>', mode 'w'>, comments=['', '', ''], cutoff=None)

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

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=<open file '<stdout>', mode 'w'>, comments=['', '', ''], cutoff=None)

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 EAMPotential.__init__() for how these are specified to the EAMPotential constructors.

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 the DL_POLY simulation code.

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=<open file '<stdout>', mode 'w'>, title='')

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 EAMPotential.__init__() for how these are specified to the EAMPotential 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.

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 – X-axis lower value highx – X-axis 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 – 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)

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)

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

To combine buck() and hbnd() functions from the potentialsforms 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 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 to endPotential 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
class atsim.potentials.TableReader(fileobject)

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

datReader

## 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 Born-Mayer 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$$ Function that will evaluate Born-Mayer 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 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 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 Function that will evaulate energy for potential of hbnd form for given A and B parameters
atsim.potentials.potentialforms.lj(epsilon, sigma)

Lennard-Jones 12-6 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$$ 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 Morse potential callable
atsim.potentials.potentialforms.zbl(z1, z2)

ZBL potential.

Ziegler-Biersack-Littmark screened nuclear repulsion for describing high energy interactions.

Parameters: z1 – Atomic number of species i z2 – Atomic number of species j ZBL callable