pyretis.simulation package

pyretis.simulation package

This package defines different simulations for use with PyRETIS.

The different simulations are defined as objects which inherit 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 the 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(ensemble, settings, controls=None)[source]

Bases: Simulation

This class defines an Umbrella simulation.

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

ensemble
It contains the simulations info
  • systemobject like System

    The system to act on.

  • rgenobject like RandomGenerator

    Object to use for random number generation.

Type:dict
umbrella

The umbrella window to consider.

Type:list, [float, float]
overlap

The position we have to cross before the simulation ends.

Type:float
maxdx

Defines the maximum movement allowed in the Monte Carlo

Type:float
steps

The number of simulation steps to perform.

Type:int, optional
startcycle

The cycle we start the simulation on, can be useful if restarting.

Type:int, optional
__init__(ensemble, settings, controls=None)[source]

Initialise the umbrella simulation simulation.

Parameters:

  • ensemble (dict) –

    It contains the simulations info
    • systemobject like System

      The system to act on.

    • rgenobject like RandomGenerator

      Object to use for random number generation.

  • settings (dict) – Contains all the simulation settings.

  • controls (dict of parameters to control the simulations. Optional) –

    It can contain:
    • mincycleint, optional
      The MINIMUM number of cycles to perform. Note that in base Simulation class this is the MAXIMUM number of cycles to perform. The meaning is redefined in this class by overriding self.simulation_finished.
    • startcycleint, optional
      The current simulation cycle, i.e. where we start.
__str__()[source]

Return some info about the simulation as a string.

is_finished()[source]

Check if the 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 (boolean) – True if the simulation is finished, False otherwise.
load_restart_info(info)[source]

Load the restart information.

restart_info()[source]

Return information which can be used to restart the simulation.

Returns:info (dict,) – Contains all the updated simulation settings and counters.
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.
SimulationMD (SimulationMD)
Definition of a simulation for running somply MD.
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(ensemble, settings=None, controls=None)[source]

Bases: Simulation

A generic MD simulation.

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

__init__(ensemble, settings=None, controls=None)[source]

Only add variable.

Parameters:
  • ensemble (dict) – It contains the simulations info
    • system : object like System This is the system we are investigating.
    • engine : object like EngineBase This is the integrator that is used to propagate the system in time.
    • order_function : object like OrderParameter, optional. A class that can be used to calculate an order parameter, if needed.
  • settings (dict, optional) – This dictionary contains the settings for the simulation.
  • controls (dict of parameters, optional) – It contains:
    • steps : int, optional The number of simulation steps to perform.
    • startcycle : int, optional The cycle we start the simulation on, can be useful if restarting.
__str__()[source]

Return a string with info about the simulation.

run()[source]

Run the MD simulation.

Yields:results (dict) – The results from a single step in the simulation.
simulation_output = [{'type': 'energy', 'name': 'md-energy-file'}, {'type': 'thermo-file', 'name': 'md-thermo-file'}, {'type': 'traj-xyz', 'name': 'md-traj-file'}, {'type': 'thermo-screen', 'name': 'md-thermo-screen'}, {'type': 'order', 'name': 'md-order-file'}]
simulation_type = 'md'
class pyretis.simulation.md_simulation.SimulationMDFlux(ensemble, settings=None, controls=None)[source]

Bases: 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.

__init__(ensemble, settings=None, controls=None)[source]

Initialise the MD-Flux simulation object.

Parameters:
  • ensemble (dict) – It contains the simulations info
    • system : object like System The system to act on.
    • engine : object like EngineBase This is the integrator that is used to propagate the system in time.
    • order_function : object like OrderParameter The class used for calculating the order parameters.
  • settings (dict, optional) – This dictionary contains the settings for the simulation.
  • controls (dict of parameters, optional) – It contains:
    • steps : int, optional The number of simulation steps to perform.
    • startcycle : int, optional The cycle we start the simulation on, can be useful if restarting.
__str__()[source]

Return a string with info about the simulation.

load_restart_info(info)[source]

Load the restart information.

restart_info()[source]

Return information which can be used to restart the simulation.

Returns:info (dict) – Contains all the updated simulation settings and counters.
run()[source]

Run the MD simulation.

Yields:results (dict) – The results from a single step in the simulation.
simulation_output = [{'type': 'energy', 'name': 'flux-energy-file'}, {'type': 'traj-xyz', 'name': 'flux-traj-file'}, {'type': 'thermo-screen', 'name': 'flux-thermo-screen'}, {'type': 'order', 'name': 'flux-order-file'}, {'type': 'cross', 'name': 'flux-cross-file'}]
simulation_type = 'md-flux'
class pyretis.simulation.md_simulation.SimulationNVE(ensemble, settings=None, controls=None)[source]

Bases: SimulationMD

A MD NVE simulation class.

This class is used to define a NVE simulation. Compared with the SimulationMD we here require that the engine supports NVE dynamics.

__init__(ensemble, settings=None, controls=None)[source]

Initialise the NVE simulation object.

Here we will set up the tasks that are to be performed in the simulation, such as the integration and thermodynamics calculation(s).

Parameters:
  • ensemble (dict) – It contains the simulations info
    • system : object like System This is the system we are investigating.
    • engine : object like EngineBase This is the integrator that is used to propagate the system in time.
    • order_function : object like OrderParameter, opt A class that can be used to calculate an order parameter, if needed.
  • settings (dict, optional) – This dictionary contains the settings for the simulation.
  • controls (dict of parameters, optional) – It contains:
    • steps : int, optional The number of simulation steps to perform.
    • startcycle : int, optional The cycle we start the simulation on.
__str__()[source]

Return a string with info about the simulation.

load_restart_info(info)[source]

Load the restart information.

restart_info()[source]

Return information which can be used to restart the simulation.

Returns:info (dict,) – Contains all the updated simulation settings and counters.
simulation_output = [{'type': 'energy', 'name': 'nve-energy-file'}, {'type': 'thermo-file', 'name': 'nve-thermo-file'}, {'type': 'traj-xyz', 'name': 'nve-traj-file'}, {'type': 'thermo-screen', 'name': 'nve-thermo-screen'}, {'type': 'order', 'name': 'nve-order-file'}]
simulation_type = 'md-nve'
step()[source]

Run a single simulation step.

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

PathSimulation (PathSimulation)
The base class for path simulations.
SimulationTIS (SimulationSingleTIS)
Definition of a TIS simulation for a single path ensemble.
SimulationRETIS (SimulationRETIS)
Definition of a RETIS simulation.
SimulationPPRETIS (SimulationPPRETIS)
Definition of a PPRETIS simulation.
class pyretis.simulation.path_simulation.PathSimulation(ensembles, settings, controls)[source]

Bases: Simulation

A base class for TIS/RETIS simulations.

ensembles

Each contains:

  • path_ensemble: objects like PathEnsemble This is used for storing results for the different path ensembles.
  • engine: object like EngineBase This is the integrator that is used to propagate the system in time.
  • 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.
Type:list of dictionaries of objects
settings

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 path ensembles.
  • nullmoves: Should we perform null moves.
  • swapsimul: Should we just swap a single pair or several pairs.
required_settingstuple 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.
Type:dict
__init__(ensembles, settings, controls)[source]

Initialise the path simulation object.

Parameters:
  • ensembles (list of dicts) – Each contains:
    • path_ensemble: object like PathEnsemble This is used for storing results for the simulation. It is also used for defining the interfaces for this simulation.
    • system: object like System This is the system we are investigating.
    • order_function: object like OrderParameter The object used for calculating the order parameter.
    • engine: object like EngineBase This is the integrator that is used to propagate the system in time.
    • rgen: object like RandomGenerator This is the random generator to use in the ensemble.
  • settings (dict) – This dictionary contains the settings for the simulation.
  • controls (dict of parameters to set up and control the simulations) – It contains:
    • steps: int, optional The number of simulation steps to perform.
    • startcycle: int, optional The cycle we start the simulation on, useful for restarts.
    • rgen: object like RandomGenerator This object is the random generator to use in the simulation.
create_output_tasks(settings, progress=False)[source]

Create output tasks for the simulation.

This method will generate output tasks based on the tasks listed in simulation_output.

Parameters:
  • settings (dict) – These are the simulation settings.
  • progress (boolean) – For some simulations, the user may select to display a progress bar, we then need to disable the screen output.
initiate(settings)[source]

Initialise the path simulation.

Parameters:settings (dictionary) – The simulation settings.
load_restart_info(info)[source]

Load restart information.

Note: This method load the info for the main simulation, the actual
ensemble restart is done in initiate_restart.
Parameters:info (dict) – The dictionary with the restart information, should be similar to the dict produced by restart_info().
name = 'Generic path simulation'
required_settings = ('tis', 'retis')
restart_info()[source]

Return restart info.

The restart info for the path simulation includes the state of the random number generator(s).

Returns:info (dict,) – Contains all the updated simulation settings and counters.
run()[source]

Run a path simulation.

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

Note

This function will just run the tasks via executing step() In general, this is probably too generic for the simulation you want, if you are creating a custom simulation. Please consider customizing the run() (or the step()) method of your simulation class.

Yields:out (dict) – This dictionary contains the results from the simulation.
simulation_output = [{'type': 'pathensemble', 'name': 'path_ensemble', 'result': ('pathensemble-{}',)}, {'type': 'path-order', 'name': 'path_ensemble-order', 'result': ('path-{}', 'status-{}')}, {'type': 'path-traj-{}', 'name': 'path_ensemble-traj', 'result': ('path-{}', 'status-{}', 'pathensemble-{}')}, {'type': 'path-energy', 'name': 'path_ensemble-energy', 'result': ('path-{}', 'status-{}')}]
simulation_type = 'generic-path'
step()[source]

Perform a TIS/RETIS/PPRETIS simulation step.

Returns:out (dict) – This list contains the results of the defined tasks.
write_restart(now=False)[source]

Create a restart file.

Parameters:now (boolean, optional) – If True, the output file will be written irrespective of the step number.
class pyretis.simulation.path_simulation.SimulationRETIS(ensembles, settings, controls)[source]

Bases: PathSimulation

A RETIS simulation.

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

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

__str__()[source]

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

name = 'RETIS simulation'
required_settings = ('retis',)
simulation_output = [{'type': 'pathensemble', 'name': 'path_ensemble', 'result': ('pathensemble-{}',)}, {'type': 'path-order', 'name': 'path_ensemble-order', 'result': ('path-{}', 'status-{}')}, {'type': 'path-traj-{}', 'name': 'path_ensemble-traj', 'result': ('path-{}', 'status-{}', 'pathensemble-{}')}, {'type': 'path-energy', 'name': 'path_ensemble-energy', 'result': ('path-{}', 'status-{}')}, {'type': 'pathensemble-retis-screen', 'name': 'path_ensemble-retis-screen', 'result': ('pathensemble-{}',)}]
simulation_type = 'retis'
class pyretis.simulation.path_simulation.SimulationTIS(ensembles, settings, controls)[source]

Bases: PathSimulation

A TIS simulation.

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

__str__()[source]

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

name = 'TIS simulation'
required_settings = ('tis',)
simulation_output = [{'type': 'pathensemble', 'name': 'path_ensemble', 'result': ('pathensemble-{}',)}, {'type': 'path-order', 'name': 'path_ensemble-order', 'result': ('path-{}', 'status-{}')}, {'type': 'path-traj-{}', 'name': 'path_ensemble-traj', 'result': ('path-{}', 'status-{}', 'pathensemble-{}')}, {'type': 'path-energy', 'name': 'path_ensemble-energy', 'result': ('path-{}', 'status-{}')}, {'type': 'pathensemble-screen', 'name': 'path_ensemble-screen', 'result': ('pathensemble-{}',)}]
simulation_type = 'tis'

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)
A class defining a generic simulation.
class pyretis.simulation.simulation.Simulation(settings, controls)[source]

Bases: object

This class defines a generic simulation.

cycle

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

  • step: The current cycle number.
  • startcycle: The cycle number we started at.
  • endcycle: Represents the cycle number where the simulation should end.
  • 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[‘startcycle’] might be != 0.
Type:dict of integers
exe_dir

The path we are running the simulation from.

Type:string
restart_freq

The frequency for creating restart files.

Type:integer
first_step

True if the first step has not been executed yet.

Type:boolean
system

This is the system the simulation will act on.

Type:object like System
simulation_output

This list defines the output tasks associated with the simulation.

Type:list of dicts
simulation_type

An identifier for the simulation.

Type:string
tasks

This is the list of simulation tasks to execute.

Type:list of objects like SimulationTask
__init__(settings, controls)[source]

Initialise the simulation object.

Parameters:

  • controls (dict of parameters to set up and control the simulations.) –

    It contains:

    • steps: int, optional The number of simulation steps to perform.
    • startcycle: int, optional The cycle we start the simulation on, useful for restarts.
    • endcycle: int, optional The cycle we end the simulation to, useful in restarts.
    • rgen: object like RandomGenerator The random generator that will be used for the paths that required random numbers.

  • settings (dict) – Contains all the simulation settings.
__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 py:attr:.tasks. 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 an object of type SimulationTask with some additional settings on how to store the output and when to execute the task. The keywords in the dict defining the task are:
    • func: Callable, this is a function to execute in the task.
    • args: List, with arguments for the function.
    • kwargs: Dict, with the keyword arguments for the function.
    • when: Dict, which defines when the task should be executed.
    • first: Boolean, determines if the task should be executed on the initial step, i.e. before the full simulation starts.
    • result: String, used to label the result.
  • position (int, optional) – Can be used to give the tasks a specific position in the task list.
create_output_tasks(settings, progress=False)[source]

Create output tasks for the simulation.

This method will generate output tasks based on the tasks listed in simulation_output.

Parameters:
  • settings (dict) – These are the simulation settings.
  • progress (boolean) – For some simulations, the user may select to display a progress bar, we then need to disable the screen output.
execute_tasks()[source]

Execute all the tasks in sequential order.

Returns:results (dict) – The results from the different tasks (if any).
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 (None) – Returns None but modifies self.cycle.
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 on the value of self.cycle[‘startcycle’].

Returns:out (boolean) – True if the simulation is finished, False otherwise.
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.
restart_info()[source]

Return information which can be used to restart the simulation.

Returns:info (dict,) – Contains all the updated simulation settings and counters.
run()[source]

Run a simulation.

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

Note

This function will just run the tasks via executing step() In general, this is probably too generic for the simulation you want, if you are creating a custom simulation. Please consider customizing the run() (or the step()) method of your simulation class.

Yields:out (dict) – This dictionary contains the results from the simulation.
set_up_output(settings, progress=False)[source]

Set up output from the simulation.

This includes the predefined output tasks, but also output related to the restart file(s).

Parameters:
  • settings (dict) – These are the simulation settings.
  • progress (boolean) – For some simulations, the user may select to display a progress bar, we then need to disable the screen output.
simulation_output = []
simulation_type = 'generic'
soft_exit()[source]

Force simulation to stop at the current step.

step()[source]

Execute a simulation step.

Here, the tasks in tasks will be executed sequentially.

Returns:out (dict) – This dictionary contains the results of the defined tasks.

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 and the behavior is defined by the tasks in tasks.

write_restart(now=False)[source]

Create a restart file.

Parameters:now (boolean, optional) – If True, the output file will be written irrespective of the step number.

pyretis.simulation.simulation_task module

Definition of a class for simulation tasks.

Important classes defined here

SimulationTask (SimulationTask)
A class representing a simulation task.
SimulationTaskList (SimulationTaskList)
A class for representing a list of simulation tasks. This class defines functionality for adding tasks from a dictionary description.
class pyretis.simulation.simulation_task.SimulationTask(function, args=None, kwargs=None, when=None, result=None, first=False)[source]

Bases: Task

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. It can simply just alter the state of the passed argument(s).

function

The function to execute.

Type:function
when

Determines when the task should be executed.

Type:dict
args

List of arguments to the function.

Type:list
kwargs

The keyword arguments to the function.

Type:dict
first

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

Type:boolean
result

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

Type:string
__call__(step)[source]

Execute the task.

Parameters:

step (dict of ints) – The keys are:

  • ‘step’: the current cycle number.
  • ‘startcycle’: the cycle number at the start.
  • ‘stepno’: the number of cycles we have performed so far.
Returns:

out (unknown type) – The result of self.execute(step).
__init__(function, args=None, kwargs=None, when=None, result=None, first=False)[source]

Initialise the task.

Parameters:
  • function (callable) – The function to execute.
  • args (list, optional) – List of arguments to the function.
  • kwargs (dict, optional) – The keyword arguments to the function.
  • when (dict, optional) – Determines if the task should be executed.
  • result (string, optional) – This is a label for the result created by the task.
  • first (boolean, optional) – True if this task should be executed before the first step of the simulation.
__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.
  • ‘startcycle’: the cycle number at the start.
  • ‘stepno’: the number of cycles we have performed so far.
Returns:

out (unknown type) – The result of running self.function.
property result

Return the result label.

run_first()[source]

Return True if task should be executed before first step.

task_dict()[source]

Return a dict representing the task.

pyretis.simulation.simulation_task._check_args(function, given_args=None, given_kwargs=None)[source]

Check consistency for function and the given (keyword) arguments.

Here we assume that the arguments are given in a list and that the keyword arguments are given as a dictionary. The function inspect.getargspec is used to check the input function.

Parameters:
  • function (callable) – The function we will inspect.
  • given_args (list, optional) – A list of the arguments to pass to the function. ‘self’ will not be considered here since it passed implicitly.
  • given_kwargs (dict, optional) – A dictionary with keyword arguments.
Returns:

out (boolean) – False if there is some inconsistencies, i.e. when the calling of the given function will probably fail. True otherwise.