pyretis.simulation package

This package defines different simulations for use with PyRETIS.

The different simulations are defined as objects which inherits from the base Simulation object defined in simulation.py. The simulation object defines as simulation as a series of tasks to be executed, typically at each step of the simulation. These tasks may produce results which can be outputted to the user in some way.

Package structure

Modules

md_simulation.py (pyretis.simulation.md_simulation)
Defines simulation classes for molecular dynamics simulations.
mc_simulation.py (pyretis.simulation.mc_simulation)
Define simulation classes for Monte Carlo simulations.
path_simulation.py (pyretis.simulation.path_simulation)
Defines simulation classes for path simulations.
simulation.py (pyretis.simulation.simulation)
Defines the Simulation class which is the base class for simulations.
simulation_task.py (pyretis.simulation.simulation_task)
Defines classes for handling of simulation tasks.

Important classes defined in this package

Simulation (Simulation)
The base class for simulations.
SimulationTask (SimulationTask)
A class for creating tasks for simulations.
SimulationSingleTIS (SimulationSingleTIS)
A class for running a TIS simulation for a single ensemble.
SimulationRETIS (SimulationRETIS)
A class for running a RETIS simulation for a set of ensembles.

pyretis.simulation.mc_simulation module

Definition of simulation objects for Monte Carlo simulations.

This module defines some classes and functions for performing Monte Carlo simulations.

Important classes defined here

UmbrellaWindowSimulation (UmbrellaWindowSimulation)
Defines a simulation for performing umbrella window simulations. Several umbrella window simulations can be joined to perform a umbrella simulation.
class pyretis.simulation.mc_simulation.UmbrellaWindowSimulation(system, umbrella, overlap, rgen, maxdx, mincycle=0, startcycle=0)[source]

Bases: pyretis.simulation.simulation.Simulation

This class defines a Umbrella simulation.

The Umbrella simulation is a special case of the simulation class with settings to simplify the execution of the umbrella simulation.

system

object like System – The system to act on.

umbrella

list = [float, float] – The umbrella window.

overlap

float – The positions that must be crossed before the simulation is done.

startcycle

int – The current simulation cycle.

mincycle

int – The MINIMUM number of cycles to perform.

rgen

object like RandomGenerator – Object to use for random number generation.

maxdx

float – Maximum allowed displacement in the Monte Carlo step.

__str__()[source]

Return some info about the simulation as a string.

is_finished()[source]

Check if simulation is done.

In the umbrella simulation, the simulation is finished when we cycle is larger than maxcycle and all particles have crossed self.overlap.

Returns:out – True if simulation is finished, False otherwise.
Return type:boolean
restart_info()[source]

Return restart info.

Here we report the cycle number and the random number generator status.

simulation_type = 'umbrella-window'

pyretis.simulation.md_simulation module

Definitions of simulation objects for molecular dynamics simulations.

This module contains definitions of classes for performing molecular dynamics simulations.

Important classes defined here

SimulationNVE (SimulationNVE)
Definition of a simple NVE simulation. The engine used for this simulation must have dynamics equal to NVE.
SimulationMDFlux (SimulationMDFlux)
Definition of a simulation for determining the initial flux. This is used for calculating rates in TIS simulations.
class pyretis.simulation.md_simulation.SimulationMD(system, engine, steps=0, startcycle=0)[source]

Bases: pyretis.simulation.simulation.Simulation

A generic MD simulation.

This class is used to define a MD simulation without whistles and bells.

system

object like System – This is the system the simulation will act on.

engine

object like EngineBase – The engine to use for integrating the equations of motion. The engine must have engine.dynamics == ‘NVE’ in order for it to be usable in this simulation.

__str__()[source]

Return a string with info about the simulation.

restart_info()[source]

Return restart info.

Here we report the cycle number and the random number generator status.

simulation_type = 'md'
class pyretis.simulation.md_simulation.SimulationNVE(system, engine, steps=0, startcycle=0)[source]

Bases: pyretis.simulation.md_simulation.SimulationMD

A MD NVE simulation class.

This class is used to define a NVE simulation with some additional additional tasks/calculations.

system

object like System – This is the system the simulation will act on.

engine

object like EngineBase – The engine to use for integrating the equations of motion. The engine must have engine.dynamics == ‘NVE’ in order for it to be usable in this simulation.

__str__()[source]

Return a string with info about the simulation.

simulation_type = 'md-nve'
class pyretis.simulation.md_simulation.SimulationMDFlux(system, orderp, engine, interfaces, steps=0, startcycle=0)[source]

Bases: pyretis.simulation.md_simulation.SimulationMD

A simulation for obtaining the initial flux for TIS.

This class is used to define a MD simulation where the goal is to calculate crossings in order to obtain the initial flux for a TIS calculation.

system

object like System – This is the system the simulation will act on.

engine

object like EngineBase – This is the integrator that is used to propagate the system in time.

interfaces

list of floats – These floats defines the interfaces used in the crossing calculation.

leftside_prev

list of booleans – These are used to store the previous positions with respect to the interfaces.

__str__()[source]

Return a string with info about the simulation.

load_restart_info(info)[source]

Load the restart information.

restart_info()[source]

Return restart info.

Here we report the cycle number and the random number generator status.

simulation_type = 'md-flux'
step()[source]

Run a simulation step.

Rather than using the tasks for the more general simulation, we here just executing what we need.

Returns:out – This list contains the results of the defined tasks.
Return type:dict

pyretis.simulation.path_simulation module

Definitions of simulation objects for path sampling simulations.

This module defines simulations for performing path sampling simulations.

Important classes defined here

SimulationSingleTIS (SimulationSingleTIS)
Definition of a TIS simulation for a single path ensemble.
SimulationRETIS (SimulationRETIS)
Definition of a RETIS simulation.
class pyretis.simulation.path_simulation.PathSimulation(system, order_function, engine, path_ensembles, rgen, settings, steps=0, startcycle=0)[source]

Bases: pyretis.simulation.simulation.Simulation

A base class for TIS/RETIS simulations.

engine

object like EngineBase – This is the integrator that is used to propagate the system in time.

path_ensembles

list of objects like PathEnsemble – This is used for storing results for the different path ensembles.

rgen

object like RandomGenerator – This is a random generator used for the generation of paths.

system

object like System – This is the system the simulation will act on.

settings

dict – A dictionary with TIS and RETIS settings. We expect that we can find settings['tis'] and possibly settings['retis']. For settings['tis'] we further expect to find the keys:

  • aimless: Determines if we should do aimless shooting (True) or not (False).
  • sigma_v: Scale used for non-aimless shooting.
  • seed: A integer seed for the random generator used for the path ensemble we are simulating here.

Note that the pyretis.core.tis.make_tis_step_ensemble() method will make use of additional keys from settings['tis']. Please see this method for further details. For the settings['retis'] we expect to find the following keys:

  • swapfreq: The frequency for swapping moves.
  • relative_shoots: If we should do relative shooting for the ensembles.
  • nullmoves: Should we perform null moves.
  • swapsimul: Should we just swap a single pair or several pairs.
required_settings

tuple of strings – This is just a list of the settings that the simulation requires. Here it is used as a check to see that we have all we need to set up the simulation.

name = 'Generic path simulation'
required_settings = ('tis',)
restart_info()[source]

Return restart info.

Here we report the cycle number and the random number generator status.

simulation_type = 'generic-path'
class pyretis.simulation.path_simulation.SimulationSingleTIS(system, order_function, engine, path_ensemble, rgen, settings, steps=0, startcycle=0)[source]

Bases: pyretis.simulation.path_simulation.PathSimulation

A single TIS simulation.

This class is used to define a TIS simulation where the goal is to calculate crossing probabilities for a single path ensemble.

path_ensemble

object like PathEnsemble – This is used for storing results for the simulation. Note that we also have the path_ensembles attribute defined by the parent class. For ideological reasons we also like to have a path_ensemble attribute since this class is intended for simulating a single TIS ensemble only.

__str__()[source]

Just a small function to return some info about the simulation.

name = 'Single TIS simulation'
required_settings = ('tis',)
simulation_type = 'tis'
step()[source]

Perform a TIS simulation step.

Returns:out – This list contains the results of the TIS step.
Return type:dict
class pyretis.simulation.path_simulation.SimulationRETIS(system, order_function, engine, path_ensembles, rgen, settings, steps=0, startcycle=0)[source]

Bases: pyretis.simulation.path_simulation.PathSimulation

A RETIS simulation.

This class is used to define a RETIS simulation where the goal is to calculate crossing probabilities for a several path ensembles.

The attributes are documented in the parent class, please see: py:class:.PathSimulation.

__str__()[source]

Just a small function to return some info about the simulation.

name = 'RETIS simulation'
required_settings = ('tis', 'retis')
simulation_type = 'retis'
step()[source]

Perform a RETIS simulation step.

Returns:out – This list contains the results of the defined tasks.
Return type:dict

pyretis.simulation.simulation module

Definitions of generic simulation objects.

This module defines the generic simulation object. This is the base class for all other simulations.

Important classes defined here

Simulation (Simulation)
Object defining a generic simulation.
class pyretis.simulation.simulation.Simulation(steps=0, startcycle=0)[source]

Bases: object

This class defines a generic simulation.

cycle

dict of integers – This dictionary stores information about the number of cycles. The keywords are:

  • end: Represents the cycle number where the simulation should end.
  • step: The current cycle number.
  • start: The cycle number we started at.
  • stepno: The number of cycles we have performed to arrive at cycle number given by cycle[‘step’].

Note that cycle[‘stepno’] might be different from cycle[‘step’] since cycle[‘start’] might be != 0.

task

list of objects like SimulationTask – This is the list of simulation tasks to execute.

first_step

boolean – True if the first step has not been executed yet.

system

object like System – This is the system the simulation will act on.

__str__()[source]

Just a small function to return some info about the simulation.

add_task(task, position=None)[source]

Add a new simulation task.

A task can still be added manually by simply appending to self.task. This function will however do some checks so that the task added can be executed.

Parameters:
  • task (dict) –

    A dict defining the task. A task is represented by a object of type SimulationTask from .simulation_task with some additional settings on how to store the output and when to execute the task. Note that the actual execution of the task in controlled in the object. The keywords are:

    • func: A function to execute.
    • args which stores the arguments for the function.
    • kwargs which store the keyword arguments for the function.
    • when which stores when the task should be executed.
    • first which is a boolean which determines if the task should be executed on the initial step, i.e. before the full simulation starts.
    • result which is used to label the result. This is used for output.
  • position (int) – Can be used to placed the task at a specific position.

Note

SimulationTask will do some tests on the consistency of the keys ‘func’, ‘args’ and ‘kwargs’. If this is not consistent, it will raise an AssertionError.

See also

SimulationTask object in .simulation_task.

execute_tasks()[source]

Execute all the tasks in sequential order.

Returns:
  • results (dict) – The results from the different tasks (if any).
  • first (boolean) – This is just to do the initial tasks, i.e. tasks that should be done before the simulation starts.
extend_cycles(steps)[source]

Extend a simulation with the given number of steps.

Parameters:steps (int) – The number of steps to extend the simulation with.
Returns:out – Returns None but modifies self.cycle.
Return type:None
is_finished()[source]

Determine if the simulation is finished.

In this object, the simulation is done if the current step number is larger than the end cycle. Note that the number of steps performed is dependent of the value of self.cycle[‘start’].

Returns:out – True if simulation is finished, False otherwise.
Return type:boolean
load_restart_info(info)[source]

Load restart information.

Note, we do not change the end property here as we probably are extending a simulation.

Parameters:info (dict) – The dictionary with the restart information, should be similar to the dict produced by restart_info().
restart_info()[source]

Return information which can be used to restart the simulation.

run(output=None)[source]

Run a simulation.

The intended usage is for simulations where all tasks have been defined in self.tasks.

Note

This function will simply run the tasks. In general this is probably too generic for the simulation you want. It is perhaps best to modify the run function of your simulation object to tailor your simulation.

Parameters:output (list of objects like OutputTask) – If outputs are given, they will be executed here.
Yields:out (dict) – This dictionary contains the results from the simulation.
simulation_type = 'generic'
step()[source]

Execute a simulation step.

Here, the tasks in self.task will be executed sequentially.

Returns:out – This dictionary contains the results of the defined tasks. It is obtained as the return value from self.execute_tasks().
Return type:dict

Note

This function will have ‘side effects’ and update/change the state of other attached variables such as the system or other variables that are not explicitly shown. This is intended. In order to see what actually is happening when running step(), investigate the tasks defined in self.task.

pyretis.simulation.simulation_task module

Definition of a class for simulation tasks.

Important classes defined here

SimulationTask (SimulationTask)
A class representing a simulation task.
class pyretis.simulation.simulation_task.SimulationTask(function, args=None, kwargs=None, when=None, result=None, first=False)[source]

Bases: object

Representation of simulation tasks.

This class defines a task object. A task is executed at specific points, at regular intervals etc. in a simulation. A task will typically provide a result, but it does not need to. I can simply just alter the state of the passed argument(s).

function

function – The function to execute.

when

dict – Determines if the task should be executed.

args

list – List of arguments to the function.

kwargs

dict – The keyword arguments to the function.

first

boolean – True if this task should be executed before the first step of the simulation.

result

string – This is a label for the result created by the task.

__call__(step)[source]

Execute the task.

Parameters:step (dict of ints) –

The keys are:

  • ’step’: the current cycle number.
  • ’start’: the cycle number at the start.
  • ’stepno’: the number of cycles we have performed so far.
Returns:out – The result of self.execute(step).
Return type:unknown type
__str__()[source]

Output info about the task.

execute(step)[source]

Execute the task.

Parameters:step (dict of ints) –

The keys are:

  • ’step’: the current cycle number.
  • ’start’: the cycle number at the start.
  • ’stepno’: the number of cycles we have performed so far.
Returns:out – The result of running self.function.
Return type:unknown type
result

Return the result label.

run_first()[source]

Return True if task should be executed before first step.

update_when(when)[source]

Update when to new value(s).

It will only update self.when for the keys given in the input when.

Parameters:when (dict) – This dict contains the settings to update.
Returns:out – Returns None but modifies self.when.
Return type:None
pyretis.simulation.simulation_task.execute_now(step, when)[source]

Determine if a task should be executed or not at this step.

Parameters:
  • step (dict of ints) – Keys are ‘step’ (current cycle number), ‘start’ cycle number at start ‘stepno’ the number of cycles we have performed so far.
  • when (dict) – This dict determines when the function should be executed.
Returns:

out – True of the task should be executed.

Return type:

boolean