The orderparameter section¶

The orderparameter section defines which order parameter to use for a path sampling simulation.

Example Orderparameter section:

[orderparameter]
class = "pyretis_distance"
index = [
    0,
    1,
]
periodic = false

Important

Every order parameter that ships with PyRETIS has a name beginning pyretis_: pyretis_position, pyretis_distance, and so on. The bare names are not accepted.

The prefix exists to keep your order parameters apart from ours. A class called Position or Distance is exactly what you are likely to write for your own system, and without the prefix PyRETIS would quietly hand you the built-in instead of your class – a simulation that runs perfectly and measures the wrong thing. Using a bare name now stops the run with an error naming the built-in you may have meant.

Your own order parameters keep whatever name you like; they are selected by naming the file they live in with a module key, and are never confused with a built-in.

Different order parameters require different settings and this is described in detail below for the different types:

Order parameter Position ¶

This order parameter is defined as the position of a single particle in a specified dimension. It is defined by specifying the class pyretis_position, selecting the index of the particle to use, dimension to consider and whether to consider periodic boundaries:

Example Orderparameter section for Position:

[orderparameter]
class = "pyretis_position"
index = 0
dim = "x"
periodic = false

Keywords for order parameter Position ¶

The following keywords can be set for order parameter Position:

Table 30 Keywords for the Position order parameter.¶
Keyword	Description
class	Selects the Position order parameter.
index	Selects the particle to use.
dim	Selects the dimension to consider for the position.
periodic	Determines if periodic boundaries should be used.

Keyword class ¶

class = pyretis_position

Selects the order parameter, should be set to pyretis_position.

Keyword index ¶

index = integer

The index selects the particle to use. The particles are numbered sequentially, from 0, in the sequence they appear in the input to PyRETIS.

Default:: Not any. This keyword must be specified.

Keyword dim ¶

dim = string

The dimension to consider for the position. This can be one of:

"x": For the x-coordinate of the particle
"y": For the y-coordinate of the particle
"z": For the z-coordinate of the particle

Default:: The default is dim = "x".

Keyword periodic ¶

periodic = boolean

This keyword determines if we should apply periodic boundaries to the position or not. If it is set to true periodic boundaries will be applied.

Default:: The default is: periodic = false

Order parameter Distance ¶

This order parameter is defined as the distance between two particles. It is defined by selecting the class pyretis_distance, selecting the indices of the particles to consider and then determining if periodic boundaries should be used or not:

Example Orderparameter section for Distance:

[orderparameter]
class = "pyretis_distance"
index = [
    10,
    11,
]
periodic = true

Keywords for order parameter Distance ¶

The following keywords can be set for order parameter Distance:

Table 31 Keywords for the Distance order parameter.¶
Keyword	Description
class	Selects the Distance order parameter.
index	Selects the particles to use for the distance.
periodic	Determines if periodic boundaries should be applied.

Keyword class ¶

class = pyretis_distance

Selects the order parameter, should be set to pyretis_distance.

Keyword index ¶

index = tuple of integers

The index selects the particles to use. The particles are numbered sequentially, from 0, in the sequence they appear in the input to PyRETIS. The two indices are given as a list: index = [0, 1].

Default:: Not any. This keyword must be specified.

Keyword periodic ¶

periodic = boolean

This keyword determines if we should apply periodic boundaries to the distance or not. If it is set to true periodic boundaries will be applied.

Default:: The default is: periodic = true.

User-defined order parameters ¶

You can also define custom order parameters to use with PyRETIS. Such order parameters should subclass the generic OrderParameter class as described in the user guide.

Example Orderparameter section for a user-defined order parameter:

[orderparameter]
class = "WCAJCP1"
module = "../orderp/orderp.py"
index = [
    7,
    8,
]
periodic = true

Keywords for user-defined order parameters ¶

At least the following keywords can be set for user-defined order parameters:

Table 32 Keywords for user-defined order parameters.¶
Keyword	Description
class	Selects a Python class to use as the order parameter.
module	Defines the module where the Python class can be located.

In addition, user-defined keywords can be specified, e.g.:

Example Orderparameter section for a user-defined order parameter:

[orderparameter]
class = "MyOrderParameter"
module = "order.py"
setting1 = "input"
setting3 = 123.456
setting2 = true

In the example the file order.py shall contain the class MyOrderParameter. The class can use the PyRETIS system object, which contains the various information to compute the order parameter(s) (position, velocities, etc). Furthermore, with a GROMACS, CP2K or LAMMPS engine, the name of the file that holds the frame the order parameter is computed for is system.config[0], and the index of the frame in that file is system.config[1], which can be None for a file that holds a single frame. In a LAMMPS dump, the index is the time step of the frame, as its ITEM: TIMESTEP line gives it (in the dumps of a run, the number of the frame times subcycles).

Keyword class ¶

class = string

This keyword selects the order parameter and it should be set to the class name of the custom order parameter 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 order parameter. This file must be accessible by PyRETIS.

Default: Not any. This keyword must be specified.