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
Returns: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
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 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
   })
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.
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 the embeddingFunction 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 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=<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.

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

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=<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
  • funcatsim.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
  • funcatsim.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
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 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
Returns:_tablereaders.DatReader associated with this callable

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\)
Returns:

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

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\)
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.

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

Parameters:
  • z1 – Atomic number of species i
  • z2 – Atomic number of species j
Returns:

ZBL callable