pyretis.core¶

This package defines the core PyRETIS tools.

The core tools are intended to define classes which are used in simulations.

Package structure¶

Modules¶

__init__.py: Import core functions from the modules.
box.py (pyretis.core.box): Definition of the simulation box class.
common.py (pyretis.core.common): Some common core methods, for instance for initiating classes.
montecarlo.py (pyretis.core.montecarlo): This module defines methods for performing Monte Carlo moves.
particlefunctions.py (pyretis.core.particlefunctions): Functions that operate on (a selection of) particles, for instance calculation of the kinetic temperature, pressure, momentum etc.
particles.py (pyretis.core.particles): Definition of the particle class which is used to represent a collection of particles.
pathensemble.py (pyretis.core.pathensemble): Definition of a class for a collection of paths (i.e. a path ensemble).
path.py (pyretis.core.path): This module defines functions and classes for paths.
properties.py (pyretis.core.properties): This module defines a class for a generic property.
random_gen.py (pyretis.core.random_gen): This module defines a class for generating random numbers.
system.py (pyretis.core.system): This module defines the system class which connects different parts (for instance box, forcefield and particles) into a single structure.
units.py (pyretis.core.units): This module defines conversion between units.

Important classes defined in this package¶

BoxBase (BoxBase): A base class for a simulation box. The box will also handle the periodic boundaries.
System (System): A class which defines the system we are working with. This class contain a lot of information and is used to group the information into a structure which the simulations will make use of. Typically the system will contain a reference to a box, a list of particles and also a force field.
Particles (Particles): A class defining a list of particles. This will contain the positions, velocities and forces for the particles.
Path (Path): A class representing a path. The path contains snapshots with some additional information (energies and order parameters).
PathEnsemble (PathEnsemble): A class representing a collection of paths. The path ensemble will not store the full trajectories, but only a simplified representation.
PathEnsembleExt (PathEnsembleExt): A class representing external path ensembles. This handles additional bookkeeping related to external paths.
RandomGenerator (RandomGenerator): A class for generating random numbers.

pyretis.core.box module¶

Definition of a class for a simulation box.

The simulation box handles the periodic boundaries if needed. It is typically referenced via the System class, i.e. as System.box.

Important classes defined here¶

BoxBase (BoxBase): Class for a simulation box.
RectangularBox (RectangularBox): Class representing a rectangular simulation box.
TriclinicBox (TriclinicBox): Class representing a triclinic simulation box.

Examples

>>> from pyretis.core.box import create_box

>>> box = create_box(cell=[10, 10, 10], periodic=[True, False, True])

pyretis.core.box.angles_from_box_matrix(box_matrix)[source]¶

Obtain angles and lengths from a given box matrix.

Parameters:

box_matrix (np.array) – The box matrix (2D).

Returns:

length (numpy.array) – 1D array, the box-lengths on form [a, b, c].
alpha (float) – The alpha angle, in degrees.
beta (float) – The beta angle, in degrees.
gamma (float) – The gamma angle, in degrees.

pyretis.core.box.box_matrix_to_list(matrix, full=False)[source]¶

Return a list representation of the box matrix.

This method ensures correct ordering of the elements for PyRETIS: xx, yy, zz, xy, xz, yx, yz, zx, zy.

Parameters:

matrix (numpy.array) – A matrix (2D) representing the box.
full (boolean, optional) – Return a full set of parameters (9) if set to True. If False, and we need 3 or fewer parameters (i.e. the other 6 are zero) we will only return the 3 non-zero ones.

Returns:

out (list) – A list with the box-parametres.

pyretis.core.box.box_vector_angles(length, alpha, beta, gamma)[source]¶

Obtain the box matrix from given lengths and angles.

Parameters:

length (numpy.array) – 1D array, the box-lengths on form [a, b, c].
alpha (float) – The alpha angle, in degrees.
beta (float) – The beta angle, in degrees.
gamma (float) – The gamma angle, in degrees.

Returns:

out (numpy.array, 2D) – The (upper triangular) box matrix.

pyretis.core.box.check_consistency(low, high, length)[source]¶

Check that given box bounds are consistent.

Parameters:

low (numpy.array) – The lower bounds for the box.
high (numpy.array) – The upper bounds for the box.
length (numpy.array) – The lengths of the box.

pyretis.core.box.create_box(low=None, high=None, cell=None, periodic=None)[source]¶

Set up and create a box.

Parameters:

low (numpy.array, optional) – 1D array containing the lower bounds of the cell.
high (numpy.array, optional) – 1D array containing the higher bounds of the cell.
cell (numpy.array, optional) – 1D array, a flattened version of the simulation box matrix. This array is expected to contain 1, 2, 3, 6 or 9 items. These are the xx, yy, zz, xy, xz, yx, yz, zx, zy elements, respectively.
periodic (list of boolean, optional) – If periodic[i] then we should apply periodic boundaries to dimension i.

Returns:

out (object like BoxBase) – The object representing the simulation box.

pyretis.core.common module¶

Definition of some common methods that might be useful.

Important methods defined here¶

bit_fat_comparer (:py:func`.big_fat_comparer`): Method to compare two nested list/dictionaries.
compare_objects (:py:func`.compare_objects`): Method to compare two PyRETIS objects.
counter (:py:func`.counter`): Function to count the number of iterations.
crossing_counter (:py:func`.crossing_counter`): Function to count the crossing of a path on an interface.
crossing_finder (:py:func`.crossing_finder`): Function to get the shooting points of the crossing of a path on an interface.
import_from (import_from()): A method to dynamically import method/classes etc. from user specified modules.
inspect_function (inspect_function()): A method to obtain information about arguments, keyword arguments for functions.
initiate_instance (initiate_instance()): Method to initiate a class with optional arguments.
generic_factory (generic_factory()): Create instances of classes based on settings.
null_move (:py:func`.compare_objects`): Method to do not move.
priority_checker (:py:func`.priority_checker`): Method to check ensemble to prioritize.
relative_shoots_select (:py:func`.compare_objects`): Method to select the shooting ensemble.
segments_counter (:py:func`.segments_counter`): Function that counts the number of segments between two interfaces.
trim_path_between_interfaces (:py:func`.trim_path_between_interfaces`): Function to trim a path between interfaces.
select_and_trim_a_segment (:py:func`.select_and_trim_a_segment`): Function to trim a path between interfaces plus the two external points.
compute_weight (compute_weight()): A method to compute the statistical weight of a path generated by a Stone Skipping and Wire Fencing move.
soft_partial_exit (:py:func`.soft_partial_exit`): Function that check the presence of the EXIT file, and kindly stops the iterator.

pyretis.core.common.big_fat_comparer(any1, any2, hard=False)[source]¶

Check if two dictionary are the same, regardless their complexity.

Parameters:

any1 (anything)
any2 (anything)
hard (boolean, optional) – Raise ValueError if any1 and any2 are different

Returns:

out (boolean) – True if any1 = any2, false otherwise

pyretis.core.common.compare_objects(obj1, obj2, attrs, numpy_attrs=None)[source]¶

Compare two PyRETIS objects.

This method will compare two PyRETIS objects by checking the equality of the attributes. Some of these attributes might be numpy arrays in which case we use the numpy_allclose() defined in this module.

Parameters:

obj1 (object) – The first object for the comparison.
obj2 (object) – The second object for the comparison.
attrs (iterable of strings) – The attributes to check.
numpy_attrs (iterable of strings, optional) – The subset of attributes which are numpy arrays.

Returns:

out (boolean) – True if the objects are equal, False otherwise.

pyretis.core.common.compute_weight(path, interfaces, move)[source]¶

Compute the High Acceptance path weight after a MC move.

This function computes the weights that will be used in the computation of the P cross. This trick allows the use of the High Acceptance version of Stone Skipping or Wire Fencing, allowing the acceptance of B to A paths. The drawback is that swapping moves needs to account also for this different weights. The weight 1 will be returned for a path not generated by SS or WF.

Parameters:

path (object like PathBase) – This is the input path which will be checked.
interfaces (list/tuple of floats) – These are the interface positions of the form [left, middle, right].
move (string, optional) – The MC move to compute the weights for.

Returns:

out[0] (float) – The weight of the path.

pyretis.core.common.counter()[source]¶: Return how many times this function is called.

pyretis.core.common.crossing_counter(path, interface)[source]¶

Count the crossing to an interfaces.

Method to count the crosses of a path over an interface.

Parameters:

path (object like PathBase) – Input path which will be trimmed.
interface (float) – The position of the interface.

Returns:

cnt (integer) – Number of crossing of the given interface.

pyretis.core.common.crossing_finder(path, interface, last_frame=False)[source]¶

Find the crossing to an interfaces.

Method to select the crosses of a path over an interface.

Parameters:

path (object like PathBase) – Input path which will be trimmed.
interface (float) – Interface position.
last_frame (boolean, optional) – Determines if the last crossing will be selected or not.

Returns:

ph1, ph2 (snapshots) – Define the randomly picked crossing, one right before and one right after the interface.

pyretis.core.common.generic_factory(settings, object_map, name='generic')[source]¶

Create instances of classes based on settings.

This method is intended as a semi-generic factory for creating instances of different objects based on simulation input settings. The input settings define what classes should be created and the object_map defines a mapping between settings and the class.

Parameters:

settings (dict) – This defines how we set up and select the order parameter.
object_map (dict) – Definitions on how to initiate the different classes.
name (string, optional) – Short name for the object type. Only used for error messages.

Returns:

out (instance of a class) – The created object, in case we were successful. Otherwise, we return none.

pyretis.core.common.import_from(module_path, function_name)[source]¶

Import a method/class from a module.

This method will dynamically import a specified method/object from a module and return it. If the module can not be imported or if we can’t find the method/class in the module we will raise exceptions.

Parameters:

module_path (string) – The path/filename to load from.
function_name (string) – The name of the method/class to load.

Returns:

out (object) – The thing we managed to import.

pyretis.core.common.initiate_instance(klass, settings)[source]¶

Initialise a class with optional arguments.

Parameters:

klass (class) – The class to initiate.
settings (dict) – Positional and keyword arguments to pass to klass.__init__().

Returns:

out (instance of klass) – Here, we just return the initiated instance of the given class.

pyretis.core.common.inspect_function(function)[source]¶

Return arguments/kwargs of a given function.

This method is intended for use where we are checking that we can call a certain function. This method will return arguments and keyword arguments a function expects. This method may be fragile - we assume here that we are not really interested in args and kwargs and we do not look for more information about these here.

Parameters:

function (callable) – The function to inspect.

Returns:

out (dict) – A dict with the arguments, the following keys are defined:

args : list of the positional arguments
kwargs : list of keyword arguments
varargs : list of arguments
keywords : list of keyword arguments

pyretis.core.common.null_move(ensemble, cycle)[source]¶

Perform a null move for a path ensemble.

The null move simply consist of accepting the last accepted path again.

Parameters:

ensemble (dict, it contains:) –
- path_ensembleobject like PathEnsemble
  This is the path ensemble to update with the null move
cycle (integer) – The current cycle number

Returns:

out[0] (boolean) – Should the path be accepted or not? Here, it’s always True since the null move is always accepted.
out[1] (object like PathBase) – The unchanged path.
out[2] (string) – The status will here be ‘ACC’ since we just accept the last accepted path again in this move.

pyretis.core.common.priority_checker(ensembles, settings)[source]¶

Determine the shooting ensemble during a RETIS simulation.

Here we check whether to do priority shooting or not. If True, we either shoot from the ensemble with the fewest paths or ensemble [0^-] if all ensembles have the same no. of paths.

Parameters:

ensembles (list of dictionaries of objects) – Lit of dict of ensembles we are using in a path method.
settings (dict) – This dict contains the settings for the RETIS method.

Returns:

out[0] (list) – Returns a list of boolean dictating whether certain ensembles are to be skipped or not.

pyretis.core.common.relative_shoots_select(ensembles, rgen, relative)[source]¶

Randomly select the ensemble for ‘relative’ shooting moves.

Here we select the ensemble to do the shooting in based on relative probabilities. We draw a random number between 0 and 1 which is used to select the ensemble.

Parameters:

ensembles (list of objects like PathEnsemble) – This is a list of the ensembles we are using in the RETIS method.
rgen (object like RandomGenerator) – This is a random generator. Here we assume that we can call rgen.rand() to draw random uniform numbers.
relative (list of floats) – These are the relative probabilities for the ensembles. We assume here that these numbers are normalised.

Returns:

out[0] (integer) – The index of the path ensemble to shoot in.
out[1] (object like PathEnsemble) – The selected path ensemble for shooting.

pyretis.core.common.segments_counter(path, interface_l, interface_r, reverse=False)[source]¶

Count the directional segment between interfaces.

Method to count the number of the directional segments of the path, along the orderp, that connect FROM interface_l TO interface_r.

Parameters:

path (object like PathBase) – This is the input path which segments will be counted.
interface_r (float) – This is the position of the RIGHT interface.
interface_l (float) – This is the position of the LEFT interface.
reverse (boolean, optional) – Check on a reversed path.

Returns:

n_segments (integer) – Segment counter

pyretis.core.common.select_and_trim_a_segment(path, interface_l, interface_r, segment_to_pick=None)[source]¶

Cut a directional segment from interface_l to interface_r.

It keeps what is within the range [interface_l interface_r) AND the snapshots just after/before the interface.

Parameters:

path (object like PathBase) – This is the input path which will be trimmed.
interface_r (float) – This is the position of the RIGHT interface.
interface_l (float) – This is the position of the LEFT interface.
segment_to_pick (integer (n.b. it starts from 0)) – This is the segment to be selected, None = random

Returns:

segment (object like PathBase) – a path segment composed only the snapshots for which orderp is between interface_r and interface_l and the ones right after/before the interfaces.

pyretis.core.common.soft_partial_exit(exe_path='')[source]¶

Check the presence of the EXIT file.

Parameters:: exe_path (string, optional) – Path for the EXIT file.
Returns:: out (boolean) – True if EXIT is present. False if EXIT in not present.

pyretis.core.common.trim_path_between_interfaces(path, interface_l, interface_r)[source]¶

Cut a path between the two interfaces.

The method cut a path and keeps only what is within the range (interface_l interface_r). -Be careful, it can provide multiple discontinuous segments- =Be carefull2 consider if you need to make this check left inclusive (as the ensemble should be left inclusive)

Parameters:

path (object like PathBase) – This is the input path which will be trimmed.
interface_r (float) – This is the position of the RIGHT interface.
interface_l (float) – This is the position of the LEFT interface.

Returns:

new_path (object like PathBase) – This is the output trimmed path.

pyretis.core.engine_time module¶

Resolve the engine time step for the flux and rate analysis.

The simulation time per PyRETIS step (timestep * subcycles) is the single factor that turns path lengths, counted in integration steps, into times when computing fluxes and rates. The time step belongs to the engine, so this module resolves it the same way for every engine: from the [engine] settings when present, otherwise from the engine’s own input file – as PyRETIS does when it builds the engine.

Important method defined here¶

engine_time_per_step (engine_time_per_step()): Return timestep * subcycles from a settings/run configuration.

pyretis.core.engine_time.engine_time_per_step(settings)[source]¶

Return the simulation time per PyRETIS step from settings.

This is the engine timestep multiplied by its subcycles (defaulting to 1) – the physical time between two recorded path points, in the engine’s own time unit. It is the single factor used to turn path lengths (counted in steps) into times when computing fluxes and rates, so every analysis routine derives it the same way.

The time step belongs to the engine. When it is not present in the [engine] settings (e.g. LAMMPS, which keeps it in the LAMMPS input file), it is recovered from the engine’s own input file – as PyRETIS does when it builds the engine – before giving up.

Parameters:: settings (dict) – The simulation settings, or a loaded run configuration. The engine information is read from the engine section.
Returns:: float or None – timestep * subcycles, or None if the time step cannot be determined from the settings or the engine input (so each caller can decide whether that is an error or a reason to fall back to a per-step quantity).

pyretis.core.engine_time.validate_engine_timestep(given, actual, engine_name)[source]¶

Check a supplied time step against the engine’s own time step.

External engines own their time step in their own input file or integrator, so an [engine] timestep is optional for them. When one is supplied it must agree with the value the engine actually uses – otherwise the simulation and the analysis would silently run with different time steps. This fails loud on a mismatch and does nothing when no time step is supplied.

Parameters:

given (float or None) – The time step from the [engine] settings, or None when it was not supplied.
actual (float) – The time step the engine itself uses (read from its input file or integrator).
engine_name (string) – Name of the engine, used in the error message.

Raises:

ValueError – If given is supplied and differs from actual.

pyretis.core.montecarlo module¶

Module for Monte Carlo Algorithms and other “random” functions.

In this module, Monte Carlo Algorithms are defined. Note that some derived or “random” functions are also defined in the TIS module.

Important methods defined here¶

metropolis_accept_reject (metropolis_accept_reject()): Accept/reject an energy change according to the metropolis rule.
max_displace_step (max_displace_step()): Monte Carlo routine for displacing particles. It will select and displace one particle randomly.

pyretis.core.montecarlo.max_displace_step(rgen, system, maxdx=0.1, idx=None)[source]¶

Monte Carlo routine for displacing particles.

It selects and displaces one particle randomly. If the move is accepted, the new positions and energy are returned. Otherwise, the move is rejected and the old positions and potential energy is returned. The function accept_reject is used to accept/reject the move.

Parameters:

rgen (object like RandomGenerator) – The random number generator.
system (object like System) – The system object to operate on
maxdx (float, optional) – The maximum displacement (default is 0.1).
idx (int, optional) – Index of the particle to displace. If idx is not given, the particle is chosen randomly.

Returns:

out (boolean) – The outcome of applying the function accept_reject to the system and trial position.

pyretis.core.montecarlo.metropolis_accept_reject(rgen, system, deltae)[source]¶

Accept/reject a energy change according to the metropolis rule.

FIXME: Check if metropolis really is a good name here.

Parameters:

rgen (object like RandomGenerator) – The random number generator.
system (object like System) – The system object we are investigating. This is used to access the beta factor.
deltae (float) – The change in energy.

Returns:

out (boolean) – True if the move is accepted, False otherwise.

Notes

An overflow is possible when using numpy.exp() here. This can, for instance, happen in an umbrella simulation where the bias potential is infinite or very large. Right now, this is just ignored.

pyretis.core.particlefunctions module¶

This file contains functions that act on (a selection of) particles.

These functions are intended for calculating particle properties as the kinetic temperature, pressure etc.

Important methods defined here¶

atomic_kinetic_energy_tensor (atomic_kinetic_energy_tensor()): Return the kinetic energy tensor for each atom in a selection of particles.
calculate_kinetic_energy (calculate_kinetic_energy()): Return the kinetic energy of a collection of particles.
calculate_kinetic_energy_tensor (calculate_kinetic_energy_tensor()): Return the kinetic energy tensor for a selection of particles.
calculate_kinetic_temperature (calculate_kinetic_temperature()): Return the kinetic temperature of a collection of particles.
calculate_linear_momentum (calculate_linear_momentum()): Calculates the linear momentum of a collection of particles.
calculate_pressure_from_temp (calculate_pressure_from_temp()): Return the scalar pressure using the temperature and the virial.
calculate_pressure_tensor (calculate_pressure_tensor()): Return the pressure tensor, obtained from the virial and the kinetic energy tensor.
calculate_scalar_pressure (calculate_scalar_pressure()): Return the scalar pressure (from the trace of the pressure tensor).
calculate_thermo (calculate_thermo()): Calculate and return several “thermodynamic” properties as the potential, kinetic and total energies per particle, the temperature, the pressure and the momentum.
calculate_thermo_path (calculate_thermo_path()): Calculate and return some thermodynamic properties. This method is similar to the calculate_thermo, however, it is simpler and calculates fewer quantities.
kinetic_energy (kinetic_energy()): Return the kinetic energy for velocities and masses given as numpy arrays.
kinetic_temperature (kinetic_temperature()): Return the temperature for velocities and masses given as numpy arrays.
reset_momentum (reset_momentum()): Set linear momentum (for a selection of particles) to zero.

pyretis.core.particlefunctions.atomic_kinetic_energy_tensor(particles, selection=None)[source]¶

Return kinetic energy tensors for a particle selection.

Parameters:

particles (object like Particles) – This object represents the particles.
selection (list of integers, optional) – A list with indices of particles to use in the calculation.

Returns:

kin (numpy.array) – A numpy array with dimensionality equal to (len(selection), dim, dim) where dim is the number of dimensions used in the velocities. kin[i] contains the kinetic energy tensor formed by the outer product of mol[selection][i] and vel[selection][i]. The sum of the tensor should equal the output from calculate_kinetic_energy_tensor.

pyretis.core.particlefunctions.calculate_beta(temperature, units='lj')[source]¶

Return the thermodynamic beta factor.

Beta is defined as \(\beta = 1/(k_\text{B} \times T)\).

Parameters:

temperature (float) – The temperature.
units (str, optional) – The unit system (used to look up the Boltzmann constant).

Returns:

out (float or None) – The beta factor, or None if temperature is None.

pyretis.core.particlefunctions.calculate_kinetic_energy(particles, selection=None, kin_tensor=None)[source]¶

Return the kinetic energy of a collection of particles.

Parameters:

particles (object like Particles) – This object represents the particles.
selection (list of integers, optional) – A list with indices of particles to use in the calculation.
kin_tensor (numpy.array, optional) – If kinetic_tensor is not given, the kinetic energy tensor will be calculated.

Returns:

out[0] (float) – The scalar kinetic energy.
out[1] (numpy.array) – The kinetic energy tensor.

pyretis.core.particlefunctions.calculate_kinetic_energy_tensor(particles, selection=None)[source]¶

Return the kinetic energy tensor for a selection of particles.

The tensor is formed as the outer product of the velocities.

Parameters:

particles (object like Particles) – This object represents the particles.
selection (list of integers, optional) – A list with indices of particles to use in the calculation.

Returns:

out (numpy.array) – The kinetic energy tensor. Dimensionality is equal to (dim, dim) where dim is the number of dimensions used in the velocities. The trace gives the kinetic energy.

pyretis.core.particlefunctions.calculate_kinetic_temperature(particles, boltzmann, dof=None, selection=None, kin_tensor=None)[source]¶

Return the kinetic temperature of a collection of particles.

Parameters:

particles (object like Particles) – This object represents the particles.
boltzmann (float) – This is the Boltzmann factor/constant in correct units.
dof (list of floats, optional) – The degrees of freedom to subtract. Its shape should be equal to the number of dimensions.
selection (list of integers, optional) – A list with indices of particles to use in the calculation.
kin_tensor (numpy.array optional) – The kinetic energy tensor. If the kinetic energy tensor is not given, it will be recalculated here.

Returns:

out[0] (numpy.array) – Array with the same size as the kinetic energy. It contains the temperature in each spatial dimension.
out[1] (float) – The temperature averaged over all dimensions.
out[2] (numpy.array) – The kinetic energy tensor.

pyretis.core.particlefunctions.calculate_linear_momentum(particles, selection=None)[source]¶

Calculate the linear momentum for a collection of particles.

Parameters:

particles (object like Particles) – This object represents the particles.
selection (list of integers, optional) – A list with indices of particles to use in the calculation.

Returns:

out (numpy.array) – The array contains the linear momentum for each dimension.

pyretis.core.particlefunctions.calculate_pressure_from_temp(particles, dim, boltzmann, volume, dof=None)[source]¶

Evaluate the scalar pressure.

The scalar pressure is here calculated using the temperature and the degrees of freedom.

Parameters:

particles (object like Particles) – This object represents the particles.
dim (int) – This is the dimensionality of the system. Typically provided by system.get_dim().
boltzmann (float) – This is the Boltzmann factor/constant in correct units. Typically it can be supplied by system.get_boltzmann().
volume (float) – This is the volume ‘occupied’ by the particles. It can typically be obtained by a box.calculate_volume()
dof (list of floats, optional) – The degrees of freedom to subtract. Its shape should be equal to the number of dimensions.

Returns:

out[0] (float) – Pressure times volume.
out[1] (float) – The pressure.

Note

This function may possibly be removed - it does not appear to be very useful right now.

pyretis.core.particlefunctions.calculate_pressure_tensor(particles, volume, kin_tensor=None)[source]¶

Calculate the pressure tensor.

The pressure tensor is obtained from the virial the kinetic energy tensor.

Parameters:

particles (object like Particles) – This object represents the particles.
volume (float) – This is the volume ‘occupied’ by the particles. It can typically be obtained by a box.calculate_volume().
kin_tensor (numpy.array, optional) – The kinetic energy tensor. If kin_tensor is not given, it will be calculated here.

Returns:

out (numpy.array) – The symmetric pressure tensor, dimensions (dim, dim), where dim = the number of dimensions considered in the simulation.

pyretis.core.particlefunctions.calculate_scalar_pressure(particles, volume, dim, press_tensor=None, kin_tensor=None)[source]¶

Evaluate the scalar pressure using the pressure tensor.

Parameters:

particles (object like Particles) – This object represents the particles.
volume (float) – This is the volume ‘occupied’ by the particles. It can typically be obtained by a box.calculate_volume().
dim (int) – This is the dimensionality of the system. Typically provided by system.get_dim()
press_tensor (numpy.array, optional) – If press_tensor is not given, the pressure tensor will be calculated here.
kin_tensor (numpy.array, optional) – If kin_tensor is not given, the kinetic energy tensor will be calculated here.

Returns:

out (float) – The scalar pressure averaged over the diagonal components of the pressure tensor.

pyretis.core.particlefunctions.calculate_thermo(system, dof=None, dim=None, volume=None, vpot=None)[source]¶

Calculate and return several thermodynamic properties.

The calculated properties are the potential, kinetic and total energies per particle, the temperature, the pressure and the momentum.

Parameters:

system (object like System) – This object is used to access the particles and the box.
dof (list of floats, optional) – The degrees of freedom.
dim (float, optional) – The dimensionality of, typically provided with a system.get_dim().
volume (float, optional) – This is the volume ‘occupied’ by the particles. It can typically be obtained by a system.box.calculate_volume().
vpot (float, optional) – The potential energy of the particles.

Returns:

out (dict) – This dict contains the float that is calculated in this routine.

pyretis.core.particlefunctions.calculate_thermo_path(system)[source]¶

Calculate and return several thermodynamic properties.

The calculated properties are the potential, kinetic and total energies for the system and the current temperature. The name here calculate_thermo_path just indicates that this function is useful in connection with path sampling simulations, i.e. it just calculates a few energy terms.

Parameters:: system (object like System) – This object is used to access the particles and the box.
Returns:: out (dict) – This dict contains the float that is calculated in this routine.

pyretis.core.particlefunctions.kinetic_energy(vel, mass)[source]¶

Obtain the kinetic energy for given velocities and masses.

Parameters:

vel (numpy.array) – The velocities
mass (numpy.array) – The masses. This is assumed to be a column vector.

Returns:

out[0] (float) – The kinetic energy
out[1] (numpy.array) – The kinetic energy tensor.

pyretis.core.particlefunctions.kinetic_temperature(vel, mass, boltzmann, dof=None, kin_tensor=None)[source]¶

Return the kinetic temperature given velocities and masses.

This method does not work on a particle object, but rather with numpy arrays. That is, it is intended for use when we can’t rely on the particle object.

Parameters:

vel (numpy.array) – The velocities
mass (numpy.array) – The masses. This is assumed to be a column vector.
boltzmann (float) – This is the Boltzmann factor/constant in correct units.
dof (list of floats, optional) – The degrees of freedom to subtract. Its shape should be equal to the number of dimensions.
kin_tensor (numpy.array optional) – The kinetic energy tensor. If the kinetic energy tensor is not given, it will be recalculated here.

Returns:

out[0] (numpy.array) – It contains the temperature in each spatial dimension. Array with the same size as the kinetic energy.
out[1] (float) – The temperature averaged over all dimensions.
out[2] (numpy.array) – The kinetic energy tensor.

pyretis.core.particlefunctions.rescale_velocities(vel, mass, vpot, target_energy)[source]¶

Rescale velocities so that kinetic + potential = target_energy.

Parameters:

vel (numpy.ndarray) – Particle velocities, shape (npart, dim).
mass (numpy.ndarray) – Particle masses, shape (npart, 1).
vpot (float) – The current potential energy.
target_energy (float) – The desired total energy.

Returns:

vel_out (numpy.ndarray) – The rescaled velocities (a new array; the input is not modified).
success (bool) – False if target_energy - vpot < 0 (rescaling impossible).

pyretis.core.particlefunctions.reset_momentum(particles, selection=None, dim=None)[source]¶

Set the linear momentum of a selection of particles to zero.

Parameters:

particles (object like Particles) – This object represents the particles.
selection (list of integers, optional) – A list with indices of particles to use in the calculation.
dim (list or None, optional) – If dim is None, the momentum will be reset for ALL dimensions. Otherwise, it will only be applied to the dimensions where dim is True.

Returns:

out (None) – Returns None and modifies velocities of the selected particles.

pyretis.core.particles module¶

This module defines a class, representing a collection of particles.

The class for particles is, in reality, a simplistic particle list which stores positions, velocities, masses etc. and is used for representing the particles in the simulations.

Important classes defined here¶

Particles (Particles): Class for a list of particles.
ParticlesExt (ParticlesExt): Class for an external particle list.

class pyretis.core.particles.Particles(dim=1)[source]¶

Bases: object

Base class for a collection of particles.

This is a simple particle list. It stores the positions, velocities, forces, masses (and inverse masses) and type information for a set of particles. This class also defines a method for iterating over pairs of particles, which could be useful for implementing neighbour lists. In this particular class, this method will just define an all-pairs list.

Variables:

npart (integer) – Number of particles.
pos (numpy.array) – Positions of the particles.
vel (numpy.array) – Velocities of the particles.
force (numpy.array) – Forces on the particles.
virial (numpy.array) – The current virial for the particles.
mass (numpy.array) – Masses of the particles.
imass (numpy.array) – Inverse masses, 1.0 / self.mass.
name (list of strings) – A name for the particle. This may be used as short text describing the particle.
ptype (numpy.array of integers) – A type for the particle. Particles with identical ptype are of the same kind.
dim (int) – This variable is the dimensionality of the particle list. This should be derived from the box. For some functions, it is convenient to be able to access the dimensionality directly from the particle list. It is therefore set as an attribute here.
vpot (float) – The potential energy of the particles.
ekin (float) – The kinetic energy of the particles.

__eq__(other)[source]¶: Compare two particle states.

__init__(dim=1)[source]¶

Initialise the Particle list.

Here we just create an empty particle list.

Parameters:: dim (integer, optional) – The number of dimensions we are considering for positions, velocities and forces.

__iter__()[source]¶

Iterate over the particles.

This function will yield the properties of the different particles.

Yields:: out (dict) – The information in self.pos, self.vel, … etc.

__str__()[source]¶: Print out basic info about the particle list.

_copy_attribute(attr, copy_function)[source]¶

Copy an attribute.

Parameters:

attr (string) – The attribute to copy.
copy_function (callable) – The method to use for copying the attribute.

Returns:

out (object) – A copy of the selected attribute.

add_particle(pos, vel, force, mass=1.0, name='?', ptype=0)[source]¶

Add a particle to the system.

Parameters:

pos (numpy.array) – Positions of new particle.
vel (numpy.array) – Velocities of new particle.
force (numpy.array) – Forces on the new particle.
mass (float, optional) – The mass of the particle.
name (string, optional) – The name of the particle.
ptype (integer, optional) – The particle type.

copy()[source]¶

Return a copy of the particle state.

Returns:: out (object like Particles) – A copy of the current state of the particles.

empty_list()[source]¶

Reset the particle list.

This will delete all particles in the list and set other variables to None.

Note

This is almost self.__init__ repeated. The reason for this is simply that we want to define all attributes in self.__init__ and not get any ‘surprise attributes’ defined elsewhere. Also, note that the dimensionality (self.dim) is not changed in this method.

get_force()[source]¶: Return (a copy of) the forces.

get_pos()[source]¶: Return (a copy of) positions.

get_selection(properties, selection=None)[source]¶

Return selected properties for a selection of particles.

Parameters:

properties (list of strings) – The strings represent the properties to return.
selection (list with indices to return, optional) – If a selection is not given, data for all particles are returned.

Returns:

out (list) – A list with the properties in the order they were asked for in the properties argument.

get_vel()[source]¶: Return (a copy of) the velocities.

load_restart_info(info)[source]¶

Load restart information.

Parameters:: info (dict) – Dictionary with the settings to load.

pairs()[source]¶

Iterate over all pairs of particles.

Yields:

out[0] (integer) – The index for the first particle in the pair.
out[1] (integer) – The index for the second particle in the pair.
out[2] (integer) – The particle type of the first particle.
out[3] (integer) – The particle type of the second particle.

particle_type = 'internal'¶

restart_info()[source]¶: Generate information for saving a restart file.

reverse_velocities()[source]¶: Reverse the velocities in the system.

set_force(force)[source]¶

Set the forces for the particles.

Parameters:: force (numpy.array) – The forces to set.

set_pos(pos)[source]¶

Set positions for the particles.

Parameters:: pos (numpy.array) – The positions to set.

set_vel(vel)[source]¶

Set velocities for the particles.

Parameters:: vel (numpy.array) – The velocities to set.

class pyretis.core.particles.ParticlesExt(dim=1)[source]¶

Bases: Particles

A particle list, when positions and velocities are stored in files.

Variables:

config (tuple) – The file name and index in this file for the configuration the particle list is representing.
vel_rev (boolean) – If this is True, the velocities in the file represeting the configuration will have to be reversed before they are used.

__init__(dim=1)[source]¶

Create an empty ParticleExt list.

Parameters:: dim (integer, optional) – The number of dimensions we are considering for positions, velocities and forces.

__str__()[source]¶: Print out basic info about the particle list.

add_particle(pos, vel, force, mass=1.0, name='?', ptype=0)[source]¶

Add a particle to the system.

Parameters:

pos (tuple) – Positions of new particle.
vel (boolean) – Velocities of new particle.
force (tuple) – Forces on the new particle.
mass (float, optional) – The mass of the particle.
name (string, optional) – The name of the particle.
ptype (integer, optional) – The particle type.

copy()[source]¶

Return a copy of the particle state, including etot/temp.

The engine reports all four energy terms (vpot/ekin/ etot/temp) for every frame it actually propagates. Moves that do NOT re-run the engine – time reversal and swaps – reuse those frames, so the copy must carry the energies forward. The base copy already preserves vpot/ekin (they are in _numpy_attr); it does not carry the derived etot/temp, which would otherwise be lost and written as nan in the path energy file. We carry them here (copy-only) rather than via _copy_attr/_numpy_attr so the restart serialisation – and the backward compatibility of existing restart files, whose load_restart_info requires every listed attribute – is untouched.

Returns:: out (object like ParticlesExt) – A copy of the current state, carrying etot/temp when the engine has set them.

empty_list()[source]¶: Just empty the list.

get_pos()[source]¶: Just return the positions of the particles.

get_vel()[source]¶: Return info about the velocities.

particle_type = 'external'¶

reverse_velocities()[source]¶: Reverse the velocities in the system.

set_pos(pos)[source]¶

Set positions for the particles.

This will copy the input positions, for this class, the input positions are assumed to be a file name with a corresponding integer which determines the index for the positions in the file for cases where the file contains several snapshots.

Parameters:: pos (tuple of (string, int)) – The positions to set, this represents the file name and the index for the frame in this file.

set_vel(vel)[source]¶

Set velocities for the particles.

Here we store information which tells if the velocities should be reversed or not.

Parameters:: vel (boolean) – If True, the velocities should be reversed before used.

pyretis.core.path module¶

Classes and functions for paths.

The classes and functions defined in this module are useful for representing paths.

Important classes defined here¶

PathBase (PathBase): A base class for paths.
Path (Path): Class for a generic path that stores all possible information.

Important methods defined here¶

paste_paths (paste_paths()): Function for joining two paths, one is in a backward time direction and the other is in the forward time direction.

class pyretis.core.path.Path(rgen=None, maxlen=None, time_origin=0)[source]¶

Bases: PathBase

A path where the full trajectory is stored in memory.

This class represents a path. A path consists of a series of consecutive snapshots (the trajectory) with the corresponding order parameter. Here we store all information for all phase points on the path.

empty_path(**kwargs)[source]¶

Return an empty path of same class as the current one.

Returns:: out (object like PathBase) – A new empty path.

get_shooting_point(criteria='rnd', interfaces=None, rgen=None)[source]¶

Return a shooting point from the path.

This will simply draw a shooting point from the path at random. All points can be selected with equal probability, except the end points which are not considered.

Parameters:

criteria (string, optional) – The criteria to select the shooting point: ‘rnd’: random, except the first and last point, standard sh. ‘exp’: selection towards low density region.
interfaces (list/tuple of floats, optional) – These are the interface positions of the form [left, middle, right].
rgen (object like RandomGenerator, optional) – Random generator to draw from. When omitted the path’s own self.rgen is used (legacy pyretis-native shape); inf-flavour callers pass one in explicitly (see A3.1a alignment).

Returns:

out[0] (object like System) – The phase point we selected.
out[1] (int) – The shooting point index.

load_restart_info(info, forcefield=None)[source]¶

Set up the path using restart information.

Parameters:

info (dict) – The dictionary with the restart information, similar to the dict produced by restart_info().
forcefield (object like ForceField, optional) – Force field to attach to each restored phasepoint. The force field is not serialised as part of the restart info, so it must be supplied by the caller (typically taken from the owning ensemble’s system).

restart_info()[source]¶: Return a dictionary with restart information.

class pyretis.core.path.PathBase(rgen=None, maxlen=None, time_origin=0)[source]¶

Bases: object

Base class for representation of paths.

This class represents a path. A path consists of a series of consecutive snapshots (the trajectory) with the corresponding order parameter.

Variables:

generated (tuple) – This contains information on how the path was generated. generated[0] : string, as defined in the variable _GENERATED generated[1:] : additional information: For generated[0] == 'sh' the additional information is the index of the shooting point on the old path, the new path and the corresponding order parameter.
maxlen (int) – This is the maximum path length. Some algorithms require this to be set. Others don’t, which is indicated by setting maxlen equal to None.
ordermax (tuple) – This is the (current) maximum order parameter for the path. ordermax[0] is the value, ordermax[1] is the index in self.path.
ordermin (tuple) – This is the (current) minimum order parameter for the path. ordermin[0] is the value, ordermin[1] is the index in self.path.
phasepoints (list of objects like System) – The phase points the path is made up of.
rgen (object like RandomGenerator) – This is the random generator that will be used for the paths that required random numbers.
time_origin (int) – This is the location of the phase point path[0] relative to its parent. This might be useful for plotting.
status (str or None) – The status of the path. The possibilities are defined in the variable _STATUS.
weight (real) – The statistical weight of the path.

__eq__(other)[source]¶: Check if two paths are equal.

__iadd__(other)[source]¶

Add path data to a path from another path, i.e. self += other.

This will simply append the phase points from other.

Parameters:: other (object of type Path) – The object to add path data from.
Returns:: self (object of type Path) – The updated path object.

__init__(rgen=None, maxlen=None, time_origin=0)[source]¶

Initialise the PathBase object.

Parameters:

rgen (object like RandomGenerator, optional) – This is the random generator that will be used.
maxlen (int, optional) – This is the max-length of the path. The default value, None, is just a path of arbitrary length.
time_origin (int, optional) – This can be used to store the shooting point of a parent trajectory.

__ne__(other)[source]¶: Check if two paths are not equal.

__str__()[source]¶: Return a simple string representation of the Path.

property adress¶

Return the external-configuration addresses on the path.

Collects the file address (config[0]) of every phasepoint that carries a real external configuration. Phasepoints with no external config – internal-engine paths where config is None or the empty default ('', -1) – are skipped, so this never raises on an in-memory native path. Used by the infinite-swapping scheduler for trajectory-file housekeeping (it drives os.remove in repex); it is never part of any numeric or bit-level output.

append(phasepoint)[source]¶

Append a new phase point to the path.

Parameters:: phasepoint (object like System) – The system information we add to the path.

check_interfaces(interfaces)[source]¶

Check current status of the path.

Get the current status of the path with respect to the interfaces. This is intended to determine if we have crossed certain interfaces or not.

Parameters:

interfaces (list of floats) – This list is assumed to contain the three interface values left, middle and right.

Returns:

out[0] (str, ‘L’ or ‘R’ or None) – Start condition: did the trajectory start at the left (‘L’) or right (‘R’) interface.
out[1] (str, ‘L’ or ‘R’ or None) – Ending condition: did the trajectory end at the left (‘L’) or right (‘R’) interface or None of them.
out[2] str, ‘M’ or ‘’* – ‘M’ if the middle interface is crossed, ‘*’ otherwise.
out[3] (list of boolean) – These values are given by ordermin < interfaces[i] <= ordermax.

copy()[source]¶: Return a copy of the path.

delete(idx)[source]¶

Remove a phase point from the path.

Parameters:: idx (integer) – The index of the frame to remove.

abstractmethod empty_path(**kwargs)[source]¶

Return an empty path of same class as the current one.

This function is intended to spawn sibling paths that share some properties and also some characteristics of the current path. The idea here is that a path of a certain class should only be able to create paths of the same class.

Returns:: out (object like PathBase) – A new empty path.

get_end_point(left, right=None)[source]¶

Return the end point of the path as a string.

The end point is either to the left of the left interface or to the right of the right interface, or somewhere in between.

Parameters:

left (float) – The left interface.
right (float, optional) – The right interface, equal to left if not specified.

Returns:

out (string) – A string representing where the end point is (‘L’ - left, ‘R’ - right or None).

get_move()[source]¶: Return the move used to generate the path.

get_path_data(status, interfaces)[source]¶

Return information about the path.

This information can be stored in a object like PathEnsemble.

Parameters:

status (string) – This represents the current status of the path.
interfaces (list) – These are just the interfaces we are currently considering.

abstractmethod get_shooting_point()[source]¶

Return a shooting point from the path.

Returns:

phasepoint (object like System) – A phase point which will be the state to shoot from.
idx (int) – The index of the shooting point.

get_start_point(left, right=None)[source]¶

Return the start point of the path as a string.

The start point is either to the left of the left interface or to the right of the right interface.

Parameters:

left (float) – The left interface.
right (float, optional) – The right interface, equal to left if not specified.

Returns:

out (string) – A string representing where the start point is (‘L’ - left, ‘R’ - right or None).

property ha_weights¶

Return the per-ensemble High-Acceptance weight vector.

Used by the native Stage-C output route under the "analysis" ha_weight_mode: the wf compute_weight crossing count, applied as the per-ensemble crossing-probability weight while the infinite-swap occupancy is driven by membership (weights). Defaults to weights when it was never set explicitly, so the "swap" convention and non-wf paths are unaffected.

property length¶: Compute the length of the path.

abstractmethod load_restart_info(info)[source]¶: Read a dictionary with restart information.

property ordermax¶: Compute the maximum order parameter of the path.

property ordermin¶: Compute the minimum order parameter of the path.

abstractmethod restart_info()[source]¶: Return a dictionary with restart information.

reverse(order_function=None, rev_v=True)[source]¶

Reverse a path and return the reverse path as a new path.

This will reverse a path and return the reversed path as a new object like PathBase object.

Returns:

new_path (object like PathBase) – The time reversed path.
order_function (object like OrderParameter, optional) – The method to use to re-calculate the order parameter, if it is velocity dependent.
rev_v (boolean, optional) – If True, also the velocities are reversed, if False, the velocities for each frame are not altered.

static reverse_velocities(system)[source]¶: Reverse the velocities in the phase points.

set_move(move)[source]¶

Update the path move.

The path move is a short string that represents how the path was generated. It should preferably match one of the moves defined in _GENERATED.

Parameters:: move (string) – A short description of the move.

sorting(key, reverse=False)[source]¶

Re-order the phase points according to the given key.

Parameters:

key (string) – The attribute we will sort according to.
reverse (boolean, optional) – If this is False, the sorting is from big to small.

Yields:

out (object like System) – The ordered phase points from the path.

success(target_interface)[source]¶

Check if the path is successful.

The check is based on the maximum order parameter and the value of target_interface. It is successful if the maximum order parameter is greater than target_interface.

Parameters:: target_interface (float) – The value for which the path is successful, i.e. the “target_interface” interface.

update_energies(ekin, vpot, etot=None, temp=None)[source]¶

Update the energies for the phase points.

This method is useful in cases where the energies are read from external engines and returned as a list of floats.

Parameters:

ekin (list of floats) – The kinetic energies to set.
vpot (list of floats) – The potential energies to set.
etot (list of floats, optional) – The total energies to set.
temp (list of floats, optional) – The temperatures to set.

property weight¶

Return the scalar path weight.

Returns the first element of weights. Kept as a scalar property so the legacy pyretis-native callers (path.weight) keep working unchanged; the canonical storage is the weights tuple (see A3.1a alignment).

property weights¶

Return per-ensemble path weights.

Mirrors the infretis-flavour shape so RETIS swap moves that carry a tuple of per-ensemble weights can store them on a native Path during the A3.1a alignment period. Single- ensemble (pyretis-native) callers can keep using weight, which is the scalar projection of this tuple.

pyretis.core.path.check_crossing(cycle, orderp, interfaces, leftside_prev)[source]¶

Check if we have crossed an interface during the last step.

This function is useful for checking if an interface was crossed from the previous step till the current one. This is for instance used in the MD simulations for the initial flux. It will use a variable to store the previous positions with respect to the interfaces and check if interfaces were crossed here.

Parameters:

cycle (int) – This is the current simulation cycle number.
orderp (float) – The current order parameter.
interfaces (list of floats) – These are the interfaces to check.
leftside_prev (list of booleans or None) – These are used to store the previous positions with respect to the interfaces.

Returns:

leftside_curr (list of booleans) – These are the updated positions with respect to the interfaces.
cross (list of tuples) – If a certain interface is crossed, a tuple will be added to this list. The tuple is of form (cycle number, interface number, direction) where the direction is ‘-’ for a crossing in the negative direction and ‘+’ for a crossing in the positive direction.

pyretis.core.path.paste_paths(path_back, path_forw, overlap=True, maxlen=None)[source]¶

Merge a backward with a forward path into a new path.

The resulting path is equal to the two paths stacked, in correct time. Note that the ordering is important here so that: paste_paths(path1, path2) != paste_paths(path2, path1).

There are two things we need to take care of here:

path_back must be iterated in reverse (it is assumed to be a backward trajectory).
we may have to remove one point in path2 (if the paths overlap).

Parameters:

path_back (object like PathBase) – This is the backward trajectory.
path_forw (object like PathBase) – This is the forward trajectory.
overlap (boolean, optional) – If True, path_back and path_forw have a common starting-point, that is, the first point in path_forw is identical to the first point in path_back. In time-space, this means that the first point in path_forw is identical to the last point in path_back (the backward and forward path started at the same location in space).
maxlen (float, optional) – This is the maximum length for the new path. If it’s not given, it will just be set to the largest of the maxlen of the two given paths.

Note

Some information about the path will not be set here. This must be set elsewhere. This includes how the path was generated (path.generated) and the status of the path (path.status).

pyretis.core.path_load module¶

Load infinite-swapping paths from disk into Path objects.

These loaders were historically part of the inf-flavour Path module (pyretis.core._path_inf). After the A3.1b Path collapse there is a single pyretis.core.path.Path, so the loaders live here, free of the now-deleted _path_inf module. They build native Path objects whose phasepoints are file-backed snapshot System objects (the external-engine representation), exactly as the infinite-swapping scheduler expects.

pyretis.core.path_load._load_energies_for_path(path: Path, dirname: str) → None[source]¶

Load energy data for a path.

Parameters:

path (Path) – The path we are to set up/fill.
dirname (str) – The path to the directory with the input files.

pyretis.core.path_load._parse_move_comment(comment_lines: List[str]) → Any[source]¶

Recover a path’s generated move tuple from a path-file comment.

The path formatters write # Cycle: N, status: S, move: M where M is the repr of the path’s generated tuple (e.g. ('sh', -0.2478, 2, 4)) or None.

Parameters:: comment_lines (list of str) – The comment lines of the first block, as returned by pyretis.inout.fileio.read_some_lines().
Returns:: tuple or None – The recovered generated tuple, or None when no parsable move: field is present (or the move was itself None).

pyretis.core.path_load._parse_move_field(token: str) → Any[source]¶

Convert one repr-formatted move-tuple token to its scalar value.

Parameters:: token (str) – A single, already-stripped element of the move tuple, e.g. "'sh'", "-0.2478", "2" or "nan".
Returns:: object – The string (quotes removed), float or int the token represents. Integers keep their int type so the recovered tuple’s repr matches the persisted one exactly.

pyretis.core.path_load.load_path(pdir: str) → Path[source]¶: Load a path from the given directory.

pyretis.core.path_load.load_paths_from_disk(config: Dict[str, Any]) → List[Path][source]¶: Load paths from disk.

pyretis.core.pathensemble module¶

Classes and functions for path ensembles.

The classes and functions defined in this module are useful for representing path ensembles.

Important classes defined here¶

PathEnsemble (PathEnsemble): Class for defining path ensembles.
PathEnsembleExt (PathEnsembleExt): Class for defining path ensembles when we are working with paths stored on disk and not in memory only.

class pyretis.core.pathensemble.PathEnsemble(ensemble_number, interfaces, rgen=None, maxpath=10000, exe_dir=None)[source]¶

Bases: object

Representation of a path ensemble.

This class represents a collection of paths in a path ensemble. In general, paths may be “long and complicated” so here, we really just store a simplified abstraction of the path, which is obtained by the Path.get_path_data() function for a given Path object. The returned dictionary is stored in the list PathEnsemble.paths. The only full path we store is the last accepted path. This is convenient for the RETIS method where paths may be swapped between path ensembles.

Variables:

ensemble_number (integer) – This integer is used to represent the path ensemble, for RETIS simulations it’s useful to identify the path ensemble. The path ensembles are numbered sequentially 0, 1, 2, etc. This corresponds to [0^-], [0^+], [1^+], etc.
ensemble_name (string) – A string which can be used for printing the ensemble name. This is of form [0^-], [0^+], [1^+], etc.
ensemble_name_simple (string) – A string with a simpler representation of the ensemble name, can be used for creating output files etc.
interfaces (list of floats) – Interfaces, specified with the values for the order parameters: [left, middle, right].
paths (list) – This list contains the stored information for the paths. Here we only store the data returned by calling the get_path_data() function of the Path object.
nstats (dict of ints) –
This dict store some statistics for the path ensemble. The keys are:
- npath : The number of paths stored.
- nshoot : The number of accepted paths generated by shooting.
- ACC, BWI, … : Number of paths with given status (from _STATUS).
maxpath (int) – The maximum number of paths to store.
last_path (object like PathBase) – This is the last accepted path.

__eq__(other)[source]¶: Check if two path_ensemble are equal.

__init__(ensemble_number, interfaces, rgen=None, maxpath=10000, exe_dir=None)[source]¶

Initialise the PathEnsemble object.

Parameters:

ensemble_number (integer) – An integer used to identify the ensemble.
interfaces (list of floats) – These are the interfaces specified with the values for the order parameters: [left, middle, right].
rgen (object like RandomGenerator, optional) – The random generator that will be used for the paths that required random numbers.
maxpath (integer, optional) – The maximum number of paths to store information for in memory. Note, that this will not influence the analysis as long as you are using the output files when running the analysis.
exe_dir (string, optional) – The base folder where the simulation was executed from. This is used to set up output directories for the path ensemble.

__ne__(other)[source]¶: Check if two paths are not equal.

__str__()[source]¶: Return a string with some info about the path ensemble.

add_path_data(path, status, cycle=0)[source]¶

Append data from the given path to self.path_data.

This will add the data from a given` path` to the list path data for this ensemble. If will also update self.last_path if the given path is accepted.

Parameters:

path (object like PathBase) – This is the object to store data from.
status (string) – This is the status of the path. Note that the path object also has a status property. However, this one might not be set, for instance when the path is just None. We therefore use status here as a parameter.
cycle (int, optional) – The current cycle number.

clear_generate()[source]¶

Remove all the files in an ensemble/generate/ directory.

This is toggled on by adding ‘remove_generate = True’ to the retis.rst input file, under the [simulation] section.

copy_path_to_generate(path, _prefix=None)[source]¶

Copy a path for temporary storing.

Parameters:: path (object like PathBase) – The path to copy.
Returns:: out (object like PathBase) – The copy of the path.

directories()[source]¶: Yield the directories PyRETIS should make.

get_acceptance_rate()[source]¶

Return acceptance rate for the path ensemble.

The acceptance rate is obtained as the fraction of accepted paths to the total number of paths in the path ensemble. This will only consider the paths that are currently stored in self.paths.

Returns:: out (float) – The acceptance rate.

get_accepted()[source]¶

Yield accepted paths from the path ensemble.

This function will return an iterator useful for iterating over accepted paths only. In the path ensemble we store both accepted and rejected paths. This function will loop over all paths stored and yield the accepted paths the correct number of times.

get_paths()[source]¶

Yield the different paths stored in the path ensemble.

It is included here in order to have a simple compatibility between the PathEnsemble object and the py:class:.PathEnsembleFile object. This is useful for the analysis.

Yields:: out (dict) – This is the dictionary representing the path data.

load_restart_info(info, cycle=0, forcefield=None)[source]¶

Load restart information.

Parameters:

info (dict) – A dictionary with the restart information.
cycle (integer, optional) – The current simulation cycle.
forcefield (object like ForceField, optional) – Force field to attach to the phasepoints of the restored path. The force field is not part of the serialised restart info, so it must be supplied by the caller.

move_path_to_generate(_path, _prefix=None)[source]¶: Move a path for temporary storing.

reset_data()[source]¶

Erase the stored data in the path ensemble.

It can be used in combination with flushing the data to a file in order to periodically write and empty the amount of data stored in memory.

Notes

We do not reset self.last_path as this might be used in the RETIS function.

restart_info()[source]¶: Return a dictionary with restart information.

store_path(path)[source]¶

Store a new accepted path in the path ensemble.

Parameters:: path (object like PathBase) – The path we are going to store.
Returns:: None, but we update self.last_path.

update_directories(path)[source]¶

Update directory names.

This method will not create new directories, but it will update the directory names.

Parameters:: path (string) – The base path to set.

class pyretis.core.pathensemble.PathEnsembleExt(ensemble_number, interfaces, rgen=None, maxpath=10000, exe_dir=None)[source]¶

Bases: PathEnsemble

Representation of a path ensemble.

This class is similar to PathEnsemble but it is made to work with external paths. That is, some extra file handling is done when accepting a path.

static _copy_path(path, target_dir, prefix=None)[source]¶

Copy a path to a given target directory.

Parameters:

path (object like PathBase) – This is the path object we are going to copy.
target_dir (string) – The location where we are copying the path to.
prefix (string, optional) – To give a prefix to the name of copied files.

Returns:

out (object like py:class:.PathBase) – A copy of the input path.

static _move_path(path, target_dir, prefix=None)[source]¶

Move a path to a given target directory.

Parameters:

path (object like PathBase) – This is the path object we are going to move.
target_dir (string) – The location where we are moving the path to.
prefix (string, optional) – To give a prefix to the name of moved files.

copy_path_to_generate(path, pref=None)[source]¶: Copy a path for temporary storing.

list_superfluous()[source]¶: List files in accepted directory that we do not need.

load_restart_info(info, cycle=0, forcefield=None)[source]¶: Load restart for external path.

move_path_to_generate(path, prefix=None)[source]¶: Move a path for temporary storing.

store_path(path)[source]¶

Store a path by explicitly moving it.

Parameters:: path (object like PathBase) – This is the path object we are going to store.

pyretis.core.pathensemble.generate_ensemble_name(ensemble_number, zero_pad=3)[source]¶

Generate a simple name for an ensemble.

The simple name will have a format like 01, 001, 0001 etc. and it is used to name the path ensemble and the output directory.

Parameters:

ensemble_number (int) – The number representing the ensemble.
zero_pad (int, optional) – The number of zeros to use for padding the name.

Returns:

out (string) – The ensemble name.

pyretis.core.pathensemble.get_path_ensemble_class(ensemble_type)[source]¶

Return the path ensemble class consistent with the given engine.

Parameters:: ensemble_type (string) – The type of ensemble we are requesting.

pyretis.core.properties module¶

This file contains a class for a generic property.

class pyretis.core.properties.Property(desc='')[source]¶

Bases: object

A generic numerical value with standard deviation and average.

A generic object to store values obtained during a simulation. It will maintain the mean and variance as values are added using Property.add(val)

Variables:

desc (string) – Description of the property.
nval (integer) – Number values stored.
mean (float) – The current mean.
delta2 (float) – Helper variable used for calculating the variance.
variance (float) – The current variance
val (list) – Store all values.

Parameters:

desc (string, optional) – Used to set the attribute desc.

Examples

>>> from pyretis.core.properties import Property
>>> ener = Property(desc='Energy of the particle(s)')
>>> ener.add(42.0)
>>> ener.add(12.220)
>>> ener.add(99.22)
>>> ener.mean

__init__(desc='')[source]¶

Initialise the property.

Parameters:: desc (string, optional) – Description of the object.

__str__()[source]¶: Return string description of the property.

add(val)[source]¶

Add a value to the property & update the mean and variance.

Parameters:: val (float or another type (list, numpy.array)) – The value to add.
Returns:: out (None) – Returns None but updates the mean and variance.

dump_to_file(filename)[source]¶

Dump the contents in self.val to a file.

Parameters:: filename (string) – Name/path of file to write.

Note

Consider if this should be moved/deleted and just replaced with a function from a more general input-output module

update_mean_and_variance()[source]¶

Calculate the mean and variance on the fly.

Source: http://en.wikipedia.org/wiki/Algorithms_for_calculating_variance

Returns:: out (None) – Returns None but updates the mean and variance.

Note

Consider if this should be moved/deleted and just replaced with a function from the analysis package.

pyretis.core.random_gen module¶

This module handles random number generation.

It derives most of the random number procedures from RandomState in numpy.random and defines a class which used RandomState to generate pseudo-random numbers.

Important classes defined here¶

RandomGeneratorBase (RandomGeneratorBase): An abstract base class for random number generators.
RandomGenerator (RandomGenerator): A class representing a random number generator.
ReservoirSampler (ReservoirSampler): A class for reservoir sampling.
MockRandomGenerator (MockRandomGenerator): A non-random number generator which is useful for testing.

class pyretis.core.random_gen.MockRandomGenerator(seed=0, norm_shift=False)[source]¶

Bases: RandomGeneratorBase

A mock random generator, useful only for testing.

This class represents a random generator that can be used for testing algorithms. It will simply return numbers from a small list of pseudo-random numbers. This class is only useful for testing algorithms on different systems. It should NEVER be used for actual production runs!

__init__(seed=0, norm_shift=False)[source]¶

Initialise the mock random number generator.

Here, we set up some predefined random number which we will use as a pool for the generation.

Parameters:

seed (int, optional) – An integer used for seeding the generator if needed.
norm_shift (boolean) – If True is will ensure that the fake ‘normal distribution’ is shifted to get the right mean.

choice(a, size=None, replace=True, p=None)[source]¶

Choose random samples from a given array.

Parameters:

a (1-D array-like or int) – If an ndarray, a random sample is generated from its elements. If an int, the random sample is generated as if a were np.arange(a).
size (int or tuple of ints, optional) – Output shape. Default is None, in which case a single value is returned.
replace (boolean, optional) – Whether the sample is with or without replacement.
p (1-D array-like, optional) – The probabilities associated with each entry in a. If not given the sample assumes a uniform distribution over all entries in a.

Returns:

choice (any or numpy.array) – The generated random samples.

Note

This is part of a mock generator and uses the pre-defined sequence to make choices.

get_state()[source]¶: Return current state.

multivariate_normal(mean, cov, cho=None, size=1)[source]¶

Draw numbers from a multi-variate distribution.

This is an attempt on speeding up the call of RandomState.multivariate_normal if we need to call it over and over again. Such repeated calling will do an SVD repeatedly, which is wasteful. In this function, this transform can be supplied and it is only estimated if it’s not explicitly given.

Parameters:

mean (numpy array (1D, 2)) – Mean of the N-dimensional array
cov (numpy array (2D, (2, 2))) – Covariance matrix of the distribution.
cho (numpy.array (2D, (2, 2)), optional) – Cholesky factorization of the covariance. If not given, it will be calculated here.
size (int, optional) – The number of samples to do.

Returns:

out (float or numpy.array of floats size) – The random numbers that are drawn here.

pyretis.core.system module¶

Module defining the System class.

The canonical System type for PyRETIS lives at pyretis.core.system_core after A3.2c (the snapshot/harness unification). This module re-exports it under the legacy import path so existing call sites that from pyretis.core.system import System keep working.

Importable here¶

System (System): The unified System class. Construct with the harness factory kwargs (units, temperature, box) or no-args for the lightweight phasepoint-storage default. Carries the bridge surface (pos / vel / vpot / ekin / mass / imass / force / virial / config / vel_rev / particles / forcefield / post_setup / units / temperature) plus the legacy method shape (update_force, potential_and_force, rescale_velocities, update_box, get_dim, get_boltzmann, calculate_temperature, generate_velocities, calculate_beta, restart_info, load_restart_info, reverse_velocities, add_particle, extra_setup, particle_type, npart).

Most of the behaviour now lives in pyretis.core.forcefieldhelp, pyretis.core.systemhelp, and pyretis.inout.restart; the System class delegates to those free functions. New code should call the free functions directly.

class pyretis.core.system.System(units: str = 'lj', temperature: float | None = None, box: Any = None, post_setup: List[Tuple[str, tuple]] | None = None)[source]¶

Bases: object

Define the representation of System snapshots.

The system is intended for sharing the current configuration (of a frame in a path) between different methods, but the same class also serves as the canonical live System (post A3.2c) – it accepts the harness-style construction kwargs and carries the particles / forcefield / post_setup attributes the factory layer needs.

__eq__(other)[source]¶

Compare two system objects.

Mirrors the harness System.__eq__: ignores the order parameter (depends on the order-function choice), compares units / post_setup / box / particles / forcefield, and the set / beta / dof keys of the temperature dict.

__init__(units: str = 'lj', temperature: float | None = None, box: Any = None, post_setup: List[Tuple[str, tuple]] | None = None) → None[source]¶

Initiate class.

Parameters:

units (str, optional) – Unit system identifier (e.g. "lj", "reduced", "openmm"). Used by helpers such as pyretis.core.systemhelp.get_boltzmann().
temperature (float, optional) – Target temperature. Stored under the temperature['set'] key for harness compatibility; dof and beta are initialised to None.
box (object, optional) – Either a pyretis.core.box.Box instance (harness shape) or a 3x3 np.ndarray (snapshot shape). When None the legacy snapshot 3x3 zeros default is used.
post_setup (list of (str, tuple), optional) – Deferred-setup callback list. Defaults to [].

__ne__(other)[source]¶: Check if two systems are not equal.

__str__()[source]¶: Print basic info about the system.

_adjust_dof_according_to_box()[source]¶

Walk the box’s periodic attribute and subtract dofs.

Subtracts one dof per periodic dimension (harness Box only). Snapshot ndarray boxes have no periodic – silently no-ops via the AttributeError fallback.

add_particle(pos, vel=None, force=None, mass=1.0, name='?', ptype=0)[source]¶: Add a particle. Requires self.particles to be set first.

adjust_dof(dof)[source]¶

Subtract dof from the system’s degree-of-freedom count.

Mirrors the harness method: accumulates into self.temperature['dof'] (initialised lazily).

calculate_beta(temperature=None)[source]¶: Thermodynamic beta for this system.

calculate_temperature()[source]¶: See pyretis.core.systemhelp.calculate_system_temperature().

property config¶

External-engine trajectory pointer (file, frame_idx).

When self.particles is a ParticlesExt, routes through its config attribute. For pure phasepoints (no particles) the backing self._config tuple is used.

copy() → System[source]¶

Return a copy of this system.

Deep-copies the phasepoint-storage state (pos/vel/box/order/ energies/etc.) and the per-instance harness-compat fields (units/temperature/particles/post_setup). forcefield is shared by reference – matches the harness System.copy() contract: if the force field changes, every system copy must see the change.

property ekin¶: Kinetic energy (routed to particles when attached).

evaluate_force()[source]¶: See pyretis.core.forcefieldhelp.evaluate_force().

evaluate_potential()[source]¶: See pyretis.core.forcefieldhelp.evaluate_potential().

evaluate_potential_and_force()[source]¶

Evaluate and return the system potential energy and forces.

See pyretis.core.forcefieldhelp.evaluate_potential_and_force().

extra_setup() → None[source]¶: Run post-construction callbacks registered in post_setup.

property force¶: Per-particle forces (routed to particles when attached).

generate_velocities(rgen=None, seed=0, momentum=True, temperature=None, distribution='maxwell')[source]¶: See pyretis.core.systemhelp.generate_system_velocities().

get_boltzmann()[source]¶: See pyretis.core.systemhelp.get_boltzmann().

get_dim()[source]¶: See pyretis.core.systemhelp.get_system_dim().

property has_particles: bool¶: True when real in-memory particles are attached.

property imass¶: Inverse particle masses (routed to particles when attached).

load_restart_info(info)[source]¶: See pyretis.inout.restart.load_system_restart().

property mass¶: Per-particle masses (routed to particles when attached).

property npart¶: Number of particles (delegates to self.particles.npart).

property particle_type¶: Engine flavour (‘internal’/’external’) of the attached particles.

property particles¶

In-memory particles, or a guard sentinel for pure snapshots.

Returns the attached particles object when present. For a file-backed / scheduler phasepoint (no in-memory particles) returns NO_PARTICLES, whose attribute access raises a clear error pointing callers at the system.pos / system.vel bridge. Read positions through system.pos; system.particles.pos is no longer supported on these phasepoints.

particles_restart_info()[source]¶: Return restart info for the attached particles object.

property pos¶: Particle positions (routed to particles when attached).

potential()[source]¶: See pyretis.core.forcefieldhelp.update_potential().

potential_and_force()[source]¶

Update and return the system potential energy and forces.

See pyretis.core.forcefieldhelp.update_potential_and_force().

rescale_velocities(energy, external=False)[source]¶

Rescale system velocities to the requested energy.

See pyretis.core.forcefieldhelp.rescale_system_velocities().

restart_info()[source]¶: See pyretis.inout.restart.system_restart_info().

reverse_velocities()[source]¶

Flip the sign of the velocities.

Mirrors the harness System’s reverse_velocities(): when particles is attached (harness flavour) delegate through it (handles ParticlesExt.vel_rev flag toggle vs regular Particles.vel flip). Otherwise (pure snapshot, external-engine restart-on-disk style) toggle vel_rev.

set_pos(pos: Tuple[str, int]) → None[source]¶: Set positions for the particles.

update_box(length)[source]¶: See pyretis.core.systemhelp.update_system_box().

update_force()[source]¶: See pyretis.core.forcefieldhelp.update_force().

property vel¶: Particle velocities (routed to particles when attached).

property vel_rev¶: Velocity-reversal flag (routed to particles when attached).

property virial¶: Virial tensor (routed to particles when attached).

property vpot¶: Potential energy (routed to particles when attached).

pyretis.core.units module¶

This module defines natural constants and unit conversions.

This module defines some natural constants and conversions between units which can be used by the PyRETIS program. The natural constants are mainly used for conversions but it is also used to define the Boltzmann constant for internal use in PyRETIS. The unit conversions are mainly useful for input/output.

All numerical values are from the National Institute of Standards and Technology and can be accessed through a web interface http://physics.nist.gov/constants or in plain text. [7]

Internally, all computations are carried out in units which are defined by a length scale, an energy scale and a mass scale. The time scale is defined by these choices.

Charges are typically given (in the input) in units of the electron charge. The internal unit for charge is not yet implemented, but a choice is here to include the factor \(\frac{1}{\sqrt{4\pi\varepsilon_0}}\). An internal calculation of \(q_1 q_2\) will then include coulombs constant in the correct units.

The different sets of unit systems are described below in the section on unit systems.

Natural constants¶

The keys for CONSTANTS defines the natural constant and its units, for instance CONSTANTS['kB']['J/K'] is the Boltzmann constants in units of Joule per Kelvin. The currently defined natural constants are:

kB : The Boltzmann constant. [1]
NA : The Avogadro constant. [2]
e : The elementary charge. [3]
c0 : The velocity of light in vacuum. [4]
mu0: Vacuum permeability. [5]
e0: Vacuum permittivity (or permittivity of free space or electric constant). [6]

Unit conversions¶

For defining the different unit conversions a simple set of base conversions are defined. These represent some common units that are convenient for input and output. For each dimension [12] we define some units and the conversion between these. The base units are:

Charge:

e: Electron charge.
C: Coulomb.

Energy:

kcal: Kilocalorie.
kcal/mol: Kilocalorie per mol.
J: Joule.
J/mol: Joule per mol.
kJ/mol: Kilojoule per mol.
eV: Electronvolt.
hartree: Hartree (atomic unit of energy).

Force:

N: Newton.
pN: Piconewton.
dyn: Dyne.

Length:

A: Ångström.
nm: Nanometre.
bohr: Bohr radius.
m: Meter.

Mass:

g/mol: Grams per mol, numerically equal to the atomic mass unit.
g: Gram.
kg: Kilogram.

Pressure:

Pa: Pascal.
bar: Bar.
atm: Atmosphere.

Temperature:

K: Kelvin.

Time:

s: Second.
ps: Picosecond.
fs: Femtosecond
ns: Nanosecond.
us: Microsecond.
ms: Millisecond.

Velocity:

m/s: Meter per second.
nm/ps: Nanometer per picosecond.
A/fs: Ångström per femtosecond.
A/ps: Ångström per picosecond.

Unit conversions and internal systems of units¶

The following system of units are defined for PyRETIS:

lj: A Lennard-Jones type of units.
real: A system of units similar to the LAMMPS unit real. [8]
metal: A system of units similar to the LAMMPS unit metal. [8]
au: Atomic units. [9]
electron: A system of units similar to the LAMMPS unit electron. [8]
si: A system of units similar to the LAMMPS unit si. [8]
gromacs: A system of units similar to the units used by GROMACS. [10]
reduced: A reduced system of units.
cp2k: A system of units consistent with CP2K.

The defining units for the Lennard-Jones units (lj) are typically based on the Lennard-Jones parameters for one of the components, e.g. \(\varepsilon\), \(\sigma\) and the atomic mass of argon (119.8 kB, 3.405 Å, 39.948 g/mol). [11] The defining units for the other systems are given in the table below:

Table 56 Defining units for energy systems¶
System name	Energy unit	Length unit	Mass unit
real	1 kcal/mol	1 Å	1 g/mol
metal	1 eV	1 Å	1 g/mol
au	1 hartree	1 bohr	9.10938291e-31 kg
electron	1 hartree	1 bohr	1 g/mol
si	1 J	1 m	1 kg
gromacs	1 kJ/mol	1 nm	1 g/mol
cp2k	1 hartree	1 Å	1 g/mol

These units are also used for the input and define the time unit. Further, all system of units expect an input temperature in Kelvin (K) and all systems, with the exception of si, expect a charge in units of electron charges. The si system uses here Coulomb as its unit of charge. The time units for the different energy systems are given in the table below.

Table 57 Time units for different systems¶
System name	Time unit
real	48.8882129084 fs
metal	10.1805056505 fs
au	0.0241888423521 fs
electron	1.03274987345 fs
si	1.0 s
gromacs	1.0 ps
cp2k	0.0457102889683 fs

The interpretation here is that if you are for instance using the system real and would like to have a time step equal to 0.5 fs, then the input time step to PyRETIS should be 0.5 fs / 48.8882129084 fs. NOTE: When using external engines, PyRETIS will not do any assumptions on the input time/length etc and simply assume that the input values are given in correct units for the external engine. In this case, the only time PyRETIS will make use of the unit system is when the Boltzmann constant is used together with energies. That is, the Boltzmann constant must be in units consistent with the energy output from the external engine.

References and footnotes¶

Examples

>>> from pyretis.core.units import CONVERT
>>> print(CONVERT['length'])
{('A', 'nm'): 0.1, ('A', 'bohr'): 1.8897261254578281, ('A', 'm'): 1e-10}
>>> from pyretis.core.units import create_conversion_factors
>>> create_conversion_factors('lj', length=(3.405, 'A'), energy=(119.8, 'kB'),
...                           mass=(39.948, 'g/mol'), charge='e')
>>> print(CONVERT['length']['bohr', 'nm'])
0.052917721067
>>> print(CONVERT['length']['lj', 'nm'])
0.3405
>>> print(CONVERT['length']['bohr', 'lj'])
0.155411809301
>>> create_conversion_factors('cgs', length=(0.01, 'm'),
...                           energy=(1.0e-7, 'J'),
...                           mass=(1.0, 'g'), charge='e')
>>> print(round(CONVERT['force']['cgs', 'dyn'], 2))
1.0
>>> print(round(CONVERT['time']['cgs', 's'], 2))
1.0

pyretis.core.units.bfs_convert(conversions, unit_from, unit_to)[source]¶

Generate unit conversion between the provided units.

The unit conversion can be obtained given that a “path” between these units exist. This path is obtained by a Breadth-first search.

Parameters:

conversions (dictionary) – The unit conversion as convert[quantity].
unit_from (string) – Starting unit.
unit_to (string) – Target unit.

Returns:

out[0] (tuple) – A tuple containing the two units: (unit_from, unit_to).
out[1] (float) – The conversion factor.
out[2] (list of tuples) – The ‘path’ between the units, i.e. the traversal from unit_from to unit_to. out[2][i] gives the (unit_from, unit_to) tuple for step i in the conversion.

pyretis.core.units.convert_bases(dimension)[source]¶

Create all conversions between base units.

This function will generate all conversions between base units defined in a UNITS[dimension] dictionary. It assumes that one of the bases have been used to defined conversions to all other bases.

Parameters:: dimension (string) – The dimension to convert for.

pyretis.core.units.create_conversion_factors(unit, length=None, energy=None, mass=None, charge=None)[source]¶

Set up conversion factors for a system of units.

Parameters:

unit (string) – A name for the system of units
length (tuple, optional) – This is the length unit given as (float, string) where the float is the numerical value and the string the unit, e.g. (1.0, nm).
energy (tuple, optional) – This is the energy unit given as (float, string) where the float is the numerical value and the string the unit, e.g. (1.0, eV).
mass (tuple, optional) – This is the mass unit given as (float, string) where the float is the numerical value and the string the unit, e.g. (1.0, g/mol).
charge (string, optional) – This is the unit of charge given as a string, e.g. ‘e’ or ‘C’.

Returns:

None but will update CONVERT so that the conversion factors are
available.

pyretis.core.units.generate_conversion_factors(unit, distance, energy, mass, charge='e')[source]¶

Create conversions for a system of units from fundamental units.

This will create a system of units from the three fundamental units distance, energy and mass.

Parameters:

unit (string) – This is a label for the unit
distance (tuple) – This is the distance unit. The form is assumed to be (value, unit) where the unit is one of the known distance units, ‘nm’, ‘A’, ‘m’.
energy (tuple) – This is the energy unit. The form is assumed to be (value, unit) where unit is one of the known energy units, ‘J’, ‘kcal’, ‘kcal/mol’, ‘kb’.
mass (tuple) – This is the mass unit. The form is assumed to be (value, unit) where unit is one of the known mass units, ‘g/mol’, ‘kg’, ‘g’.
charge (string, optional) – This selects the base charge. It can be ‘C’ or ‘e’ for Coulomb or the electron charge. This will determine how we treat Coulomb’s constant.

pyretis.core.units.generate_inverse(conversions)[source]¶

Generate all simple inverse conversions.

A simple inverse conversion is something we can obtain by doing a 1 / unit type of conversion.

Parameters:: conversions (dictionary) – The unit conversions as convert[quantity]. Note that this variable will be updated by this function.
Returns:: out (None) – Will not return anything, but will update the given parameter conversions.

pyretis.core.units.print_table(unit, system=False)[source]¶

Print out tables with conversion factors.

This is a table in rst format which is useful for displaying conversions.

Parameters:

unit (string) – The unit to print out conversions for.
system (boolean, optional) – Determines if information for system conversions should be printed.

Returns:

out (None) – Does not return anything, but will print to the screen.

pyretis.core.units.read_conversions(filename='units.txt', select_units=None)[source]¶

Load conversion factors from a file.

This will load unit conversions from a file.

Parameters:

filename (string, optional) – The file to load units from.
select_units (string, optional) – If select_units is different from None, it can be used to pick out only conversions for a specific system of units, e.g. ‘real’ or ‘gromacs’, … etc.

Returns:

out (dict) – A dictionary with the conversions.

pyretis.core.units.units_from_settings(settings)[source]¶

Set up units from given input settings.

Parameters:

settings (dict) – A dict defining the units. The unit system is taken from system.units when explicitly given. Otherwise, the selected engine must define default units.

Returns:

msg (string) – Just a string with some information about the units created. This can be used for printing out some info to the user.

Raises:

KeyError – If the system section is missing, or if no unit system can be determined.
ValueError – If the provided unit-system settings are inconsistent.

pyretis.core.units.write_conversions(filename='units.txt')[source]¶

Print out the information currently stored in CONVERT.

This function is intended for creating a big list of conversion factors that can be included in this script for defining unit conversions.

Parameters:: filename (string, optional) – The file to write units to.
Returns:: out (None) – Will not return anything, but writes the given file.

pyretis.core.units.CONSTANTS = Dictionary with natural constants¶: A dict containing the natural constants. Natural constants can be accessed with CONSTANTS[‘kB’][‘eV/K’] etc.

pyretis.core.units.CONVERT = Dictionary with conversion factors¶: A dictionary with conversion factors. It is used to convert between different units, e.g. CONVERT[‘length’][‘bohr’, ‘nm] will convert from the length unit bohr to the length unit nm.

pyretis.core.units.DIMENSIONS = Dictionary with known dimensions¶: A dictionary with the known dimensions. Note that not all of these are true dimensions, for instance, we are using velocity as a dimension here. This is just because it is convenient to use this to get conversion factors for velocities.

pyretis.core.units.UNITS = Dictionary with known base units¶: A dictionary of sets. Each set defines the known base unit for a dimension, i.e. UNITS[‘length’] is the set with known base units for the length: UNITS[‘length’] = {‘A’, ‘nm’, ‘bohr’, ‘m’}

pyretis.core.units.UNIT_SYSTEMS = Dictionary with definitions of systems of units¶: A dictionary containing basic information about the different unit systems. E.g. UNIT_SYSTEMS[‘lj’][‘length’] contains the length unit for the ‘lj’ unit system.

pyretis.core.forcefieldhelp module¶

Forcefield evaluation helpers (system-type-agnostic).

These free functions let callers compute / update the potential and forces of a System without going through harness-specific system.potential_and_force() style methods. The functions operate purely through the System bridge surface (system.vpot / system.force / system.virial), so they work transparently on both the harness System and the snapshot System.

The corresponding harness System methods delegate to these helpers; new code should call the free functions directly, since the harness methods go away in A3.2c.

pyretis.core.forcefieldhelp.evaluate_force(system, forcefield)[source]¶

Return forces/virial without updating the system.

Parameters:

system (object like System) – The system being evaluated. Not mutated.
forcefield (object like ForceField) – The forcefield used.

Returns:

force (numpy.ndarray) – Force array.
virial (numpy.ndarray) – Virial tensor.

pyretis.core.forcefieldhelp.evaluate_potential(system, forcefield)[source]¶

Return the potential energy without updating the system.

Parameters:

system (object like System) – The system being evaluated. Not mutated.
forcefield (object like ForceField) – The forcefield used.

Returns:

float – The potential energy.

pyretis.core.forcefieldhelp.evaluate_potential_and_force(system, forcefield)[source]¶

Return potential, force, and virial without updating the system.

Parameters:

system (object like System) – The system being evaluated. Not mutated.
forcefield (object like ForceField) – The forcefield used.

Returns:

vpot (float) – Potential energy.
force (numpy.ndarray) – Force array.
virial (numpy.ndarray) – Virial tensor.

pyretis.core.forcefieldhelp.rescale_system_velocities(system, target_energy, forcefield=None, external=False)[source]¶

Re-scale system.vel so total energy matches target_energy.

Free-function form of the soon-to-go System.rescale_velocities(energy, external=...) method.

Parameters:

system (object like System) – The system whose velocities should be rescaled in place via the bridge surface (system.vel / system.mass / system.vpot).
target_energy (float) – Desired total energy (kinetic + potential).
forcefield (object like ForceField, optional) – Required when external is False; used to recompute system.vpot before the rescale. Ignored when external is True (the existing system.vpot is used).
external (bool, optional) – Mirrors the external flag of the legacy method. When True, use the cached system.vpot; when False, recompute it via the forcefield first.

pyretis.core.forcefieldhelp.update_force(system, forcefield)[source]¶

Evaluate forces via the forcefield and store on the system.

Parameters:

system (object like System) – The system to update. Must expose force and (optionally) virial via the bridge surface.
forcefield (object like ForceField) – The forcefield used to evaluate the forces.

Returns:

force (numpy.ndarray) – The freshly computed force array (also written to system.force).
virial (numpy.ndarray) – The virial tensor (also written to system.virial when the system carries one).

pyretis.core.forcefieldhelp.update_potential(system, forcefield)[source]¶

Evaluate the potential energy and store it on the system.

Parameters:

system (object like System) – The system to update.
forcefield (object like ForceField) – The forcefield used to evaluate the potential.

Returns:

float – The potential energy (also written to system.vpot).

pyretis.core.forcefieldhelp.update_potential_and_force(system, forcefield)[source]¶

Evaluate potential, force, and virial and store them on the system.

Parameters:

system (object like System) – The system to update.
forcefield (object like ForceField) – The forcefield used.

Returns:

vpot (float) – The potential energy.
force (numpy.ndarray) – The force array.
virial (numpy.ndarray) – The virial tensor.

pyretis.core.provenance module¶

Run provenance metadata (P7.3).

Collects enough metadata to detect “same directory, different code/settings” mistakes in production runs. Not a full environment capture — just the fields that matter for scientific auditing.

pyretis.core.provenance.collect_provenance(input_file=None)[source]¶

Return a dict of run provenance metadata.

Parameters:: input_file (str or path-like, optional) – Path to the TOML/rst input file. Its SHA-256 hash is recorded so a restart can detect if the settings changed underneath.
Returns:: info (dict) – Keys: pyretis_version, python_version, numpy_version, git_commit (or "unknown"), input_hash (or None).

pyretis.core.snapshot module¶

Canonical flat-snapshot System (the inf-flavour shape).

This module is the public landing for the snapshot System type chosen by the A3.2 decision (see docs/decisions/system_canonical_form.md). Post-A3.2c, pyretis.core.system ALSO re-exports the same class – the snapshot vs system import paths are aliases for one canonical type.

This module remains as the public name for new consumers who specifically want to communicate “this is a phasepoint-storage snapshot” rather than “this is the live System.”

pyretis.core.systemhelp module¶

System helpers that don’t involve the forcefield.

Pure-lookup helpers that work on both the harness System and the snapshot System. They cover the small bag of legacy system.method() calls (dimensionality, Boltzmann lookup, box update) that aren’t worth attaching to either System class – the free-function form means we don’t have to grow the snapshot’s API just to satisfy A3.2c’s “delete the harness” goal.

pyretis.core.systemhelp.calculate_system_temperature(system)[source]¶

Compute the current temperature from particle velocities.

Free-function form of the soon-to-go System.calculate_temperature().

Parameters:: system (object like System)
Returns:: float – Kinetic temperature.

pyretis.core.systemhelp.generate_system_velocities(system, rgen=None, seed=0, momentum=True, temperature=None, distribution='maxwell')[source]¶

Generate per-particle velocities at the system temperature.

Free-function form of the soon-to-go System.generate_velocities().

Parameters:

system (object like System) – Must have system.particles, system.units, and system.temperature['set' / 'dof'] populated.
rgen (str or object, optional) – Random generator selector / instance.
seed (int, optional) – Seed for the random generator.
momentum (bool, optional) – If True, reset the linear momentum after drawing.
temperature (float, optional) – Override target temperature. When None, taken from system.temperature['set'].
distribution (str, optional) – Currently only 'maxwell' is supported.

pyretis.core.systemhelp.get_boltzmann(system)[source]¶

Return the Boltzmann constant in the system’s unit system.

Parameters:: system (object like System) – Must expose a units attribute (string key into pyretis.core.units.CONSTANTS).
Returns:: float – Boltzmann constant for system.units.

pyretis.core.systemhelp.get_system_dim(system)[source]¶

Return the spatial dimensionality of the system.

Works for both the harness System (system.box is a Box with a .dim attribute) and the snapshot System (system.box is a 3x3 np.ndarray).

Parameters:: system (object like System)
Returns:: int – Spatial dimensionality (1, 2, or 3). Falls back to 1 when no box is attached – matches the legacy System.get_dim() fallback.

pyretis.core.systemhelp.update_system_box(system, length)[source]¶

Update the system box, creating one if needed.

Mirrors the legacy System.update_box(length) method on the harness System; on the snapshot side it overwrites the 3x3 matrix.

Parameters:

system (object like System)
length (numpy.ndarray, list, or iterable) – Box vectors / cell description.

pyretis.core.velocity module¶

Helpers for velocity generation settings.

The single user-facing selector for shooting style is the sign of sigma_v:

negative values (the default -1) select aimless shooting;
zero or positive values select soft velocity perturbations whose per-particle width is sigma_v (a scalar or a per-particle array).

The legacy aimless boolean is stripped from parsed settings (see pyretis.inout.settings._remove_legacy_tis_settings()); helpers in this module therefore only look at sigma_v.

pyretis.core.velocity.is_aimless_velocity_setting(settings)[source]¶

Return True when velocity settings select aimless shooting.

Parameters:: settings (dict) – Mapping containing a sigma_v key. A missing key is treated as the default -1 (aimless), matching the input-file default in pyretis.inout.settings.SECTIONS.

pyretis.core.velocity.make_velocity_settings(tis_settings)[source]¶

Build per-engine velocity-modification settings.

If tis_settings carries a pre-computed imass-scaled width (_sigma_v_scaled, populated by PathSimulation.__init__()), that array is forwarded; otherwise the raw sigma_v is used.

pyretis.core.mc_moves module¶

Shared Monte-Carlo path-sampling move primitives.

This module holds the engine-agnostic MC move primitives that several parts of PyRETIS need without pulling in the whole native TIS/RETIS loop: the shooting move and its helpers, and the time-reversal move. They were factored out of the native loop so that consumers which only need the primitives – notably the initial-path kick machinery (pyretis.initiation.initiate_kick, used by both the native loop and the scheduler’s native-route input shim) – do not depend on the full loop module. The native loop (pyretis’s native move suite) re-imports these names.

Important

The move bodies are kept byte-for-byte identical to their previous tis.py definitions: the random-number draw order, acceptance criteria and sub-path construction are unchanged, so results are reproducible across the move.

pyretis.core.mc_moves.shoot(ensemble, tis_settings, start_cond, shooting_point=None)[source]¶

Perform a shooting-move.

This function will perform the shooting move from a randomly selected time-slice.

Parameters:

ensemble (dict) – It contains:
- path_ensemble: object like PathEnsemble This is the path ensemble to perform the TIS step for.
- system: object like System System is used here since we need access to the temperature and to the particle list.
- order_function: object like OrderParameter The class used for obtaining the order parameter(s).
- engine: object like EngineBase The engine to use for propagating a path.
- rgen: object like RandomGenerator This is the random generator that will be used.
- interfaces: list of floats These are the interface positions on form [left, middle, right].
tis_settings (dict) – This contains the settings for TIS:
- sigma_v: velocity width. Negative values select aimless shooting.
- allowmaxlength: boolean, should paths be allowed to reach maximum length?
- maxlength: integer, maximum allowed length of paths.
start_cond (string or tuple of strings) – The starting condition for the current ensemble, ‘L’eft or ‘R’ight. (‘L’, ‘R’), the default option, implies no directional difference.
shooting_point (object like System, optional) – If given, it is the shooting point from which the path is generated.

Returns:

out[0] (boolean) – True if the path can be accepted.
out[1] (object like PathBase) – Returns the generated path.
out[2] (string) – Status of the path, this is one of the strings defined in path._STATUS.

pyretis.core.mc_moves.time_reversal(path, order_function, interfaces, start_condition)[source]¶

Perform a time-reversal move.

Parameters:

path (object like PathBase) – This is the input path which will be used for generating a new path.
order_function (object like OrderParameter) – The class used for obtaining the order parameter(s).
interfaces (list/tuple of floats) – These are the interface positions of the form [left, middle, right].
start_condition (string) – The starting condition, ‘L’eft or ‘R’ight.

Returns:

out[0] (boolean) – True if the path can be accepted.
out[1] (object like PathBase) – The time reversed path.
out[2] (string) – Status of the path, this is one of the strings defined in .path._STATUS.

pyretis.core.multires_wf module¶

Multiresolution Wire Fencing (mwf) move for the infinite-swapping route.

Ported from the upstream infretis classes/multires_wf.py (branch multires_wf). Multiresolution wire fencing generates the wire-fencing sub-paths at TWO engine resolutions: the intermediate sub-paths are shot with a small number of subcycles (cheap, “high resolution” in the number of shooting attempts) and only the final sub-path of each set is shot with the engine’s full subcycle count, before the surviving sub-path is extended to a full path and accepted with the usual sub-trajectory acceptance.

The high-level helpers (wirefence_weight_and_pick / shoot / extender / subt_acceptance / check_kick) are pyretis’s own infinite-swapping move helpers in pyretis.core.moves (the faithful port of infretis.core.tis), so this is a near-verbatim port; the only adaptations are the lower-level kick calls in _generate_segment_using_shoot() (pyretis’s modify_velocities takes the random generator explicitly and check_kick takes the TIS settings).

New [tis] keys: mwf_subcycle_small (and the per-ensemble mwf_subcycle_small_by_ensemble dict) and mwf_nsubpath; the number of sets reuses the wire-fencing n_jumps.

class pyretis.core.multires_wf._MWFSettings(nsubpath: int, nsubset: int, subcycle_small: int, subcycle_large: int)[source]¶

Bases: object

Resolved multiresolution-wire-fencing parameters for one ensemble.

nsubpath: int¶

nsubset: int¶

subcycle_large: int¶

subcycle_small: int¶

pyretis.core.multires_wf._generate_segment_using_shoot(si, idx, ens_set_sub, engine, start_cond)[source]¶

Shoot a sub-path from si.phasepoints[idx] (MWF-chosen point).

The MWF caller owns the shooting-point policy, so we build the explicit shooting point and pass it to pyretis.core.moves.shoot(), performing the velocity kick (modify_velocities + check_kick) here to preserve standard MC kick semantics.

pyretis.core.multires_wf._pick_shooting_idx(path, rgen, is_highres: bool, queue: List[int])[source]¶

Pick a shooting index according to resolution.

High resolution pops the head of queue (empty -> status "EQU", a failed sub-path); low resolution draws a uniform interior index.

pyretis.core.multires_wf._positive_int_or_none(value: Any) → int | None[source]¶: Return value if it is a positive int (not bool), else None.

pyretis.core.multires_wf._random_internal_indices(path, rgen, k: int) → List[int][source]¶: Up to k distinct interior indices of path, shuffled.

pyretis.core.multires_wf._read_mwf_settings(ens_set: Dict[str, Any], engine) → _MWFSettings[source]¶: Resolve the multiresolution settings for the current ensemble.

pyretis.core.multires_wf._temporary_subcycles(engine, new_subcycles)[source]¶: Temporarily switch the engine to new_subcycles subcycles.

pyretis.core.multires_wf.multires_wire_fencing(ens_set: Dict[str, Any], trial_path, engine, start_cond: Tuple[str, ...] = ('L',))[source]¶

Perform a Multiresolution Wire Fencing (mwf) move.

Parameters:

ens_set (dict) – Ensemble settings (interfaces, tis_set, rgen, ens_name).
trial_path (object like pyretis.core.path.Path) – The current accepted path to move from.
engine (object like pyretis.engines.engine.EngineBase) – The MD engine used for propagating.
start_cond (tuple of str) – The starting condition ("L" / "R").

Returns:

out[0] (boolean) – True if the path can be accepted.
out[1] (object like pyretis.core.path.Path) – The generated path.
out[2] (string) – The status of the path.

pyretis.core.shooting_selection module¶

Strategy objects for biased shooting-point selection.

This module defines a small, dependency-free strategy abstraction used by the biased shooting move (shooting_move = "bias"). A selector assigns a strictly positive weight w(x) to every interior frame of a path (the two end points are excluded, exactly as the uniform rnd move excludes them). The shooting point is then drawn with probability w_i / W where W = sum_j w_j is the selection partition function, and detailed balance is restored by the Metropolis acceptance factor min(1, W_old / W_new) applied in pyretis.core.tis.shoot_bias().

The weight w_i of the chosen frame cancels in the acceptance ratio because the shooting point is the same physical frame shared by the old and the new path; only the two partition functions W_old and W_new survive. See docs/decisions/biased_shooting_acceptance.md and the user documentation (docs/user/section/tis.rst) for the full derivation.

The module is intentionally free of any machine-learning or heavy dependency: it only uses numpy. A learned (committor) selector can later be added as one more ShootingPointSelector subclass whose weights() queries a model.

Important

Every random draw must use the per-ensemble random generator that is passed in to select(), never a path’s own rgen (which can be aliased across ensembles and would break continue-vs-restart equivalence). select() draws exactly one uniform number, so the random stream advances deterministically.
Weights must be strictly positive and finite. Non-positive or non-finite weights raise instead of being silently clamped – a wrong selection weight silently biases the sampled rate, which is the worst possible failure mode for this code.

class pyretis.core.shooting_selection.GaussianOrderSelector(alpha, lambda0, index=0)[source]¶

Bases: ShootingPointSelector

Gaussian bias toward a target order-parameter value.

The interior-frame weights are

\[\begin{split}w(x) = \\exp\\!\\big(-\\alpha\\,(\\lambda(x) - \\lambda_0)^2\\big),\end{split}\]

where \(\\lambda(x)\) is the index-th order-parameter component of a frame. This concentrates the shooting points near \(\\lambda_0\) (for example a barrier-top / transition-state value), which is where re-shooting is most informative. It is a cheap, analytic, machine-learning-free bias and the reference selector for the statistical-equivalence test of the biased move.

Parameters:

alpha (float) – Inverse-width of the Gaussian; must be strictly positive. Larger values concentrate the selection more tightly around lambda0. Very large values can make distant frames underflow to zero weight, which select() reports as an error – reduce alpha then.
lambda0 (float) – The order-parameter value the selection is biased toward.
index (int, optional) – Which order-parameter component to read (default 0, the progress coordinate).

__init__(alpha, lambda0, index=0)[source]¶: Initialise the Gaussian selector and validate its parameters.

__str__()[source]¶: Return a short human-readable description.

weights(path)[source]¶: Return exp(-alpha (lambda - lambda0)**2) per interior frame.

class pyretis.core.shooting_selection.ShootingPointSelector[source]¶

Bases: object

Strategy for choosing a shooting point and its acceptance weight.

A selector defines a strictly positive per-frame weight w(x) over a path’s interior frames (the end points are excluded). The shooting point is drawn with probability w_i / W (W = sum_j w_j) and the biased shooting move is made detailed-balance correct by the Metropolis factor min(1, W_old / W_new).

Subclasses only need to implement weights(); the selection and the partition-function bookkeeping are provided here so every selector shares the exact same, reproducible draw.

_validated_weights(path)[source]¶

Return the interior weights after checking the contract.

Raises:: ValueError – If the path has no interior frame, or if any weight is non-finite or not strictly positive. Failing loud here keeps a broken weight from silently biasing the sampled rate.

select(path, rgen)[source]¶

Draw an interior frame with probability proportional to w_i.

Exactly one uniform random number is drawn from rgen and mapped to a frame through the inverse cumulative weight distribution, so the draw is deterministic given the random stream and independent of the concrete generator implementation.

Parameters:

path (object like PathBase) – The path to select a shooting point from.
rgen (object like RandomGenerator) – The per-ensemble random generator. A path’s own rgen must not be used (see the module docstring).

Returns:

out[0] (int) – The index of the selected frame in path.phasepoints. It lies in [1, path.length - 2] (an interior frame).
out[1] (float) – The weight w_i of the selected frame.
out[2] (float) – The selection partition function W of path.

sum_weight(path)[source]¶

Return the selection partition function W of a path.

Parameters:: path (object like PathBase) – The path whose interior weights are summed.
Returns:: out (float) – W = sum_j w_j over the interior frames. Strictly positive.

weights(path)[source]¶

Return the interior-frame selection weights.

Parameters:: path (object like PathBase) – The path to weight. Only the interior frames path.phasepoints[1:-1] are considered.
Returns:: out (numpy.ndarray) – A 1-D array of strictly positive, finite weights, one per interior frame (length path.length - 2).

class pyretis.core.shooting_selection.UniformSelector[source]¶

Bases: ShootingPointSelector

Selector with constant weights (every interior frame equally likely).

With w == 1 the partition function is W = L - 2 (the number of interior frames) and the biased-move acceptance reduces to the standard flexible-length two-way-shooting factor min(1, (L_o - 2)/(L_n - 2)).

This selector is the correctness anchor of the biased move: running shooting_move = "bias" with UniformSelector must reproduce the statistics of the native uniform rnd move. It is not wired as the default shooting move – the uniform rnd path is left untouched.

weights(path)[source]¶: Return an array of ones, one per interior frame.

pyretis.core.shooting_selection.selection_bias_accept(rgen, sum_weight_old, sum_weight_new)[source]¶

Apply the selection-bias Metropolis test min(1, W_o/W_n).

This is the sole acceptance correction for the aimless biased shooting move (the dynamics and the shooting-point weight cancel; see pyretis.core.tis.shoot_bias()). It is a tiny, side-effect-free function – shared by the native and infinite-swapping flows – so the exact arithmetic, in particular the orientation W_old / W_new and not its inverse, can be unit-tested without an engine.

Parameters:

rgen (object) – The per-ensemble random generator; one uniform number is drawn (via draw_uniform(), so either generator flavour works).
sum_weight_old (float) – W_o, the selection partition function of the current path.
sum_weight_new (float) – W_n, the selection partition function of the trial path. Must be strictly positive.

Returns:

out (bool) – True if the trial path is accepted by the selection-bias test.

pyretis.core.shooting_selection.shooting_selector_factory(settings)[source]¶

Create a built-in shooting-point selector from settings.

Mirrors pyretis.orderparameter.order_factory(): the class key selects one of the built-in selectors and the remaining keys are passed to its constructor. User-defined selectors are loaded from a module instead (handled by pyretis.setup.common.create_shooting_selector()).

Parameters:: settings (dict) – The [shooting-selector] settings, including the class key and any constructor arguments (e.g. alpha, lambda0).
Returns:: out (object like ShootingPointSelector) – The created selector, or None if the class is unknown.

pyretis.core.system_core module¶

The canonical PyRETIS System class.

Originally ported from infretis.classes.system as a lightweight value type for phasepoint storage; A3.2c (2026-05-27) absorbed the former pyretis-native “harness” System into this class so PyRETIS has a single, unified type.

Both pyretis.core.system and pyretis.core.snapshot re-export the class defined here, which carries the canonical, unified implementation (it is no longer “internal” or “inf-flavour”; the module was renamed from the historical _system_inf in the de-brand pass).

Construction¶

System() – bare phasepoint-storage shape (all the per-state attributes None or empty until written).

System(units=..., temperature=..., box=..., post_setup=...) – live-System factory shape (matches what pyretis.setup.createsystem expects).

Bridge properties¶

pos / vel / vpot / ekin / mass / imass / force / virial / config / vel_rev route through self.particles when attached (harness-style behaviour for the factory-built case) and through per-instance backing storage when no particles are attached (pure-snapshot use as path phasepoints).

Behaviour¶

The methods on this class are thin wrappers around the canonical free functions in pyretis.core.forcefieldhelp, pyretis.core.systemhelp, and pyretis.inout.restart. New code should call those directly; the methods exist for backwards compatibility with the legacy system.X() shape.

pyretis.core.moves module¶

TIS / RETIS move suite for the infinite-swapping scheduler.

Ported from infretis.core.tis (provenance). PyRETIS already ships its own native TIS/RETIS move suite in pyretis’s native move suite with a broader move set (PPTIS / REPPTIS / stone_skipping / web_throwing / target_swap / …). Phase 4 reconciles the two: the scheduler calls into pyretis’s moves, and the genuinely-new pieces (quantis_swap_zero, the extender maxlen fix, etc.) get folded back into the native move suite.

Until then this module preserves the infinite-swapping move suite verbatim so the scheduler / repex code keeps the behaviour it was tested against.

pyretis.core¶

Package structure¶

Modules¶

Important classes defined in this package¶

List of submodules¶

pyretis.core.box module¶

Important classes defined here¶

pyretis.core.common module¶

Important methods defined here¶

pyretis.core.engine_time module¶

Important method defined here¶

pyretis.core.montecarlo module¶

Important methods defined here¶

pyretis.core.particlefunctions module¶

Important methods defined here¶

pyretis.core.particles module¶

Important classes defined here¶

pyretis.core.path module¶

Important classes defined here¶

Important methods defined here¶

pyretis.core.path_load module¶

pyretis.core.pathensemble module¶

Important classes defined here¶

pyretis.core.properties module¶

pyretis.core.random_gen module¶

Important classes defined here¶

pyretis.core.system module¶

Importable here¶

pyretis.core.units module¶

Natural constants¶

Unit conversions¶

Unit conversions and internal systems of units¶

References and footnotes¶

pyretis.core.forcefieldhelp module¶

pyretis.core.provenance module¶

pyretis.core.snapshot module¶

pyretis.core.systemhelp module¶

pyretis.core.velocity module¶

pyretis.core.mc_moves module¶

pyretis.core.multires_wf module¶

pyretis.core.shooting_selection module¶

pyretis.core.system_core module¶

Construction¶

Bridge properties¶

Behaviour¶

pyretis.core.moves module¶