.. _potable-pair-section:
******************
``[Pair]`` section
******************
In the ``[Pair]`` section of the model definition, potential-forms are combined with parameters that tailor them to a given pair of species.
The *basic* form of an entry in this section is::
SPECIES_A-SPECIES_B : POTENTIAL_FORM PARAM_1 PARAM_2 ... PARAM_N
* The label before the colon: ``SPECIES_A-SPECIES_B`` identifies the pair interaction being parametrised.
+ This label consists of two species identifiers (``SPECIES_A`` and ``SPECIES_B``\ ) separated by a hyphen ``-``\ .
+ The order in which the species labels are specified does not matter. That is, ``Au-Ag`` and ``Ag-Au`` would be equivalent.
+ The ``[Pair]`` section can only contain one entry per unique species pair.
* The potential definition, specified after the colon, consists of the name of the potential-form (``POTENTIAL_FORM``\ ) followed by the numeric parameters it requires.
Pre-defined potential-forms
+++++++++++++++++++++++++++
A number of :ref:`pre-defined potential forms are provided `\ . These all have names pre-fixed by ``as.``
Each entry in the :ref:`list of potentials ` provides an entry called ``potable signature``\ . This shows the order in which parameters should be given to create a potential.
For the :ref:`Buckingham ` potential the ``potable signature`` is:
| ``as.buck`` :math:`A` :math:`\rho` :math:`C`
which is associated with the formula:
.. math ::
V(r_{ij}) = A \exp \left( - \frac{r_{ij}}{\rho} \right) - \frac{C}{r_{ij}^6}
This means that if we were defining a potential between Si and O that had :math:`A_{ij}` = 18003, :math:`\rho_{ij}` = 0.205 and :math:`C_{ij}` = 133.36 then the entry in the ``[Pair]`` section would be::
[Pair]
Si-O = as.buck 18003.0 0.205 133.36
Please refer to the ``potable signature`` when using the ``as.*`` potential-forms; specifying parameters in the wrong order will cause you problems.
It is also possible to define your own potential-forms in the ``[Potential-Form]`` section of ``potable`` file. These are parametrised here in the ``[Pair]`` section in the same way as the pre-defined ``as.*`` potential-forms. This usage is documented later here: :ref:`potable-potential-form`\ .
.. _potential-modifiers:
Potential modifiers
+++++++++++++++++++
If you followed the :ref:`quick-start` guide, you will have already seen a potential modifier. The ``[Pair]`` section from the :download:`basak.aspot <../quick_start/basak.aspot>` used in the :ref:`quick-start` is repeated here:
.. literalinclude:: ../quick_start/basak.aspot
:lines: 6-10
You can see that the O-O and U-U pairs use the basic definition we have just seen. The U-O interaction however uses the modified form:
.. literalinclude:: ../quick_start/basak.aspot
:lines: 9-10
Here ``sum()`` takes two basic pair-definitions (one for :ref:`as.buck ` and one for :ref:`as.morse `\ ) and creates a pair-potential that is the sum of both. Here ``sum()`` is acting as a potential-modifier.
Potential-modifiers take the input or output of other potentials and produce outputs that have been altered in some way. A number of modifiers are provided with ``atsim.potentials`` and these are listed.
.. seealso::
See :ref:`list-of-potential-modifiers`\ .
.. _multi-range-potentials:
Multi-range potentials
++++++++++++++++++++++
The potential definition syntax used in the ``[Pair]`` section supports an extension which allows a series of potential-forms to be concatenated to each other, allowing each to act over a particular range of separations. These are defined as multi-range potentials. Concrete examples of where they are useful are provided in :ref:`multi-range-potential-examples` however the basic syntax defining multi-range potentials is introduced here.
Suppose we want to define a potential acting between Mg and O using two potential-forms: ``pot_A`` and ``pot_B``. The first is to be parametrised with values of 5.3 and 1.2 and ``pot_B`` with 9.6 and 2.4. Now say we want ``pot_A`` to act over the separations :math:`0 \geq r_{ij} \leq 3` and ``pot_B`` :math:`3 < r_{ij} \leq 8` and for the pair-potential to evaluate to zero when :math:`r_{ij} > 8`\ .
.. figure:: figures/multi_range.svg
:name: fig_multi_range
:width: 60%
:align: center
Illustration of multi-range potential definition described in the text.
The multi-range potential just described is summarised in :numref:`fig_multi_range`\ . This would be defined as follows in the ``potable`` input file::
[Pair]
Mg-O : >=0 pot_A 5.3 1.2 >3 pot_B 9.6 2.4 >8 as.zero
Notice that we used the :ref:`as.zero ` potential-form to provide a constant value of 0.0 when :math:`r_{ij} > 8` (equally ``as.constant 0.0`` could have been used).
The syntax for a multi-range potential can be summarised as:
* A series of single potential definitions delimited by range markers.
* Range markers take the form:
- ``>=R`` which indicates that the potential definition, following the marker, will be used at separations **greater than or equal** to the value specifid by ``R``
- ``>R`` which means the same but acts only for separations **greater** than ``R``\ .
.. note::
``potable`` defines all potentials to have the initial range of ``>0`` unless a range is explicitly defined. This is to avoid divide by zero errors when the potential is evaluated for :math:`r_{ij}` = 0. As this separation is unimportant to most physically relevant simulation.
To include :math:`r_{ij}` = 0 in you tabulations simply make sure that your potential starts with ``>=0``\ ::
>=0 POTENTIAL_DEFN
.. seealso::
* Examples of multi-range potentials can be found here: :ref:`multi-range-potential-examples`