pyretis.orderparameter package

Definition of order parameters.

This package defines order parameters for use with PyRETIS.

Package structure

Modules

orderparameter.py (pyretis.orderparameter.orderparameter)

Defines the base class for order parameters and some simple example order parameters.

orderangle.py (pyretis.orderparameter.orderangle)

Defines a class for an angle order parameter.

orderdihedral.py (pyretis.orderparameter.orderdihedral)

Defines a class for a dihedral angle order parameter.

Important methods defined here

order_factory (order_factory())

A method to create order parameters from settings.

pyretis.orderparameter.order_factory(settings)

Create order parameters according to the given settings.

This function is included as a convenient way of setting up and selecting the order parameter.

Parameters:settings (dict) – This defines how we set up and select the order parameter. Returns:out (object like OrderParameter) – An object representing the order parameter.

List of submodules

• pyretis.orderparameter.orderangle
• pyretis.orderparameter.orderdihedral
• pyretis.orderparameter.orderparameter

pyretis.orderparameter.orderangle module

This file contains classes to represent angle order parameters.

Important classes defined here

Angle (Angle)

An angle defined by three atoms.

class pyretis.orderparameter.orderangle.Angle(index, periodic=False)

Bases: OrderParameter

An angle order parameter.

This class defines an order parameter which is an angle ABC for 3 particles A, B and C. The angle is defined as the angle given by the two vectors BA and BC.

index

These are the indices of atoms to be used for the angle, i.e. system.particles.pos[index] will be used.

Type:list of integers

periodic

This determines if periodic boundaries should be applied to the positions/distances.

Type:boolean

__init__(index, periodic=False)

Initialise the order parameter.

Parameters:

• index (list/tuple of integers) – The indices for the atoms defining the angle.
• periodic (boolean, optional) – This determines if periodic boundary conditions should be applied to the distance vectors.

calculate(system)

Calculate the angle.

Parameters:system (object like System) – Object containing the positions and box info we use for the calculation. Returns:out (list of floats) – The order parameters.

pyretis.orderparameter.orderdihedral module

Definition of a dihedral order parameter.

Important classes defined here

Dihedral (Dihedral)

A dihedral angle order parameter.

class pyretis.orderparameter.orderdihedral.Dihedral(index, periodic=False)

Bases: OrderParameter

Calculates the dihedral angle defined by 4 atoms.

The angle definition is given by Blondel and Karplus, J. Comput. Chem., vol. 17, 1996, pp. 1132–1141. If we label the 4 atoms A, B, C and D, then the angle is given by the vectors u = A - B, v = B - C, w = D - C

index

These are the indices for the atoms to use in the definition of the dihedral angle.

Type:list/tuple of integers

periodic

This determines if periodic boundaries should be applied to the position or not.

Type:boolean

__init__(index, periodic=False)

Initialise the order parameter.

Parameters:

• index (list/tuple of integers) – This list gives the indices for the atoms to use in the definition of the dihedral angle.
• periodic (boolean, optional) – This determines if periodic boundary conditions should be applied to the distance vectors.

calculate(system)

Calculate the dihedral angle.

Parameters:system (object like System) – The object containing the information we need to calculate the order parameter. Returns:out (list of float) – The order parameter.

pyretis.orderparameter.orderparameter module

This file contains classes to represent order parameters.

The order parameters are assumed to all be completely determined by the system properties and they will all return at least one value - the order parameter itself. The order parameters can also return several order parameters which can be used for further analysis.

Important classes defined here

OrderParameter (OrderParameter)

Base class for the order parameters.

Position (Position)

An order parameter equal to the position of a particle.

Velocity (Velocity)

An order parameter equal to the velocity of a particle.

Distance (Distance)

A class for a particle-particle distance order parameter.

Distancevel (Distancevel)

A class for the rate of change in a particle-particle distance order parameter.

CompositeOrderParameter (CompositeOrderParameter)

A class for an order parameter which is made up of several order parameters, i.e. of several objects like OrderParameter.

PositionVelocity (PositionVelocity)

An order parameter which is equal to the composition of Position and Velocity.

DistanceVelocity (DistanceVelocity)

An order parameter which is equal to the composition of Distance and Distancevel.

class pyretis.orderparameter.orderparameter.CompositeOrderParameter(order_parameters=None)

Bases: OrderParameter

A composite order parameter.

This class represents a composite order parameter. It does not actually calculate order parameters itself, but it has references to several objects like OrderParameter which it can use to obtain the order parameters. Note that the first one of these objects will be interpreted as the main progress coordinate in path sampling simulations.

extra

This is a list of order parameters to calculate.

Type:list of objects like OrderParameter

__init__(order_parameters=None)

Set up the composite order parameter.

Parameters:order_parameters (list of objects like OrderParameter) – A list of order parameters we can add.

__str__()

Return a simple string representation of the order parameter.

add_orderparameter(order_function)

Add an extra order parameter to calculate.

Parameters:order_function (object like OrderParameter) – An object we can use to calculate the order parameter. Returns:out (boolean) – Return True if we added the function, False otherwise.

calculate(system)

Calculate the main order parameter and return it.

This is defined as a method just to ensure that at least this method will be defined in the different order parameters.

Parameters:system (object like System) – This object contains the information needed to calculate the order parameter. Returns:out (list of floats) – The order parameter(s). The first order parameter returned is assumed to be the progress coordinate for path sampling simulations.

property index

Get only the index that is tracked by the orderparameter.

load_restart_info(info)

Load the mutable attributes for restart.

mirror()

Mirrors all of the functions that allow it.

restart_info()

Return the mutable attributes for restart.

class pyretis.orderparameter.orderparameter.Distance(index, periodic=True)

Bases: OrderParameter

A distance order parameter.

This class defines a very simple order parameter which is just the scalar distance between two particles.

index

These are the indices used for the two particles. system.particles.pos[index[0]] and system.particles.pos[index[1]] will be used.

Type:tuple of integers

periodic

This determines if periodic boundaries should be applied to the distance or not.

Type:boolean

__init__(index, periodic=True)

Initialise order parameter.

Parameters:

• index (tuple of ints) – This is the indices of the atom we will use the position of.
• periodic (boolean, optional) – This determines if periodic boundary conditions should be applied to the position.

calculate(system)

Calculate the order parameter.

Here, the order parameter is just the distance between two particles.

Parameters:system (object like System) – The object containing the positions and box used for the calculation. Returns:out (list of floats) – The distance order parameter.

class pyretis.orderparameter.orderparameter.DistanceVelocity(index, periodic=True)

Bases: CompositeOrderParameter

An order parameter equal to a distance and its rate of change.

__init__(index, periodic=True)

Initialise the order parameter.

Parameters:

• index (tuple of integers) – These are the indices used for the two particles. system.particles.pos[index[0]] and system.particles.pos[index[1]] will be used.
• periodic (boolean, optional) – This determines if periodic boundary conditions should be applied to the position.

class pyretis.orderparameter.orderparameter.Distancevel(index, periodic=True)

Bases: OrderParameter

A rate of change of the distance order parameter.

This class defines a very simple order parameter which is just the time derivative of the scalar distance between two particles.

index

These are the indices used for the two particles. system.particles.pos[index[0]] and system.particles.pos[index[1]] will be used.

Type:tuple of integers

periodic

This determines if periodic boundaries should be applied to the distance or not.

Type:boolean

__init__(index, periodic=True)

Initialise the order parameter.

Parameters:

• index (tuple of ints) – This is the indices of the atom we will use the position of.
• periodic (boolean, optional) – This determines if periodic boundary conditions should be applied to the position.

calculate(system)

Calculate the order parameter.

Here, the order parameter is just the distance between two particles.

Parameters:system (object like System) – The object containing the positions and box used for the calculation. Returns:out (list of floats) – The rate-of-change of the distance order parameter.

class pyretis.orderparameter.orderparameter.OrderParameter(description='Generic order parameter', velocity=False)

Bases: object

Base class for order parameters.

This class represents an order parameter and other collective variables. The order parameter is assumed to be a function that can uniquely be determined by the system object and its attributes.

description

This is a short description of the order parameter.

Type:string

velocity_dependent

This flag indicates whether or not the order parameter depends on the velocity direction. If so, we need to recalculate the order parameter when reversing trajectories.

Type:boolean

__init__(description='Generic order parameter', velocity=False)

Initialise the OrderParameter object.

Parameters:description (string) – Short description of the order parameter.

__str__()

Return a simple string representation of the order parameter.

abstract calculate(system)

Calculate the order parameter (or collective variable).

The same interface is used both for the main order parameter and for additional collective variables: each call returns the per-frame value(s) of the quantity. Implementations may return a single scalar, a numpy.ndarray, a tuple, or a list. When loaded through pyretis.setup.common.create_orderparameter() or wrapped via wrap_orderparameter(), the return value is normalised to a plain Python list of scalars by normalize_order_output(). Downstream code therefore always sees system.order and phasepoint.order as a list whose first element is the progress coordinate used by path-sampling moves.

Parameters:system (object like System) – This object contains the information needed to calculate the order parameter. Returns:out (scalar, list, tuple, or numpy.ndarray) – The order-parameter (or collective-variable) value(s). After normalisation the first element is used as the progress coordinate in path-sampling simulations and any additional elements are stored alongside it.

load_restart_info(info)

Load the order parameter restart info.

restart_info()

Save any mutable parameters for the restart.

class pyretis.orderparameter.orderparameter.Permeability(index, dim='z', offset=0.0, mirror_pos=0.0, relative=True)

Bases: Position

A positional order parameter for calculating parmeability.

This class defines a very simple order parameter which is just the position of a given particle, but it allows for the mirror move.

index

This is the index of the atom which will be used, i.e. system.particles.pos[index] will be used.

Type:integer

dim

This is the dimension of the coordinate to user: 0, 1 or 2 for ‘x’, ‘y’ or ‘z’.

Type:integer

periodic

This determines if periodic boundaries should be applied to the position or not.

Type:boolean

offset

The offset to apply before returning, l(x) = pos(x+offset). This allows for effectively moving the periodic boundary position. Should be defined in the same space as this order parameter (relative or not).

Type:float

mirror_pos

The position of the mirror plane around which we mirror when the mirror function is called. Should be defined in the same space as this order parameter (relative or not).

Type:float

relative

If we should map the position to be relative to the box-vector. Defaults to True as that is the only correct option for NPT. For NVT sampling it can be set to False.

Type:boolean

__init__(index, dim='z', offset=0.0, mirror_pos=0.0, relative=True)

Initialise the order parameter.

Parameters:

• index (int) – This is the index of the atom we will use the position of.
• dim (string) – This select what dimension we should consider, it should equal ‘x’, ‘y’ or ‘z’.
• offset (float,) – The offset to add to the position, used to change the effective location of the periodic boundary.
• mirror_pos (float) – The value of the position to mirror around. Allowing for the mirror move.
• relative (boolean) – This determines if the position is returned as a relative value to the box size.

calculate(system)

Calculate the compute_s order parameter and alters it.

Parameters:system (object like System) – The object containing the positions. Returns:out (list of floats) – The position order parameter.

calculate_s(system)

Calculate a value that we the alter in the calculate function.

Parameters:system (object like System) – The object containing the positions. Returns:out (list of floats) – The position order parameter.

load_restart_info(info)

Load the mutable attributes from restart.

mirror()

Swap this object around the mirror plane.

restart_info()

Return the mutable attributes for the restart.

class pyretis.orderparameter.orderparameter.PermeabilityMinusOffset(index, dim='z', offset=0.0, mirror_pos=0.0, relative=True)

Bases: Permeability

A positional order parameter for calculating parmeability - offset.

calculate(system)

Calculate the permeability op and subtract the offset.

class pyretis.orderparameter.orderparameter.Position(index, dim='x', periodic=False, description=None)

Bases: OrderParameter

A positional order parameter.

This class defines a very simple order parameter which is just the position of a given particle.

index

This is the index of the atom which will be used, i.e. system.particles.pos[index] will be used.

Type:integer

dim

This is the dimension of the coordinate to use. 0, 1 or 2 for ‘x’, ‘y’ or ‘z’.

Type:integer

periodic

This determines if periodic boundaries should be applied to the position or not.

Type:boolean

__init__(index, dim='x', periodic=False, description=None)

Initialise the order parameter.

Parameters:

• index (int) – This is the index of the atom we will use the position of.
• dim (string) – This select what dimension we should consider, it should equal ‘x’, ‘y’ or ‘z’.
• periodic (boolean, optional) – This determines if periodic boundary conditions should be applied to the position.

calculate(system)

Calculate the position order parameter.

Parameters:system (object like System) – The object containing the positions. Returns:out (list of floats) – The position order parameter.

class pyretis.orderparameter.orderparameter.PositionVelocity(index, dim='x', periodic=False)

Bases: CompositeOrderParameter

An order parameter equal to the position & velocity of a given atom.

__init__(index, dim='x', periodic=False)

Initialise the order parameter.

Parameters:

• index (int) – This is the index of the atom we will use the position and velocity of.
• dim (string) – This select what dimension we should consider, it should equal ‘x’, ‘y’ or ‘z’.
• periodic (boolean, optional) – This determines if periodic boundary conditions should be applied to the position.

class pyretis.orderparameter.orderparameter.Velocity(index, dim='x')

Bases: OrderParameter

Initialise the order parameter.

This class defines a very simple order parameter which is just the velocity of a given particle.

index

This is the index of the atom which will be used, i.e. system.particles.vel[index] will be used.

Type:integer

dim

This is the dimension of the coordinate to use. 0, 1 or 2 for ‘x’, ‘y’ or ‘z’.

Type:integer

__init__(index, dim='x')

Initialise the order parameter.

Parameters:

• index (int) – This is the index of the atom we will use the velocity of.
• dim (string) – This select what dimension we should consider, it should equal ‘x’, ‘y’ or ‘z’.

calculate(system)

Calculate the velocity order parameter.

Parameters:system (object like System) – The object containing the velocities. Returns:out (list of floats) – The velocity order parameter.

pyretis.orderparameter.orderparameter._verify_pair(index)

Check that the given index contains a pair.

pyretis.orderparameter.orderparameter.expand_order_names(name, count, default_prefix='op', start_index=1)

Expand an order-parameter name into count per-element labels.

The naming convention is shared by the main order parameter and any collective variable: each calculate() returns a list with count entries and this function produces one label per entry.

Parameters:

• name (str, list/tuple of str, or None) – The user-provided name. When None the labels are always "<default_prefix>_<i>". When name is a string and count > 1 the labels are "<name>_1", "<name>_2", ...; when count == 1 the bare name is used. When name is a list or tuple its length must equal count.
• count (int) – Number of labels to produce (the number of values returned by calculate() for this order parameter or collective variable).
• default_prefix (str, optional) – Prefix used to build labels when name is None. Use "op" for the main order parameter and "cv" for any collective variable.
• start_index (int, optional) – Starting index used when generating "<prefix>_<i>" labels. Useful for combining several blocks into one continuous index space.

Returns:

out (list of str) – A list of length count.

Raises:

ValueError – If count is not a positive integer, if name is a sequence whose length differs from count, or if name is of an unsupported type.

pyretis.orderparameter.orderparameter.normalize_order_output(order, klass_name='unknown')

Normalise the return value of calculate() to a flat list.

This function accepts the raw return value from any calculate implementation — a scalar, a 0-D or 1-D numpy.ndarray, a list, or a tuple — and returns a plain Python list whose elements are all plain Python scalars (no nested lists or arrays).

Parameters:

• order (scalar, list, tuple, or numpy.ndarray) – The raw return value from a calculate method.
• klass_name (str, optional) – Name of the order-parameter class; used only in error messages.

Returns:

out (list of floats) – A flat list of scalar values.

Raises:

ValueError – If order is a >1-D array or contains nested sequences.

pyretis.orderparameter.orderparameter.wrap_orderparameter(instance)

Wrap an OP instance so calculate() always returns a list.

The wrapper is idempotent: calling this function twice on the same instance is safe and has no additional effect.

Parameters:instance (object with a calculate method) – Any order-parameter object (internal or external). Returns:instance (same object, mutated in place.)