The Potential section¶

The potential section specifies a single potential function to add to the force field.

Example Potential section:

potential = [
    { class = "DoubleWell", parameter = { a = 1.0, b = 2.0, c = 0.0 } },
]

In order to add several potential functions to a force field, several [[potential]] tables can be added:

Example Potential section:

[[potential]]
class = "PairLennardJonesCutnp"
shift = true
dim = 2
mixing = "geometric"

[potential.parameter.0]
sigma = 1.0
epsilon = 1.0
factor = 1.12246205

[potential.parameter.1]
sigma = 1.0
epsilon = 1.0
factor = 1.12246205

[[potential]]
class = "DoubleWellWCA"
dim = 2

[potential.parameter]
rzero = 1.122462048309373
height = 15.0
width = 0.5
types = [
    [
        1,
        1,
    ],
]

As the different potentials typically require different settings, detailed information can be found below for specific potentials:

The DoubleWell potential ¶

This class defines a one-dimensional double well potential. The potential energy (\(V_\text{pot}\)) is given by

\[V_\text{pot} = a x^4 - b (x - c)^2\]

where \(x\) is the position and \(a\), \(b\) and \(c\) are parameters for the potential.

Example Potential section for DoubleWell:

potential = [
    { class = "DoubleWell", parameter = { a = 1.0, b = 2.0, c = 0.0 } },
]

Keywords for the DoubleWell potential ¶

The following keywords can be specified for the DoubleWell potential:

Table 16 Keywords for the DoubleWell potential.¶
Keyword	Description
class	Selects the DoubleWell potential.
parameter	Sets the parameters for the potential.

Keyword class ¶

class = DoubleWell

This keyword selects the potential and should be set to: DoubleWell.

Keyword parameter ¶

For the DoubleWell potential, three parameters can be specified:

parameter a = float

The a parameter in the potential energy function given above.

Default:: The default is a = 1.0.

parameter b = float

The b parameter in the potential energy function given above.

Default:: The default is b = 1.0.

parameter c = float

The c parameter in the potential energy function given above.

Default:: The default is c = 0.0.

The RectangularWell potential ¶

This class defines a one-dimensional rectangular well potential. The potential energy is zero within the potential well and infinite outside. The well is defined with a left and right boundary.

Example Potential section for RectangularWell:

potential = [
    { class = "RectangularWell", parameter = { left = -1.0, right = 1.0 } },
]

Keywords for the RectangularWell potential ¶

The following keywords can be specified for the RectangularWell potential:

Table 17 Keywords for the RectangularWell potential.¶
Keyword	Description
class	Selects the RectangularWell potential.
parameter	Sets the parameters for the potential.

Keyword class ¶

class = RectangularWell

This keyword selects the potential and should be set to: RectangularWell.

Keyword parameter ¶

For the RectangularWell potential, two parameters can be set.

parameter left = float

The left border for the potential well function. The potential energy is 0 for positions \(x\) such that \(\text{left} < x < \text{right}\).

Default:: The default is left = 0.0.

parameter right = float

The right border for the potential well function. The potential energy is 0 for positions \(x\) such that \(\text{left} < x < \text{right}\).

Default:: The default is right = 1.0.

The PairLennardJonesCutnp potential ¶

This class implements as simple Lennard-Jones 6-12 potential which employs a simple cut-off and can be shifted. The potential energy (\(V_\text{pot}\)) is defined in the usual way for an interacting pair \((i,j)\) of particles a distance \(r\) apart,

\[V_\text{pot} = 4 \varepsilon_{ij} \left( x^{12} - x^{6} \right),\]

where \(x = \sigma_{ij}/r\) and \(\varepsilon_{ij}\) and \(\sigma_{ij}\) are the potential parameters.

Example Potential section for PairLennardJonesCutnp:

Here is an example for defining parameters for a mixture of 3 particle types with geometric mixing.

[[potential]]
class = "PairLennardJonesCutnp"
shift = true
dim = 3
mixing = "geometric"

[potential.parameter.0]
sigma = 1.0
epsilon = 1.0
rcut = 2.5

[potential.parameter.1]
sigma = 1.2
epsilon = 1.1
rcut = 2.5

[potential.parameter.2]
sigma = 1.4
epsilon = 0.9
rcut = 2.5

Keywords for the PairLennardJonesCutnp potential ¶

The following keywords can be specified for the PairLennardJonesCutnp potential:

Table 18 Keywords for the PairLennardJonesCutnp potential.¶
Keyword	Description
class	Selects the potential.
dim	Set the number of dimensions to consider.
shift	Determines if the potential should be shifted.
mixing	Selects the mixing rules for generating parameters for cross interactions.
parameter	Sets the parameters for the potential.

Keyword class ¶

class = PairLennardJonesCutnp

This keyword selects the potential and should be set to: PairLennardJonesCutnp.

Keyword dim ¶

dim = integer

Sets the dimensionality for the potential. Should be 1, 2, or 3 for 1D, 2D or 3D, respectively.

Default:: The default value is dim = 3.

Keyword shift ¶

shift = boolean

Determines if the potential should be shifted or not. This should be either true (enables shifting) or false (disables shifting). If shifting is true, the following value is subtracted from the potential (for a given \((i, j)\) pair), which makes it zero at the cut-off:

\[V_{\text{shift}} = 4 \varepsilon_{ij} \left( x_{\text{c}}^{12} - x_{\text{c}}^{6} \right),\]

where \(x_{\text{c}} = \sigma_{ij} / r_{\text{c}, ij}\) and \(r_{\text{c}, ij}\) is the cut-off.

Default:: The default value is shift = true.

Keyword mixing ¶

mixing = string

Determines how the parameters of a pair of two different particle types \((i, j)\) are obtained from the parameters of each type. The supported mixing rules are:

mixing = "geometric":
- \(\epsilon_{ij} = \sqrt{\epsilon_{i} \times \epsilon_{j}}\)
- \(\sigma_{ij} = \sqrt{\sigma_{i} \times \sigma_{j}}\)
- \(r_{\text{c},ij} = \sqrt{r_{\text{c},i} \times r_{\text{c},j}}\)
mixing = "arithmetic":
- \(\epsilon_{ij} = \sqrt{\epsilon_{i} \times \epsilon_{j}}\)
- \(\sigma_{ij} = \frac{\sigma_{i} + \sigma_{j}}{2}\)
- \(r_{\text{c},ij} = \frac{r_{\text{c},i} + r_{\text{c},j}}{2}\)
mixing = "sixthpower":
- \(\epsilon_{ij} = 2 \sqrt{\epsilon_{i} \times \epsilon_{j}} \frac{\sigma_i^3 \times \sigma_j^3}{\sigma_i^6 + \sigma_j^6}\)
- \(\sigma_{ij} = \left( \frac{\sigma_{i}^6 + \sigma_{j}^6}{2} \right)^{1/6}\)
- \(r_{\text{c},ij} = \left(\frac{r_{\text{c},i}^6 + r_{\text{c},j}^6}{2}\right)^{1/6}\)

The value is one of these three, in lower case. The settings parse refuses any other value, "Sixthpower" among them, in a [[potential]] section of a PyRETIS potential (a section with no module key), and the message names the three values. A PairLennardJonesCut (or a subclass, such as the potential of a user module) refuses it when it is created, and generate_pair_interactions() checks it even when the parameters give every cross pair. An rst input that sets mixing = None gives no mixing key, as for any key set to None: the run uses the default, "geometric".

Default: The default value is mixing = "geometric".

Keyword parameter ¶

The following parameters can be set for the PairLennardJonesCutnp potential:

parameter i = dictionary

The parameters for the PairLennardJonesCutnp potentials are given for each particle type on the form:

[[potential]]
class = "PairLennardJonesCutnp"

[potential.parameter.0]
sigma = 1.0
epsilon = 1.0
rcut = 2.5

Where i is the particle type, identified as an integer. Here, sigma is \(\sigma_i\), epsilon is \(\varepsilon_i\) and rcut is \(r_{\text{c},i}\).

Note that several parameters can be given in this way and that they will be combined according to the selected mixing rule.

The DoubleWellWCA potential ¶

This class defines a n-dimensional Double Well potential. The potential energy (\(V_\text{pot}\)) for a pair of particles separated by a distance \(r\) is given by,

\[V_\text{pot} = h (1 - (r - r_0 - w)^2/w^2)^2,\]

where \(h\) gives the ‘height’ of the potential, \(r_0\) the minimum and \(w\) the width.

Example Potential section for DoubleWellWCA:

[[potential]]
class = "DoubleWellWCA"
dim = 2

[potential.parameter]
rzero = 1.122462048309373
height = 6.0
width = 0.25
types = [
    [
        1,
        1,
    ],
]

Keywords for the DoubleWellWCA potential ¶

The following keywords can be specified for the DoubleWellWCA potential:

Table 19 Keywords for the DoubleWellWCA potential¶
Keyword	Description
class	Selects the potential.
dim	Sets the number of dimensions to consider.
parameter	Sets the parameters for the potential.

Keyword class ¶

class = DoubleWellWCA

Selects the potential, should be set to: DoubleWellWCA.

Keyword dim ¶

dim = integer

Sets the dimensionality for the potential. Should be 1, 2, or 3 for 1D, 2D or 3D, respectively.

Default:: The default value is dim = 3.

Keyword parameter ¶

The following parameters can be set for the DoubleWellWCA potential:

parameter rzero = float

This is the \(r_0\) parameter in the potential energy function given above.

Default: The default is rzero = 0

parameter height = float

This is the \(h\) parameter in the potential energy function given above.

Default: The default is height = 0

parameter width = float

This is the \(w\) parameter in the potential energy function given above.

Default: The default is width = 0

parameter types = list of lists of integers

The pairs of particle types the interaction acts on. For example, types = [[1, 2]] turns the interaction on between particles of type 1 and type 2 only. (See the particle section for a description of the particle type.) Several pairs can be given at the same time: types = [[1, 2], [0, 1], [0, 2]].

Default: No pair: without types, the interaction acts on no pair of particles, and this potential adds no energy and no force.

User-defined potential functions ¶

User-defined potential functions are selected as follows:

Example Potential section for a user-defined class:

[[potential]]
class = "PotentialName"
module = "potential.py"
keyword1 = "value"

[potential.parameter]
p = 123.0

Here, the user can both define custom keywords and parameters. However, the class and the module must always be specified in this case.

Keywords for user-defined potential functions ¶

At least, the following keywords can be specified for user-defined potential functions:

Table 20 Keywords for user.defined potential functions.¶
Keyword	Description
class	Selects the Python class which implements the potential.
module	Defines the file where the Python class with the potential can be found.

Keyword class ¶

class = string

This keyword selects the potential function and it should be set to the class name of the custom potential function class defined in the given module.

Keyword module ¶

module = string

This keyword specified the location of the file containing the user-defined class for the potential function. This file must be accessible by PyRETIS.

Default: Not any. This keyword must be specified.