:mod:`atsim.potentials` ======================= .. py:module:: atsim.potentials .. autoapi-nested-parse:: A collection of classes and functions related to defining potentials Subpackages ----------- .. toctree:: :titlesonly: :maxdepth: 3 config/index.rst referencedata/index.rst spline/index.rst tools/index.rst Submodules ---------- .. toctree:: :titlesonly: :maxdepth: 1 eam_tabulation/index.rst pair_tabulation/index.rst potentialforms/index.rst potentialfunctions/index.rst tableforms/index.rst Package Contents ---------------- Classes ~~~~~~~ .. autoapisummary:: atsim.potentials.Potential atsim.potentials.EAMPotential atsim.potentials.SplinePotential atsim.potentials.Multi_Range_Defn atsim.potentials.TableReader Functions ~~~~~~~~~ .. autoapisummary:: atsim.potentials.gradient atsim.potentials.num_deriv atsim.potentials.deriv atsim.potentials.writeTABEAM atsim.potentials.writeTABEAMFinnisSinclair atsim.potentials.writeFuncFL atsim.potentials.writeSetFL atsim.potentials.writeSetFLFinnisSinclair atsim.potentials.potential atsim.potentials.is_potential atsim.potentials.buck4 atsim.potentials.create_Multi_Range_Potential_Form atsim.potentials.plus atsim.potentials.product atsim.potentials.pow atsim.potentials.plotToFile atsim.potentials.plot atsim.potentials.plotPotentialObject atsim.potentials.plotPotentialObjectToFile atsim.potentials.writePotentials .. py:class:: Potential(speciesA, speciesB, potentialFunction, h=1e-06) Bases: :class:`object` Class used to describe a potential to the :func:`~atsim.potentials.writePotentials()` function. Potential objects encapsulate a python function or callable which is used by the :meth:`~atsim.potentials.Potential.energy` method to calculate potential energy. The :meth:`~atsim.potentials.Potential.force` method returns :math:`\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 :func:`gradient` function is used to wrap the energy callable so that the correct derivative implementation is used. .. attribute:: speciesA .. attribute:: speciesB .. attribute:: potentialFunction .. method:: energy(self, r) :param r: Separation :return: Energy for given separation .. method:: 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. :param r: Separation :type r: float :return: -dU/dr at given separation :rtype: float .. py:class:: EAMPotential(species, atomicNumber, mass, embeddingFunction, electronDensityFunction, latticeConstant=0.0, latticeType='fcc') Bases: :class:`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. .. method:: 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. :param density: Electron density. :type density: float :return: Energy for given density (as given by ``self.embeddingFunction``). :rtype: float .. method:: 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. .. :warning:: In cases where the ``electronDensityFunction`` attribute has been set to a dictionary, (for instance, when density functions specific to particular pairs of species are required), this method should not be used :param separation: Separation (in angstroms) between atom represented by this object and another atom. :type separation: float. :return: Contribution to electron density due to given pair separation. :rtype: float. .. py:class:: SplinePotential(startPotential, endPotential, detachmentX, attachmentX) Bases: :class:`atsim.potentials.spline.Custom_SplinePotential` Callable to allow splining of one potential to another using an exponential spline .. function:: gradient(func, h=1e-06) 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. :param func: Function to be wrapped :param h: Step size used when performing numerical differentiation :return: Function that returns derivative of func .. function:: num_deriv(r, func, h=1e-06) Returns numerical derivative of the callable `func` :param r: Value at which derivative of `func` should be evaluated. :param func: Function whose gradient is to be evaluated. :param h: Step size used when performing numerical differentiation. :return: Numerical derivative of func at `r`. .. function:: deriv(r, func, h=1e-06) 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() :param r: Value at which derivative of `func` should be evaluated. :param func: Function whose derivative is to be evaluated. :param h: Step size used when performing numerical differentiation. :return: Derivative of func at `r`. .. function:: writeTABEAM(nrho, drho, nr, dr, eampots, pairpots, out=sys.stdout, title='') Create ``TABEAM`` file for use with the ``DL_POLY`` simulation code. .. seealso :: For a working example using this function see :ref:`eam_example_2b` :param nrho: Number of entries in tabulated embedding functions :type nrho: int :param drho: Step size between consecutive embedding function entries :type drho: float :param nr: Number of entries in tabulated pair potentials and density functions :type nr: int :param dr: Step size between entries in tabulated pair potentials and density functions :type dr: float :param eampots: Potentials List of potentials.EAMPotential objects :type eam: list :param pair: Potentials List of potentials.Potential objects :type pairpots: list :param out: Python file object to which TABEAM data should be written :type out: file object :param title: Title of TABEAM file :type title: str .. function:: writeTABEAMFinnisSinclair(nrho, drho, nr, dr, eampots, pairpots, out=sys.stdout, title='') Create Exended EAM variant of DL_POLY ``TABEAM`` file. The :class:`~atsim.potentials.EAMPotential` instances within the ``eampots`` list are expected to provide individual density functions for each species pair in the species being tabulated. See :meth:`~atsim.potentials.EAMPotential.__init__` for how these are specified to the :class:`~atsim.potentials.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. .. seealso :: For a working example using this function see :ref:`eam_example_3b` :param nrho: Number of entries in tabulated embedding functions :type nrho: int :param drho: Step size between consecutive embedding function entries :type drho: float :param nr: Number of entries in tabulated pair potentials and density functions :type nr: int :param dr: Step size between entries in tabulated pair potentials and density functions :type dr: float :param eampots: Potentials List of :class:`atsim.potentials.EAMPotential` objects :type eam: list :param pairpots: Potentials List of :class:`atsim.potentials.Potential` objects :type pairpots: list :param out: Python file object to which ``TABEAM`` data should be written :type out: file object :param title: Title of TABEAM file :type title: str .. function:: 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 `_ potential form. For the `pair_style eam/alloy `_ see :func:`~atsim.potentials.writeSetFL`. .. seealso :: For a working example using this function see :ref:`eam_example_1` :param nrho: Number of points used to describe embedding function :type nrho: int :param drho: Step size between rho values used to describe embedding function :type drho: float :param nr: Number of points used for the pair-potential, and density functions :type nr: int :param dr: Step size between r values in effective charge and density functions :type dr: float :param eampots: List containing a single :class:`~atsim.potentials.EAMPotential` instance for species to be tabulated. :type eampots: list :param pairpots: List containing a single :class:`~atsim.potentials.PairPotential` instance for the X-X interaction (where X is the species represented by EAMPotential in ``eampots`` list) :type pairpots: list :param out: Python file object to which eam table file will be written :type out: file object :param title: Title to be written as table file header :type title: str .. function:: 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 use with the ``LAMMPS`` `pair_style eam/alloy `_. .. seealso :: For a working example using this function see :ref:`eam_example_2a` :param nrho: Number of points used to describe embedding function :type nrho: int :param drho: Increment used when tabulating embedding function :type drho: float :param nr: Number of points used to describe density and pair potentials :type nr: int :param dr: Separation increment used when tabulating density function and pair potentials :type dr: float :param eampots: Instances of lammps.writeEAMTable.EAMPotential() which encapsulate information about each species :type eampots: list :param pairpots: Instance of potentials.Potential, these describe repulsive pair potential component of EAM potential :type pairpots: list :param out: Python file object into which EAM potential data should be written :type out: file object :param comments: List containing three strings, these form the header of the created file :type comments: list :param cutoff: Pair potential and density cutoff, if None then value of ``nr`` * ``dr`` is used. :type cutoff: float .. function:: 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 ``LAMMPS`` `eam/fs pair_style `_. The :class:`~atsim.potentials.EAMPotential` instances within the ``eampots`` list are expected to provide individual density functions for each species pair in the species being tabulated. See :meth:`atsim.potentials.EAMPotential.__init__` for how these are specified to the :class:`atsim.potentials.EAMPotential` constructor. .. seealso :: For a working example using this function see :ref:`eam_example_3a` :param nrho: Number of points used to describe embedding function :type nrho: int :param drho: Increment used when tabulating embedding function :type drho: float :param nr: Number of points used to describe density and pair potentials :type nr: int :param dr: Separation increment used when tabulating density function and pair potentials :type dr: float :param eampots: Instances of lammps.writeEAMTable.EAMPotential() which encapsulate information about each species :type eampots: list :param pairpots: Instance of potentials.Potential, these describe repulsive pair potential component of EAM potential :type pairpots: list :param out: Python file object into which EAM potential data should be written :type out: file object :param comments: List containing three strings, these form the header of the created file :type comments: list :param cutoff: Pair potential and density cutoff. If None then value of ``nr`` * ``dr`` is used. :type cutoff: float .. function:: potential(func) Decorator for callables that should be tagged as potential-forms or potential-functions .. function:: is_potential(obj) Identifies if an object is a potential-form or potential-function .. function:: buck4(A, rho, C, r_detach, r_min, r_attach) Returns a potential form describing the four-range Buckingham potential. The potential form is: .. math:: 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} 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 :math:`r_ ext{min}`). The spline parameters are subject to the constraints that :math:`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`. .. seealso:: * :class:`atsim.potentials.Buck4_Spline` * :class:`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. :param A: A potential parameter. :param rho: potential parameter. :param C: C parameter. :param r_detach: Separation where spline starts. :param r_min: Location of stationary point. :param r_attach: End of splined region. :return: Splined potential. .. data:: buck .. data:: bornmayer .. data:: coul .. data:: constant .. data:: exponential .. data:: hbnd .. data:: lj .. data:: morse .. data:: polynomial .. data:: sqrt .. data:: tang_toennies .. data:: zbl .. data:: zero .. data:: exp_spline .. function:: create_Multi_Range_Potential_Form(*range_tuples, **kwargs) 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. :param range_tuples: List of Multi_Range_Defn instances. :param kwargs: Keyword arguments passed to Multi_Range_Potential_Form constructor. :return: See above .. py:class:: Multi_Range_Defn(range_type, start, potential_form, **kwargs) Bases: :class:`object` .. attribute:: range_type .. attribute:: start .. attribute:: potential_form .. attribute:: has_deriv Returns True if the potential callable provides an analytical derivative through a `.deriv()` method. .. attribute:: has_deriv2 Returns True if the potential callable provides an analytical derivative through a `.deriv2()` method. .. method:: deriv(self, r) .. method:: deriv2(self, r) .. function:: 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. **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 :func:`~atsim.potentials.potentialforms.buck` and :func:`~atsim.potentials.potentialforms.hbnd` functions from the :mod:`atsim.potentials.potentialforms` module to give: .. code:: python A*(-r/rho) + C/r**6 + D/r**12 - E/r**10 this function can then be used as follows: .. code:: python plus(buck(A,rho,C), hbnd(D,E)) :param a: First callable :param b: Second callable :return: Function that when evaulated returns ``a(r) + b(r)`` .. function:: product(a, b) 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. :param a: First callable :param b: Second callable :return: Function that when evaulated returns ``a(r) * b(r)`` .. function:: pow(a, b) 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. :param a: First callable :param b: Second callable :return: Function that when evaulated returns ``a(r)**b(r)`` (a to the power of b) .. py:class:: TableReader(fileobject) Bases: :class:`object` Callable that allows pretabulated data to be used with a Potential object. .. attribute:: datReader :return: _tablereaders.DatReader associated with this callable .. method:: __call__(self, separation) .. function:: 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. :param fileobj: Python file object into which data should be plotted :param lowx: X-axis lower value :param highx: X-axis upper value :param func: Function to be plotted :param steps: Number of data points to be plotted .. function:: 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. :param filename: File into which data should be plotted :param lowx: X-axis lower value :param highx: X-axis upper value :param func: Function to be plotted :param steps: Number of data points to be plotted .. function:: plotPotentialObject(filename, lowx, highx, potentialObject, steps=10000) Convenience function for plotting energy of pair interactions given by instances of :class:`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. :param filename: File into which data should be plotted :param lowx: X-axis lower value :param highx: X-axis upper value :param func: :class:`atsim.potentials.Potential` object. :param steps: Number of data points to be plotted .. function:: plotPotentialObjectToFile(fileobj, lowx, highx, potentialObject, steps=10000) Convenience function for plotting energy of pair interactions given by instances of :class:`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. :param fileobj: Python file object into which data should be plotted :param lowx: X-axis lower value :param highx: X-axis upper value :param func: :class:`atsim.potentials.Potential` object. :param steps: Number of data points to be plotted .. py:exception:: UnsupportedTabulationType Bases: :class:`Exception` Exception thrown by writePotentials() when unknown tabulation type specified .. function:: writePotentials(outputType, potentialList, cutoff, gridPoints, out=sys.stdout) 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 :ref:`Quick-Start: DL_POLY `. * ``GULP``: * Creates output for the `GULP code `_ * Output is in the form of a series of `spline potential forms `_ * The generated file can be loaded into GULP using the `library command `_ * ``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 :class:`~atsim.potentials.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 :class:`~atsim.potentials.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. :param outputType: The type of output that should be created can be one of: ``DL_POLY`` or ``LAMMPS`` :type outputType: str :param potentialList: List of Potential objects to be tabulated. :type potentialList: list :param cutoff: Largest separation to be tabulated. :type cutoff: float :param gridPoints: Number of rows in tabulation. :type gridPoints: int :param out: Python file like object to which tabulation should be written :type out: file