[Potential-Form] section¶
This section of the input file is used for defining formulae that can be used as potential-forms and functions elsewhere in the model definition.
This allows for potential-forms that are not described in the standard file itself. Entries in this section have the general form:
LABEL([ARG_1, ARG_2, ... , ARG_N]) : FORMULA
LABELis a unique identifier for the function (this can be used to refer to this function in the [Pair]).ARG ...defines the function signature by naming the arguments it takes.FORMULAmathematical expression defining the function.
Formula syntax¶
The FORMULA strings used in this section of the configuration file support a rich range of mathematical expressions. These are parsed using the cexprtk python module which is built on top of the exprtk library. As a result the supported operators and functions are listed here .
In addition, users can make use of functions from the python math module. In FORMULA definitions these are called with a pymath.* prefix. A list of the supported python math functions are given here: Python maths functions supported in mathematical expressions.
pymath formula example¶
As an example of where a pymath function might be useful, exprtk does not natively provide a means of calculating factorials. Instead, the python factorial() function can be used in a FORMULA as shown in this potential form definition:
N(zeta, n) = (2*zeta)**n * sqrt((2*zeta)/pymath.factorial(2*n))
Example: using custom-potential forms to define Basak potential¶
We will revisit the Basak [Basak2003] UO2 model. In the Quick-Start guide you will have seen that the published potential parameters required considerable manipulation to make them compatible with the Buckingham (buck) and Morse (morse) potential-forms defined in atsim.potentials (see Potential model). Rather than transforming model parameters in this way, it may be easier to use the pair-potential equations and parameters directly as they appear in a paper. The [Potential-Form] section is the mechanism by which this may be achieved.
The Buckingham potential used in the Basak paper has the form:
We can write this as an entry in [Potential-Form] as:
[Potential-Form]
basak_buck(r,f0,a,b,c) = f0*b*exp((a-r)/b) - c/r^6
Note
You may have noticed in this equation that we defined one of the terms using r^6 (r to the sixth power), where python syntax would define this as r**6. This is because, the formulae defined in this section are parsed using the exprtk library (via its python wrapper cexprtk).
To understand the functions, operators and syntax, supported for formulae please refer to the exprtk documentation.
It is also possible to call the standard as.* potential-forms in [Potential-Form] expressions. This is shown here to define a basak_morse function, where as.morse will be used to provide a function that can be used directly with the parameters from the Basak paper (Table 2). For reference, as.morse has the potable signature:
as.morse\(\gamma\) \(r_*\) \(D\)
Remembering that the \(D\) parameter is given as \(f_0 \times D\) using parameters from Table 2 (see Potential model) we can now define our second potential function:
[Potential-Form]
basak_buck(r,f0,a,b,c) = f0*b*exp((a-r)/b) - c/r^6
basak_morse(r, f0, d, gamma, r_star) = as.morse(r,gamma, r_star, f0*d)
Note
It should also be noted that not-all the as.* potential-forms are available as functions within these formulae (for instance as.buck4 isn’t). If you would like to check, please refer to the List of Potential Forms and make sure that potential-function is listed as one of its Features.
Now that we have both functions, we need to parametrise them for each interaction using values from Table 2. This is achieved in the normal way in the [Pair] section:
[Pair]
O-O : basak_buck 0.042203 3.82 0.327022 3.948787
U-U : basak_buck 0.042203 3.26 0.327022 0.0
O-U : sum(
basak_buck 0.042203 3.54 0.327022 0.0,
basak_morse 0.042203 13.6765 1.65 2.369)
Notice that for the O-U interaction we continue to use the sum() potential-modifier to combine our Buckingham and Morse potentials (see Potential modifiers).
The order in which parameters are specified in the [Pair] entries correspond to the arguments in the function signatures for basak_buck and basak_morse, as is now shown:
Note
By convention the as.* potentials take r (separation) as their first argument when used in formulae in the [Potential-Form] section.
This represents a subtle to difference to when they appear in the [Pair] section and the argument list defined by the potable signature entries in List of Potential Forms.
For instance where as.buck could be parametrised as as.buck 1000.0 0.2 32.0 in the [Pair] section it would be defined as as.buck(r, 1000.0, 0.2, 32.0) in a [Potential-Form] formula.
The model is now fully defined and gives the following potable input:
[Tabulation]
target : LAMMPS
nr : 1000
dr : 0.01
[Pair]
O-O : basak_buck 0.042203 3.82 0.327022 3.948787
U-U : basak_buck 0.042203 3.26 0.327022 0.0
O-U : sum(
basak_buck 0.042203 3.54 0.327022 0.0,
basak_morse 0.042203 13.6765 1.65 2.369)
[Potential-Form]
basak_buck(r,f0,a,b,c) = f0*b*exp((a-r)/b) - c/r^6
basak_morse(r, f0, d, gamma, r_star) = as.morse(r,gamma, r_star, f0*d)
This input file can be downloaded as basak_custom_potential_form_a.aspot and tabulated thus:
potable basak_custom_potential_form_a.aspot Basak.lmptab
Section Using Basak.lmptab in LAMMPS describes how this table can then be used to perform a molecular dynamics simulation.
Alternative descriptions¶
The potential-forms used in the previous example could have been defined in a number of different ways. Some of these are now shown to illustrate the flexibility of the potable system:
basak_custom_potential_form_b.aspot. In this example, a third potential-formbasak_buckmorseis defined. This addsbasak_buck()tobasak_morseas an alternative to using the sum() potential modifier in the [Pair].[Tabulation] target : LAMMPS nr : 1000 dr : 0.01 [Pair] O-O : basak_buck 0.042203 3.82 0.327022 3.948787 U-U : basak_buck 0.042203 3.26 0.327022 0.0 O-U : basak_buckmorse 0.042203 3.54 0.327022 0.0 13.6765 1.65 2.369 [Potential-Form] basak_buck(r,f0,a,b,c) = f0*b*exp((a-r)/b) - c/r^6 basak_morse(r, f0, d, gamma, r_star) = as.morse(r,gamma, r_star, f0*d) basak_buckmorse(r,f0,a,b,c,d,gamma,r_star) = basak_buck(r,f0,a,b,c) + basak_morse(r, f0,d,gamma,r_star)
basak_custom_potential_form_c.aspot. In this example the Morse potential is described directly rather than delegating to theas.morse()function:[Tabulation] target : LAMMPS nr : 1000 dr : 0.01 [Pair] O-O : basak_buck 0.042203 3.82 0.327022 3.948787 U-U : basak_buck 0.042203 3.26 0.327022 0.0 O-U : basak_buckmorse 0.042203 3.54 0.327022 0.0 13.6765 1.65 2.369 [Potential-Form] basak_buck(r,f0,a,b,c) = f0*b*exp((a-r)/b) - c/r^6 basak_morse(r, f0, d, gamma, r_star) = f0*d*(exp(-2*gamma*(r-r_star)) - 2*exp(-gamma*(r-r_star))) basak_buckmorse(r,f0,a,b,c,d,gamma,r_star) = basak_buck(r,f0,a,b,c) + basak_morse(r, f0,d,gamma,r_star)
basak_custom_potential_form_d.aspot. This example shows that[Potential-Form]formulae can refer to each other.In order to use the standard
as.buck()potential-function, its \(A_{ij}\) parameter must be calculated from thef0,aandbBasak parameters (see Potential model).Here an
A_ij()formula is defined which is then invoked from inside thebasak_buck()function. This sort of modularisation allows well structured and hence simpler expressions to be define.[Tabulation] target : LAMMPS nr : 1000 dr : 0.01 [Pair] O-O : basak_buck 0.042203 3.82 0.327022 3.948787 U-U : basak_buck 0.042203 3.26 0.327022 0.0 O-U : basak_buckmorse 0.042203 3.54 0.327022 0.0 13.6765 1.65 2.369 [Potential-Form] A_ij(f0, a,b) = f0*b*exp(a/b) basak_buck(r,f0,a,b,c) = as.buck(r, A_ij(f0,a,b), b, c) basak_morse(r, f0, d, gamma, r_star) = as.morse(r,gamma, r_star, f0*d) basak_buckmorse(r,f0,a,b,c,d,gamma,r_star) = basak_buck(r,f0,a,b,c) + basak_morse(r, f0,d,gamma,r_star)