pyretis.engines package

Definition of engines.

This package defines engines for PyRETIS. The engines are responsible for carrying out dynamics for a system. This can in principle both be molecular dynamics or Monte Carlo dynamics. Typically, with RETIS, this will be molecular dynamics in some form in order to propagate the equations of motion and obtain new trajectories.

Package structure

Modules

engine.py (pyretis.engines.engine)
Defines the base engine class.
internal.py (pyretis.engines.internal)
Defines internal PyRETIS engines.
external.py (pyretis.engines.external)
Defines the interface for external engines.
gromacs.py (pyretis.engines.gromacs)
Defines an engine for use with GROMACS.

Important methods defined here

engine_factory (engine_factory())
A method to create engines from settings.
pyretis.engines.engine_factory(settings)[source]

Create an engine according to the given settings.

This function is included as a convenient way of setting up and selecting an engine. It will return the created engine.

Parameters:settings (dict) – This defines how we set up and select the engine.
Returns:out – The object representing the engine to use in a simulation.
Return type:object like EngineBase

pyretis.engines.engine module

Definition of PyRETIS engines.

This module defines the base class for the engines.

Important classes defined here

EngineBase (EngineBase)
The base class for engines.
class pyretis.engines.engine.EngineBase(description)[source]

Bases: object

Abstract base class for engines.

The engines perform molecular dynamics (or Monte Carlo) and they are assumed to act on a system. Typically they will integrate Newtons equation of motion in time for that system.

description

string – Short string description of the engine. Used for printing information about the integrator.

__str__()[source]

Return the string description of the integrator.

static add_to_path(path, phase_point, left, right)[source]

Add a phase point and perform some checks.

This method is intended to be used by the propagate methods.

Parameters:
  • path (object like PathBase) – The path to add to.
  • phase_point (dict) – The phase_point to add.
  • left (float) – The left interface.
  • right (float) – The right interface.
calculate_order(order_function, system, xyz=None, vel=None, box=None)[source]

Obtain the order parameter.

clean_up()[source]

Perform clean up after using the engine.

dump_phasepoint(phasepoint, deffnm=None)[source]

Dump phase point to a file.

engine_type = None
integration_step(system)[source]

Perform one time step of the integration.

kick_across_middle(system, order_function, rgen, middle, tis_settings)[source]

Force a phase point across the middle interface.

modify_velocities(system, rgen, sigma_v=None, aimless=True, momentum=False, rescale=None)[source]

Modify the velocities of the current state.

Parameters:
  • system (object like System) – System is used here since we need access to the particle list.
  • rgen (object like RandomGenerator) – This is the random generator that will be used.
  • sigma_v (numpy.array, optional) – These values can be used to set a standard deviation (one for each particle) for the generated velocities.
  • aimless (boolean, optional) – Determines if we should do aimless shooting or not.
  • momentum (boolean, optional) – If True, we reset the linear momentum to zero after generating.
  • rescale (float, optional) – In some NVE simulations, we may wish to re-scale the energy to a fixed value. If rescale is a float > 0, we will re-scale the energy (after modification of the velocities) to match the given float.
Returns:

  • dek (float) – The change in the kinetic energy.
  • kin_new (float) – The new kinetic energy.

propagate(path, system, orderp, interfaces, reverse=False)[source]

Propagate equations of motion.

pyretis.engines.external module

Definition of external engines.

This module defines the base class for external MD engines. This class is sub-classed by all other external MD engines.

Important classes defined here

ExternalMDEngine (ExternalMDEngine)
The base class for external scripts. This defines the actual interface to external programs.
class pyretis.engines.external.ExternalMDEngine(description, timestep, subcycles)[source]

Bases: pyretis.engines.engine.EngineBase

Base class for interfacing external MD engines.

This class defines the interface to external programs. The interface will define how we interact with the external programs and how we write input files for them and read output files. New engines should inherit from this class and implement the following methods:

description

string – Short string which a description about the external script. This can for instance be what program we are interfacing. This is used for output of information to the user.

timestep

float – The time step used for the external engine.

subcycles

integer – The number of steps the external step is composed of. That is: each external step is really composed of subcycles number of iterations.

_abc_cache = <_weakrefset.WeakSet object>
_abc_negative_cache = <_weakrefset.WeakSet object>
_abc_negative_cache_version = 45
_abc_registry = <_weakrefset.WeakSet object>
static _copyfile(source, dest)[source]

Copy file from source to destination.

_extract_frame(traj_file, idx, out_file)[source]

Extract a frame from a trajectory file.

Parameters:
  • traj_file (string) – The trajectory file to open.
  • idx (integer) – The frame number we look for.
  • out_file (string) – The file to dump to.
static _modify_input(sourcefile, outputfile, settings, delim='=')[source]

Modify input file for external software.

Here we assume that the input file has a syntax consisting of keyword = setting. We will only replace settings for the keywords we find in the file that is also inside the settings dictionary.

Parameters:
  • sourcefile (string) – The path of the file to use for creating the output.
  • outputfile (string) – The path of the file to write.
  • settings (dict) – A dictionary with settings to write.
  • delim (string) – The delimiter used for separation keywords from settings
static _movefile(source, dest)[source]

Move file from source to destination.

_name_output(basename)[source]

Return the name of the output file.

_propagate_from(name, path, system, order_function, interfaces, reverse=False)[source]

Run the actual propagation using the specific engine.

This method is called after propagate(). And we assume that the necessary preparations before the actual propagation (e.g. dumping of the configuration etc.) is handled in that method.

Parameters:
  • name (string) – A name to use for the trajectory we are generating.
  • path (object like PathBase) – This is the path we use to fill in phase-space points.
  • system (object like System) – The system object gives the initial state.
  • order_function (object like OrderParameter) – The object used for calculating the order parameter.
  • interfaces (list of floats) – These interfaces define the stopping criterion.
  • reverse (boolean) – If True, the system will be propagated backwards in time.
Returns:

  • success (boolean) – This is True if we generated an acceptable path.
  • status (string) – A text description of the current status of the propagation.

_read_configuration(filename)[source]

Read output configuration from external software.

Parameters:filename (string) – The file to open and read a configuration from.
Returns:
  • out[0] (numpy.array) – The dimensions of the simulation box.
  • out[1] (numpy.array) – The positions found in the given filename.
  • out[2] (numpy.array) – The velocities found in the given filename.
static _read_input_settings(sourcefile, delim='=')[source]

Read input settings for simulation input files.

Here we assume that the input file has a syntax consisting of keyword = setting, where = can be any string given in the input parameter delim.

Parameters:
  • sourcefile (string) – The path of the file to use for creating the output.
  • delim (string) – The delimiter used for separation keywords from settings
Returns:

settings – The settings found in the file.

Return type:

dict of strings

Note

Important: We are here assuming that there will ONLY be one keyword per line.

_remove_files(dirname, files)[source]

Remove files from a directory.

Parameters:
  • dirname (string) – Where we are removing.
  • files (list of strings) – A list with files to remove.
static _removefile(filename)[source]

Remove a given file if it exist.

_reverse_velocities(filename, outfile)[source]

Reverse velocities in a given snapshot.

Parameters:
  • filename (string) – Input file with velocities.
  • outfile (string) – File to write with reversed velocities.
calculate_order(order_function, system, xyz=None, vel=None, box=None)[source]

Calculate order parameter from configuration in a file.

Note, if xyz, vel or box are given, we will NOT read positions, velocity and box information from the current configuration file.

Parameters:
  • order_function (object like OrderParameter) – The class used for calculating the order parameter.
  • system (object like System) – The object the order parameter is acting on.
  • xyz (numpy.array, optional) – The positions to use, in case we have already read them somewhere else. We will then not attempt to read the again.
  • vel (numpy.array, optional) – The velocities to use, in case we already have read them.
  • box (numpy.array, optional) – The current box vectors, in case we already have read them.
Returns:

out – The calculated order parameter(s).

Return type:

list of floats

clean_up()[source]

Will remove all files from the current directory.

dump_config(config, deffnm='conf')[source]

Extract configuration frame from a system if needed.

Parameters:
  • config (tuple) – The configuration given as (filename, index).
  • deffnm (string, optional) – The base name for the file we dump to.
Returns:

out – The file name we dumped to. If we did not in fact dump, this is because the system contains a single frame and we can use it directly. Then we return simply this file name.

Return type:

string

Note

If the velocities should be reversed, this is handled elsewhere.

dump_frame(system, deffnm='conf')[source]

Just dump the frame from a system object.

dump_phasepoint(phasepoint, deffnm='conf')[source]

Just dump the frame from a system object.

engine_type = 'external'
exe_dir

Return the directory we are currently using.

execute_command(cmd, cwd=None, inputs=None)[source]

Execute an external command for the engine.

We are here executing a command and then waiting until it finishes. The standard out and standard error are piped to files during the execution, and can be inspected if the command fails. This method returns the return code of the issued command.

Parameters:
  • cmd (list of strings) – The command to execute.
  • cwd (string or None) – The current working directory to set for the command.
  • inputs (bytes or None) – Possible input to give to the command. This are not arguments but more akin to keystrokes etc. that the external command may take.
Returns:

out – The return code of the command.

Return type:

int

integration_step(system)[source]

Perform one time step of the integration.

For external engines, it does not make much sense to run single steps unless we absolutely have to. We therefore just fail here. I.e. the external engines are not intended for performing pure MD simulations.

If it’s absolutely needed, there is a self.step() method which can be used, for instance in the initialisation.

Parameters:system (object like System) – A system to run the integration step on.
kick_across_middle(system, order_function, rgen, middle, tis_settings)[source]

Force a phase point across the middle interface.

This is accomplished by repeatedly kicking the pahse point so that it crosses the middle interface.

Parameters:
  • system (object like System) – This is the system that contains the particles we are investigating
  • order_function (object like OrderParameter) – The object used for calculating the order parameter.
  • rgen (object like RandomGenerator) – This is the random generator that will be used.
  • middle (float) – This is the value for the middle interface.
  • tis_settings (dict) –

    This dictionary contains settings for TIS. Explicitly used here:

    • zero_momentum: boolean, determines if the momentum is zeroed
    • rescale_energy: boolean, determines if energy is re-scaled.
Returns:

  • out[0] (dict) – This dict contains the phase-point just before the interface. It is obtained by calling the get_particle_state() of the particles object.
  • out[1] (dict) – This dict contains the phase-point just after the interface. It is obtained by calling the get_particle_state() of the particles object.

Note

This function will update the system state so that the system.particles.get_particle_state() == out[1]. This is more convenient for the following usage in the generate_initial_path_kick function.

propagate(path, system, order_function, interfaces, reverse=False)[source]

Propagate the equations of motion with the external code.

This method will explicitly do the common set-up, before calling more specialised code for doing the actual propagation.

Parameters:
  • path (object like PathBase) – This is the path we use to fill in phase-space points. We are here not returning a new path - this since we want to delegate the creation of the path to the method that is running propagate.
  • system (object like System) – The system object gives the initial state for the integration. The initial state is stored and the system is reset to the initial state when the integration is done.
  • order_function (object like OrderParameter) – The object used for calculating the order parameter.
  • interfaces (list of floats) – These interfaces define the stopping criterion.
  • reverse (boolean) – If True, the system will be propagated backwards in time.
Returns:

  • success (boolean) – This is True if we generated an acceptable path.
  • status (string) – A text description of the current status of the propagation.

step(system, name)[source]

Perform a single step with the external engine.

Parameters:
  • system (object like System) – The system we are integrating.
  • name (string) – To name the output files from the external engine.
Returns:

out – The name of the output configuration, obtained after completing the step.

Return type:

string

pyretis.engines.gromacs module

A GROMACS external MD integrator interface.

This module defines a class for using GROMACS as an external engine.

Important classes defined here

GromacsEngine (GromacsEngine)
A class responsible for interfacing GROMACS.
class pyretis.engines.gromacs.GromacsEngine(gmx, mdrun, input_path, timestep, subcycles, maxwarn=0, gmx_format='g96', write_vel=True, write_force=False)[source]

Bases: pyretis.engines.external.ExternalMDEngine

A class for interfacing GROMACS.

This class defines the interface to GROMACS.

gmx

string – The command for executing GROMACS. Note that we are assuming that we are using version 5 of GROMACS.

mdrun

string – The command for executing GROMACS mdrun. In some cases this executable can be different from gmx mdrun.

mdrun_c

string – The command for executing GROMACS mdrun when continuing a simulation. This is derived from the mdrun command.

input_path

string – The directory where the input files are stored.

input_files

dict of strings – The names of the input files. We expect to find the keys 'conf', 'input' 'topology'.

ext_time

float – The time to extend simulations by. It is equal to timestep * subcycles.

maxwarn

integer – Setting for the GROMACS grompp maxwarn option.

ext

string – This string selects the output format for GROMACS.

get_energies(energy_file)[source]

Return energies from a GROMACS run.

Parameters:energy_file (string) – The file to read energies from.
modify_velocities(system, rgen, sigma_v=None, aimless=True, momentum=False, rescale=None)[source]

Modify the velocities of the current state.

This method will modify the velocities of a time slice.

Parameters:
  • system (object like System) – System is used here since we need access to the particle list.
  • rgen (object like RandomGenerator) – This is the random generator that will be used.
  • sigma_v (numpy.array, optional) – These values can be used to set a standard deviation (one for each particle) for the generated velocities.
  • aimless (boolean, optional) – Determines if we should do aimless shooting or not.
  • momentum (boolean, optional) – If True, we reset the linear momentum to zero after generating.
  • rescale (float, optional) – In some NVE simulations, we may wish to re-scale the energy to a fixed value. If rescale is a float > 0, we will re-scale the energy (after modification of the velocities) to match the given float.
Returns:

  • dek (float) – The change in the kinetic energy.
  • kin_new (float) – The new kinetic energy.

step(system, name)[source]

Perform a single step with GROMACS.

Parameters:
  • system (object like System) – The system we are integrating.
  • name (string) – To name the output files from the GROMACS step.
Returns:

out – The name of the output configuration, obtained after completing the step.

Return type:

string

pyretis.engines.internal module

Definition of numerical MD integrators.

These integrators are representations of engines for performing molecular dynamics. Typically they will propagate Newtons equations of motion in time numerically.

Important classes defined here

MDEngine (MDEngine)
Base class for internal MDEngines.
Verlet (Verlet)
A Verlet MD integrator.
VelocityVerlet (VelocityVerlet)
A Velocity Verlet MD integrator.
Langevin (Langevin)
A Langevin MD integrator.
class pyretis.engines.internal.MDEngine(timestep, description, dynamics=None)[source]

Bases: pyretis.engines.engine.EngineBase

Base class for internal MD integrators.

This class defines an internal MD integrator. This class of integrators work with the positions and velocities of the system object directly. Further, we make use of the system object in order to update forces etc.

delta_t

float – Time step for the integration.

description

string – Description of the MD integrator.

dynamics

str – A short string to represent the type of dynamics produced by the integrator (NVE, NVT, stochastic, …).

__call__(system)[source]

To allow calling MDEngine(system).

Here, we are just calling self.integration_step(system).

Parameters:system (object like System) – The system we are integrating.
Returns:out – Does not return anything, but will update the particles.
Return type:None
static calculate_order(order_function, system, xyz=None, vel=None, box=None)[source]

Return the order parameter.

This method is just to help calculating the order parameter in cases where only the engine can do it! This creates a uniform behaviour for both internal and external engines. For internal engine this may not be so useful in it self, since we could just call order.calculate(system). But for external engines, we can not assume that the system is able to calculate the order parameter, this because the state of the system might be stored in a file which only the engine knows how to read.

Parameters:
  • order_function (object like OrderParameter) – The object used for calculating the order parameter(s).
  • system (object like System) – The system containing the corrent positions and velocities.
  • xyz (numpy.array, optional) – The positions to use. Typically for internal engines, this is not needed. It is included here as it can be used for testing and also to be compatible with the generic function defined by the parent.
  • vel (numpy.array, optional) – The velocities to use.
  • box (numpy.array, optional) – The current box vectors.
Returns:

out – The calculated order parameter(s).

Return type:

list of floats

clean_up()[source]

Clean up after using the engine.

Currently this is only included for compatibility with external integrators.

dump_phasepoint(phasepoint, deffnm=None)[source]

For compatibility with external integrators.

engine_type = 'internal'
integration_step(system)[source]

Perform one time step of the integration.

Parameters:system (object like System) – The system we are acting on.
Returns:out – Does not return anything, in derived classes it will typically update the given System.
Return type:None
invert_dt()[source]

Invert the time step for the integration.

Returns:out – True if time step is positive, False otherwise.
Return type:boolean
kick_across_middle(system, order_function, rgen, middle, tis_settings)[source]

Force a phase point across the middle interface.

This is accomplished by repeatedly kicking the pahse point so that it crosses the middle interface.

Parameters:
  • system (object like System) – This is the system that contains the particles we are investigating
  • order_function (object like OrderParameter) – The object used for calculating the order parameter.
  • rgen (object like RandomGenerator) – This is the random generator that will be used.
  • middle (float) – This is the value for the middle interface.
  • tis_settings (dict) –

    This dictionary contains settings for TIS. Explicitly used here:

    • zero_momentum: boolean, determines if the momentum is zeroed
    • rescale_energy: boolean, determines if energy is re-scaled.
Returns:

  • out[0] (dict) – This dict contains the phase-point just before the interface. It is obtained by calling the get_particle_state() of the particles object.
  • out[1] (dict) – This dict contains the phase-point just after the interface. It is obtained by calling the get_particle_state() of the particles object.

Note

This function will update the system state so that the system.particles.get_particle_state() == out[1]. This is more convenient for the following usage in the generate_initial_path_kick function.

static modify_velocities(system, rgen, sigma_v=None, aimless=True, momentum=False, rescale=None)[source]

Modify the velocities of the current state.

This method will modify the velocities of a time slice. And it is part of the integrator since it, conceptually, fits here: we are acting on the system and modifying it.

Parameters:
  • system (object like System) – System is used here since we need access to the particle list.
  • rgen (object like RandomGenerator) – This is the random generator that will be used.
  • sigma_v (numpy.array, optional) – These values can be used to set a standard deviation (one for each particle) for the generated velocities.
  • aimless (boolean, optional) – Determines if we should do aimless shooting or not.
  • momentum (boolean, optional) – If True, we reset the linear momentum to zero after generating.
  • rescale (float, optional) – In some NVE simulations, we may wish to re-scale the energy to a fixed value. If rescale is a float > 0, we will re-scale the energy (after modification of the velocities) to match the given float.
Returns:

  • dek (float) – The change in the kinetic energy.
  • kin_new (float) – The new kinetic energy.

propagate(path, system, orderp, interfaces, reverse=False)[source]

Generate a path by integrating until a criterion is met.

This function will generate a path by calling the function specifying the integration step repeatedly. The integration is carried out until the order parameter has passed the specified interfaces or if we have integrated for more than a specified maximum number of steps. The given system defines the initial state and the system is reset to it’s initial state when this method is done.

Parameters:
  • path (object like PathBase) – This is the path we use to fill in phase-space points. We are here not returning a new path - this since we want to delegate the creation of the path (type) to the method that is running propagate.
  • system (object like System) – The system object gives the initial state for the integration. The initial state is stored and the system is reset to the initial state when the integration is done.
  • orderp (object like OrderParameter) – The object used for calculating the order parameter.
  • interfaces (list of floats) – These interfaces define the stopping criterion.
  • reverse (boolean) – If True, the system will be propagated backwards in time.
Returns:

  • success (boolean) – This is True if we generated an acceptable path.
  • status (string) – A text description of the current status of the propagation.

class pyretis.engines.internal.Verlet(timestep)[source]

Bases: pyretis.engines.internal.MDEngine

The Verlet MD integrator.

This class defines the Verlet MD integrator.

half_idt

float – Half of inverse time step: 0.5 / delta_t

delta_t2

float – Squared time step: delta_t**2

previous_pos

numpy.array – Stores the previous positions of the particles.

integration_step(system)[source]

Perform one Verlet integration step.

Parameters:system (object like System) – The system to integrate/act on. Assumed to have a particle list in system.particles.
Returns:out – Does not return anything, but alters the state of the given system.
Return type:None
set_initial_positions(particles)[source]

Get initial positions for the Verlet integration.

Parameters:particles (object like Particles) – The initial configuration. Positions and velocities are required.
class pyretis.engines.internal.VelocityVerlet(timestep)[source]

Bases: pyretis.engines.internal.MDEngine

The Velocity Verlet MD integrator.

This class defines the Velocity Verlet integrator.

half_delta_t

float – Half of timestep.

integration_step(system)[source]

Velocity Verlet integration, one time step.

Parameters:system (object like System) – The system to integrate/act on. Assumed to have a particle list in system.particles.
Returns:out – Does not return anything, but alters the state of the given system.
Return type:None
class pyretis.engines.internal.Langevin(timestep, gamma, rgen=None, seed=0, high_friction=False)[source]

Bases: pyretis.engines.internal.MDEngine

The Langevin MD integrator.

This class defines a Langevin integrator.

rgen

object like RandomGenerator – This is the class that handles generation of random numbers.

gamma

float – The friction parameter.

high_friction

boolean – Determines if we are in the high friction limit and should do the over-damped version.

init_params

boolean – If true, we will initiate parameters for the Langevin integrator when integrate_step is invoked.

param_high

dict – This contains the parameters for the high friction limit. Here we integrate the equations of motion according to: r(t + dt) = r(t) + dt * f(t)/m*gamma + dr. The items in the dict are:

  • sigma : float standard deviation for the positions, used when drawing dr
  • bddt : numpy.array Equal to dt*gamma/masses, since the masses is a numpy.array this will have the same shape.
param_iner

dict – This dict contains the parameters for the non-high friction limit where we integrate the equations of motion according to: r(t + dt) = r(t) + c1 * dt * v(t) + c2*dt*dt*a(t) + dr and v(r + dt) = c0 * v(t) + (c1-c2)*dt*a(t) + c2*dt*a(t+dt) + dv. The dict contains:

  • c0 : float Corresponds to c0 in the equation above.
  • a1 : float Corresponds to c1*dt in the equation above.
  • a2 : numpy.array Corresponds to c2*dt*dt/mass in the equation above. Here we divide by the masses in order to use the forces rather than the acceleration. Since the masses might be different for different particles, this will result in a numpy.array with shape equal to the shape of the masses.
  • b1 : numpy.array Corresponds to (c1-c2)*dt/mass in the equation above. Here we also divide by the masses, resulting in a numpy.array.
  • b2 : numpy.array Corresponds to c2*dt/mass in the equation above. Here we also divide by the masses, resulting in a numpy.array.
  • mean : numpy.array (2,) The means for the bivariate Gaussian distribution.
  • cov : numpy.array (2,2) This array contains the covariance for the bivariate Gaussian distribution. param_iner[‘mean’] and param_iner[‘cov’] are used as parameters when drawing dr and dv from the bivariate distribution.

Note

Currently, we are using a multi-normal distribution from numpy. Consider replacing this one as it seems somewhat slow.

integration_step(system)[source]

Langevin integration, one time step.

Parameters:system (object like System) – The system to integrate/act on. Assumed to have a particle list in system.particles.
Returns:out – Does not return anything, but alters the state of the given system.
Return type:None
integration_step_inertia(system)[source]

Langevin integration, one time step.

Parameters:system (object like System) – The system to integrate/act on. Assumed to have a particle list in system.particles.
Returns:out – Does not return anything, but alters the state of the given system.
Return type:None
integration_step_overdamped(system)[source]

Over damped Langevin integration, one time step.

Parameters:system (object like System) – The system to integrate/act on. Assumed to have a particle list in system.particles.
Returns:out – Does not return anything, but alters the state of the given system.
Return type:None