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.
SimulationTIS (SimulationTIS): A class for running a TIS simulation for a single ensemble.
SimulationPPTIS (SimulationPPTIS): A class for running a PPTIS simulation for a single ensemble.
SimulationRETIS (SimulationRETIS): A class for running a RETIS simulation for a set of ensembles.
SimulationPPRETIS (SimulationPPRETIS): A class for running a REPPTIS simulation for a set of ensembles.

pyretis.simulation.async_runner module¶

asyncio-based task runner for the infinite-swapping scheduler.

The runner drives the worker pool that executes the per-cycle run_md calls produced by pyretis.simulation.scheduler.

exception pyretis.simulation.async_runner.RunnerError¶

Bases: Exception

Exception class for the runner.

class pyretis.simulation.async_runner._ShutdownNoiseFilter(name='')¶

Bases: Filter

Drop the expected BrokenProcessPool teardown noise.

When the worker pool is force-released on an interrupt / SIGTERM (a tutorial smoke run killed by its timeout, an HPC walltime kill, a user Ctrl-C), an in-flight run_in_executor future can finish with a concurrent.futures.BrokenExecutor after its wrapper task was already cancelled. asyncio then reports it – usually during interpreter shutdown – as “Future exception was never retrieved” at ERROR level with a full traceback. That is expected teardown noise, not a real failure (a genuine pool failure mid-run is retrieved onto the work future via future.set_exception and never reaches this “never retrieved” path), so it is dropped. Everything else passes through untouched.

filter(record: LogRecord) → bool¶: Return False only for the unretrieved-BrokenExecutor record.

pyretis.simulation.async_runner._install_shutdown_noise_filter() → None¶

Attach _ShutdownNoiseFilter to the asyncio logger once.

asyncio’s default exception handler logs through the asyncio logger, so the filter is installed there (a logger-level filter drops the record before it propagates to the root handlers). Idempotent: a second runner does not stack a duplicate filter.

class pyretis.simulation.async_runner.aiorunner(config: dict, n_workers: int = 1)¶

Bases: object

A light asynchronuous runner based on asyncio.

The runner manage an asyncio.queue with a pool of workers. Upon instanciation, a dedicated event loop is launched in a separate thread. The user can then attach a worker function to the runner and start multiple instances of that function in the background. As work is submitted to the runner, it is picked up by workers on-the-fly.

__init__(config: dict, n_workers: int = 1) → None¶

Init function of runner.

Parameters:

config (dict) – The simulation configuration dictionary. It is forwarded unchanged to every worker process via the pool initializer (worker_initializer()) and must therefore be picklable (the pool uses the spawn start method). When config contains a "simulation" section the initializer builds that worker’s engine pool and order parameters from it (via pyretis.engines.factory.create_engines() and create_orderparameters()) and installs the engines as process-local state with set_worker_engines(); the engines are intentionally not part of the per-task work units, so they never cross the process boundary.
n_workers (int) – Number of worker processes in the pool.

async _add_work_to_queue(work_unit: dict[str, Any]) → Future¶

Async function adding work to queue, returns a future.

Parameters:: work_unit (dict) – a unit of work encapsulated in a dict
Returns:: concurrent.futures.Future – A future wih the results of the work

async _cancel_pending_tasks() → None¶: Cancel the worker-wrapper tasks and await their completion.

_discard_pending_future(future: Future) → None¶: Forget a completed or cancelled caller-visible future.

async _drain_and_stop_tasks() → None¶: Drain submitted work and stop every queue consumer.

_start_event_loop() → None¶: Start the event loop in a separate thread.

async _start_tasks() → None¶: Launch the background tasks.

async _task_wrapper(queue: Queue, executor: Executor) → None¶

Wrap the sync task.

To enable running the sync task_f from a dynamic list of tasks.

Parameters:

queue (asyncio.Queue) – an asyncio queue to get work from
executor (concurrent.futures.Executor) – an executor

close() → None¶

Force-release runner resources without draining the queue.

Safe to call from an error/interrupt path (unlike stop(), which waits for the work queue to empty): it cancels the pending worker tasks, stops the event loop and shuts the pool down so it is never orphaned.

n_workers() → int¶: Return runner number of workers.

set_task(task_f: Callable) → None¶

Attach the task function to the runner.

Parameters:: task_f (callable) – a callable function

start() → None¶: Launch background tasks.

stop() → None¶: Terminate the runner and release the worker pool.

submit_work(work_unit: dict[str, Any]) → Future¶

Submit work to the runner.

Parameters:: task – a unit of work encapsulated in a dict
Returns:: concurrent.futures.Future – A future wih the results of the work

class pyretis.simulation.async_runner.future_list¶

Bases: object

A managed list of futures, returned in the order they finish.

Each future added gets a done callback that queues it as finished, in the thread that completes it. The runner sets the result of each future from its event-loop thread, one at a time, so the queue holds the futures in the order the runner saw them finish. as_completed() returns the future at the head of that queue: of the futures that finished while the caller was busy, the one that finished first.

__init__() → None¶: Initialize future list.

_record_finished(future: Future) → None¶

Queue a finished future and wake a caller that waits for it.

Parameters:: future (concurrent.futures.Future) – The future that finished.

add(future: Future) → None¶

Add a future to list.

A future that is already done is queued as finished at once.

Parameters:: future (concurrent.futures.Future) – The future to add.

as_completed(on_wait: Callable[[], None] | None = None, poll_interval: float = 0.25) → Future | None¶

Get the future that finished first, optionally reporting.

Without on_wait, the call blocks until a future has finished. A path can take minutes, which would leave the command-line progress bar frozen for the whole propagation. When on_wait is supplied, the call waits in short, non-busy polling intervals and invokes the callback between them. The scheduler uses that callback to refresh the worker/ensemble/trajectory-leg display.

Parameters:

on_wait (callable, optional) – Called after each polling interval in which no future finished.
poll_interval (float, optional) – Seconds between callback invocations.

Returns:

concurrent.futures.Future, optional – The future of the list that finished first, or None when the list is empty.

pyretis.simulation.async_runner.get_worker_engines() → dict[str, Any]¶: Return the engine pool created for the current worker process.

pyretis.simulation.async_runner.prepare_streaming_engines(engines, config)¶

Give the internal integrators their file-backed streaming setup.

The coordinator hands every engine file-backed phase points (a snapshot System whose config points at a trajectory file). The external engines read that file directly; the internal integrators (langevin / velocityverlet / verlet / randomwalk) integrate from in-memory particles instead, so they need a streaming template – their own box / particles / masses / force field – built from the carried-through [system] / [box] / [particles] / [potential] / [forcefield] sections. This mirrors how TurtleMDEngine builds its own box / particles / potential in __init__. Engines without a setup_streaming method (the external engines) are skipped.

Parameters:

engines (dict of lists) – The per-worker engine pool, keyed by engine name.
config (dict) – The coordinator configuration dictionary.

pyretis.simulation.async_runner.set_worker_engines(engines: dict[str, Any]) → None¶: Install the engine pool for the current worker process.

pyretis.simulation.async_runner.worker_initializer(counter, config, process_sessions=None, external_shutdown=None)¶: Initialize function for each worker process.

pyretis.simulation.biretis module¶

The infinite-swapping state of a bidirectional RETIS (biretis) run.

BiretisState runs the layout of pyretis.core.biretis with the scheduler of pyretis.simulation.repex.InfSwapState. It differs from it in the layout (two minus ensembles, two ladders and the shared ensembles), in the weight of a path in each ensemble, in the zero swaps (one per state) and in the occupancy of the paths.

The occupancy is the infinite-swapping one. A path that starts in A can hold an ensemble of the A ladder or a shared ensemble, and a path that starts in B one of the B ladder or a shared ensemble. Every assignment of the paths to the ensembles gives the shared ensembles to the two families in the same numbers, so the permanent of the weight matrix is a sum, over the shared ensembles the A family takes, of the product of the permanents of the two families. Each of these is the permanent of a 0/1 matrix whose rows have nested supports, a product.

class pyretis.simulation.biretis.BiretisState(config)¶

Bases: InfSwapState

The infinite-swapping state of a biretis run.

Variables:: windows (list of dict) – The ensembles of the run in slot order (pyretis.core.biretis.biretis_windows()).

__init__(config)¶

Set up the state of a biretis run from its configuration.

Parameters:: config (dict) – The scheduler configuration of the run.

_build_ensembles()¶: Build the ensemble dicts of the biretis layout.

_engine_slot(ens_num)¶: Return the entry of ensemble_engines of an ensemble.

_ens_key(ens_num)¶: Return the slot of an ensemble number.

_log_name(ens_num)¶: Return the name the log gives an ensemble: its directory.

static _occupancy_sums(support, rows_a, rows_b, columns)¶

Return the permanent sums of the occupancy of the free paths.

The free A paths fill the free A ensembles and take of the free shared ensembles, the B paths the rest. For each choice of those take shared ensembles, the permanent of the weights is the product of the permanents of the A block and the B block, and the sum for a path and an ensemble is the number of assignments that give the path that ensemble.

Parameters:

support (numpy.ndarray of bool) – The nonzero weights, one row per slot.
rows_a, rows_b (list of integers) – The rows of the free paths of state A and of state B.
columns (dict of lists of integers) – The free ensembles of the A ladder ("A"), of the B ladder ("B") and the free shared ensembles ("S").

Returns:

sums (numpy.ndarray of int objects) – sums[row, col] is the number of assignments of the free paths that give the path of row the ensemble col.
total (int) – The number of assignments, the permanent of the weights.

Raises:

ValueError – If the free paths of the two states cannot fill the free ensembles, or no assignment is valid.

_split_free_rows(support, free)¶

Sort the free paths into minus paths and paths of A and of B.

Parameters:

support (numpy.ndarray of bool) – The nonzero weights, one row per slot.
free (list of integers) – The free slots.

Returns:

minus_rows (dict of integers) – For the row of each free minus path, the column of its [0^-].
rows_a, rows_b (list of integers) – The rows of the free paths of state A and of state B.

add_traj(ens, traj, valid, count=True, n=0)¶

Put a path in an ensemble and update the occupancy.

Parameters:

ens (integer) – The ensemble number.
traj (object like pyretis.core.path.Path) – The path.
valid (tuple of floats) – The weights of the path: (1.0,) for a minus path, else pyretis.core.biretis.biretis_weights().
count (boolean, optional) – Unused; kept for the signature of the base class.
n (integer, optional) – Unused; kept for the signature of the base class.

Raises:

ValueError – If the weights are not one for a minus path, or one per ensemble after the minus ones and the trailing 0 for another path, or if the path is not valid in the ensemble.

compute_swap_matrix(input_mat, locks)¶

Return the infinite-swap occupancy of the free paths.

A free path of a [0^-] holds it. The other free paths are those of state A and those of state B; the shared ensembles the free A paths do not fill hold B paths, and the occupancy is the sum over the ways to split them (_occupancy_sums()).

Parameters:

input_mat (numpy.ndarray) – The (path, ensemble) weight matrix, one row per slot.
locks (numpy.ndarray) – One entry per slot, 1 for a locked ensemble.

Returns:

out (numpy.ndarray) – out[i, j] is the probability that ensemble j holds the path of row i; locked rows and columns are zero.

load_paths(paths)¶

Load the first paths of the run, one per ensemble in slot order.

Parameters:: paths (list of objects like pyretis.core.path.Path) – The paths, paths[slot] for the ensemble of that slot.

pick()¶

Pick an ensemble and a path, or a zero swap with its partner.

With probability zeroswap a pick of a [0^-] or a [0^+] becomes the zero swap of the two ensembles of its state when the partner is free.

Returns:: picked (dict) – The picked ensembles, keyed by ensemble number, each with the path it starts from.

sort_trajstate()¶: Give each free ensemble a free path that is valid in it.

pyretis.simulation.biretis.check_biretis_engines(engines, windows)¶

Check that each ensemble of a biretis run runs with [engine].

Parameters:

engines (list of lists of strings) – The ensemble_engines of the scheduler configuration, one list of engine sections per ensemble in slot order.
windows (list of dict) – The ensembles of the run (pyretis.core.biretis.biretis_windows()).

Raises:

ValueError – If the list does not give ["engine"] to each ensemble.

pyretis.simulation.biretis.nested_permanent(mask)¶

Return the permanent of a 0/1 matrix whose row supports are nested.

For rows whose supports form a chain under inclusion, sorted by the size c_i of the support (smallest first), the permanent is the product of c_i - i.

Parameters:: mask (numpy.ndarray of bool) – The square matrix of the nonzero entries.
Returns:: out (int) – The permanent.
Raises:: ValueError – If the supports of the rows are not nested.

pyretis.simulation.biretis.refuse_biretis_settings(config)¶

Refuse the settings a biretis run does not support.

Parameters:: config (dict) – The scheduler configuration of the run.
Raises:: ValueError – For the keys of pyretis.core.biretis.biretis_refused_keys() but the ones with one entry per interface: the configuration holds a move and a list of engines for each ensemble of every run (check_biretis_engines()).

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 an umbrella simulation.

class pyretis.simulation.mc_simulation.UmbrellaWindowSimulation(ensemble, settings, controls=None)¶

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.

Variables:

system (object like System) – The system to act on.
rgen (object like RandomGenerator) – Object to use for random number generation.
umbrella (list, [float, float]) – The umbrella window to consider.
overlap (float) – The position we have to cross before the simulation ends.
maxdx (float) – Defines the maximum movement allowed in the Monte Carlo displacement move.

__init__(ensemble, settings, controls=None)¶

Initialise the umbrella window simulation.

Parameters:

ensemble (dict) – It contains the simulation info:
- system : object like System The system to act on.
- rgen : object 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:
- steps : int, optional The MINIMUM number of cycles to perform (the mincycle setting). 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.is_finished.
- startcycle : int, optional The current simulation cycle, i.e. where we start.

__str__()¶: Return some info about the simulation as a string.

is_finished()¶

Check if the simulation is done.

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

Returns:: out (boolean) – True if the simulation is finished, False otherwise.

load_restart_info(info)¶: Load the restart information.

restart_info()¶

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 plain 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)¶

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)¶

Initialise the MD simulation object.

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.
- rgen : object like RandomGenerator, optional The random generator of the task, which seeds the runs of an engine that draws a seed per run (draws_run_seeds).
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__()¶: Return a string with info about the simulation.

load_restart_info(info)¶

Load restart information.

When the engine seeds its runs from the random generator of the task, the generator continues from the state the restart file stores (restart_info()), and the engine draws the seeds of its next runs from it.

Parameters:: info (dict) – The dictionary with the restart information, should be similar to the dict produced by restart_info().
Raises:: ValueError – If the engine seeds its runs from the random generator of the task and the restart file stores no state of it: the restarted runs would repeat the seeds of the first runs.

restart_info()¶

Return information which can be used to restart the simulation.

The state of the random generator of the task, when the engine seeds its runs from it, is info['simulation']['rgen'], so that a restart continues its stream of seeds.

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

run()¶

Run the MD simulation.

Yields:: results (dict) – The results from a single step in the simulation.

simulation_output = [{'name': 'md-energy-file', 'type': 'energy'}, {'name': 'md-thermo-file', 'type': 'thermo-file'}, {'name': 'md-traj-file', 'type': 'traj-xyz'}, {'name': 'md-thermo-screen', 'type': 'thermo-screen'}, {'name': 'md-order-file', 'type': 'order'}]¶

simulation_type = 'md'¶

class pyretis.simulation.md_simulation.SimulationMDFlux(ensemble, settings=None, controls=None)¶

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)¶

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__()¶: Return a string with info about the simulation.

load_restart_info(info)¶: Load the restart information.

restart_info()¶

Return information which can be used to restart the simulation.

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

run()¶

Run the MD simulation.

Yields:: results (dict) – The results from a single step in the simulation.

simulation_output = [{'name': 'flux-energy-file', 'type': 'energy'}, {'name': 'flux-traj-file', 'type': 'traj-xyz'}, {'name': 'flux-thermo-screen', 'type': 'thermo-screen'}, {'name': 'flux-order-file', 'type': 'order'}, {'name': 'flux-cross-file', 'type': 'cross'}]¶

simulation_type = 'md-flux'¶

class pyretis.simulation.md_simulation.SimulationNVE(ensemble, settings=None, controls=None)¶

Bases: SimulationMD

A MD NVE simulation class.

This class is used to define a NVE simulation. Compared with the SimulationMD, the engine is expected to have NVE dynamics, and a warning is logged when its dynamics is not NVE.

__init__(ensemble, settings=None, controls=None)¶

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__()¶: Return a string with info about the simulation.

load_restart_info(info)¶: Load the restart information.

restart_info()¶

Return information which can be used to restart the simulation.

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

simulation_output = [{'name': 'nve-energy-file', 'type': 'energy'}, {'name': 'nve-thermo-file', 'type': 'thermo-file'}, {'name': 'nve-traj-file', 'type': 'traj-xyz'}, {'name': 'nve-thermo-screen', 'type': 'thermo-screen'}, {'name': 'nve-order-file', 'type': 'order'}]¶

simulation_type = 'md-nve'¶

step()¶: 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 (SimulationTIS): 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)¶

Bases: Simulation

A base class for TIS/RETIS simulations.

Variables:

ensembles (list of dictionaries of objects) –
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.
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:
- sigma_v: The velocity width. Negative values select aimless shooting; zero or positive values select soft velocity perturbations.
- seed: A integer seed for the random generator used for the path ensemble we are simulating here.
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.
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.

__init__(ensembles, settings, controls)¶

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)¶

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)¶

Initialise the path simulation.

Parameters:: settings (dictionary) – The simulation settings.

load_restart_info(info)¶

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()¶

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()¶

Run a path simulation.

Raises:: RuntimeError – A path simulation cannot be run in process: the scheduler drives the cycles. Run it with pyretis run, or step it yourself by iterating pyretis.simulation.scheduler.scheduler_cycles().

simulation_output = []¶

simulation_type = 'generic-path'¶

step()¶

Perform a TIS/RETIS/PPRETIS simulation step.

Raises:: RuntimeError – A path simulation cannot be stepped in process: the scheduler drives the cycles. Run the simulation with pyretis run, or step it yourself by iterating pyretis.simulation.scheduler.scheduler_cycles().

write_restart(now=False)¶

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)¶

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__()¶: Just a small function to return some info about the simulation.

name = 'RETIS simulation'¶

required_settings = ('retis',)¶

simulation_output = [{'name': 'path_ensemble-retis-screen', 'result': ('pathensemble-{}',), 'type': 'pathensemble-retis-screen'}]¶

simulation_type = 'retis'¶

class pyretis.simulation.path_simulation.SimulationTIS(ensembles, settings, controls)¶

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__()¶: Just a small function to return some info about the simulation.

name = 'TIS simulation'¶

required_settings = ('tis',)¶

simulation_output = [{'name': 'path_ensemble-screen', 'result': ('pathensemble-{}',), 'type': 'pathensemble-screen'}]¶

simulation_type = 'tis'¶

pyretis.simulation.repex module¶

Replica-exchange (REPEX) coordinator.

Runs the infinite-swap parallel REPEX bookkeeping for the scheduler in pyretis.simulation.scheduler.

pyretis.simulation.repex.EXACT_PERM_ONLY_KEY = '[tis] exact_perm_only'¶: The input keys that decide whether a probability block beyond the exact permanent threshold is refused, as a message names them.

class pyretis.simulation.repex.InfSwapState(config, minus=False)¶

Bases: object

Define the infinite-swapping replica-exchange (REPEX) state object.

__init__(config, minus=False)¶: Initiate the swap state given the config dict from a TOML file.

_apply_freq_moves(picked)¶

Draw the per-cycle frequency move for a single pick.

For a single-ensemble (non-swap) pick the configured shooting move is replaced, with the [tis] weights, by a time reversal (tr, weight freq), a mirror (mr, weight mirror_freq) or a target swap (ts, weight target_freq); otherwise the configured move is kept (weight max(1 - freq - mirror_freq - target_freq, 0)). Mirror and target swap are allowed only in the [0^-] ensemble, which is scheduler pick key -1.

The draw is taken from the ensemble’s per-cycle rgen, the same generator the move itself consumes, before the move draws from it; the result overrides mc_move on the (locked, hence worker-private for this cycle) ensemble dict. The draw lists the moves in the order tr, mirror, target swap, configured move.

Parameters:: picked (dict) – The per-ensemble pick dict from pick() / pick_lock().

_attach_shooting_selectors(selector)¶

Attach the shared shooting-point selector to every ensemble.

selector is built once in _build_ensembles() when any ensemble uses the biased shooting move. It is stateless and shared, so attaching it to every ensemble is harmless: only pyretis.core.moves.shoot_bias() reads the shooting_selector key, and it is inert for the other moves. Attaching it to every ensemble covers every branch of the ensemble construction.

_build_ensembles()¶: Build the ensemble dicts of the run’s layout from the config.

_count_submitted(ens_nums)¶

Count a submitted move in each of its ensembles.

Parameters:: ens_nums (sequence of integers) – The ensembles of the move, numbered as pick() returns them (a zero swap has two).

_energy_engine(section)¶

Return an engine of a section that computes energies of frames.

A streaming internal integrator recomputes the energies of every stored frame (streaming_energies, set up with the force field and the masses by its setup_streaming); it is built once for each section and kept. Another engine with frame_energies (OpenMM, OpenMMEngine.frame_energies()) computes the energies of the stored frames it is given; it is built anew for each call, and the caller drops it when the energies of the path are set, so the coordinator holds no OpenMM context between two paths. Returns None for an engine that does neither (e.g. an external engine that reports energy through its own files), in which case the energy.txt output keeps the engine’s in-memory terms (nan when absent).

Parameters:: section (string) – The engine section, as [simulation] ensemble_engines names it.
Returns:: out (object like EngineBase or None) – The engine, or None.

_engine_slot(ens_num)¶

Return the entry of ensemble_engines of an ensemble.

The lists of [simulation] ensemble_engines hold one entry per interface, the [0^-] first, so ensemble ens_num takes entry ens_num + 1.

_ens_key(ens_num)¶

Map a logical ensemble number to its ensembles dict key.

Multi-ensemble runs key the [0^-] ensemble (logical ens_num -1) at 0, so key = ens_num + 1. A no-minus run (single-ensemble TIS, explore, or PPTIS without zero_left/flux) has no [0^-]: ensemble ens_num is keyed at ens_num.

_ensemble_engine_section(pn)¶

Return the engine section of the ensemble a path belongs to.

The ensemble is the one whose output the path is stored in (ens_save_idx of traj_data); its engine section is the first one [simulation] ensemble_engines names for it, or, for a configuration without that list, the section the default list gives it (default_ensemble_engines()).

Parameters:: pn (int) – The path number; traj_data holds its entry.
Returns:: out (string) – The name of the engine section.

_log_name(ens_num)¶

Return the name the log gives an ensemble number.

The [0^-] (ensemble -1) is 000 and ensemble ens_num is 00 followed by ens_num + 1.

_move_counts()¶

Return the moves submitted to each ensemble slot so far.

The counts are those recorded in the state file. A restart of a run that recorded none starts from the attempted moves in each ensemble’s moves.txt, and a new run starts from zero. The phantom cap slot of the routes with a [0^-] ensemble holds zero.

Returns:: out (numpy.ndarray of integers) – One count per slot (length n), updated in place as moves are submitted.

_move_rng(spawn_key)¶

Rebuild the generator a move was submitted with.

The generator is the one _spawn_move_rng() spawned for the move: its seed sequence has the entropy and the pool size of root_seed_sequence, and spawn_key.

Parameters:: spawn_key (list of int) – The spawn key _spawn_move_rng() returned for the move.
Returns:: child_rng (np.random.Generator) – The generator of the move.
Raises:: ValueError – If spawn_key is not the key of a child the root seed sequence has already spawned: a later fresh pick would then spawn the same child.

_moves_in_flight_at_write()¶

Return the moves in flight at the write a resume starts from.

Returns:: locked0 (list of tuple) – One (ensembles, path numbers, spawn key) per entry of [current] locked, in the recorded order. The spawn key is the entry of [current] locked_spawn_keys at the same position, and None when the write recorded no keys.
Raises:: ValueError – If [current] locked_spawn_keys does not hold one key per move in flight.

_pick_probabilities()¶

Return the flattened, normalised (traj, ens) pick distribution.

The distribution is _pick_weights() divided by its sum. It is separate from pick(), so the weighting can be tested without the pick and lock machinery.

Returns:: out (numpy.ndarray of float) – The probability of each (traj, ens) pair, traj * n + ens.
Raises:: RuntimeError – If the weights sum to zero, so that no ensemble can be picked (can_pick()).

_pick_weights()¶

Return the flattened (traj, ens) pick weights, not normalised.

The base weights are the infinite-swap probability matrix (prob), optionally reweighted per ensemble column by the pick_scheme exponent and by the fixed relative_shoots frequencies, or by the priority_shooting weights. A locked ensemble has a zero column, so the weights sum to zero when no free ensemble can be picked.

Returns:: out (numpy.ndarray of float) – The weight of each (traj, ens) pair, traj * n + ens.

_priority_weights()¶

Return the ensemble weights of priority shooting.

A live ensemble that has received n moves, while the most-sampled live ensemble has received n_max, has weight n_max - n + 1, so level ensembles are equally likely. The phantom cap slot has weight zero. The weights depend on the moves submitted so far and not on the current paths.

Returns:: out (numpy.ndarray of float) – One weight per slot (length n).

_scratch_dir(ens_num)¶

Return the per-ensemble generate/ scratch dir for a move.

The scratch lives under the PICKED ensemble’s output directory (<data_dir>/NNN/generate) – the same generate/ the kick initiation runs in – so a run keeps every transient file under its ensemble. The picked logical ens_num (-1 for the [0^-] minus ensemble) maps to its output number through the same seam the per-ensemble output and the nested archive use (pyretis.inout.archive_paths.output_ensemble_number()), so all three agree on the directory name.

Parameters:: ens_num (int) – The picked (primary, first-locked) logical ensemble number.
Returns:: str – The absolute generate/ scratch directory for this move.

_spawn_move_rng()¶

Spawn the generator of a new move from the root generator.

The generator is built on the next child of root_seed_sequence, the seed sequence of the root generator, with the generator and bit-generator types of the root generator: it is the generator spawn_rng() spawns from the root generator.

Returns:

spawn_key (list of int) – The spawn key of the child seed sequence, which _move_rng() rebuilds the generator from.
child_rng (np.random.Generator) – The generator of the move.

_stored_frame_energies(pn, path)¶

Compute the energies of the stored frames of a path.

The engine is the one of the ensemble the path belongs to (_ensemble_engine_section(), _energy_engine()). A streaming internal integrator recomputes the energies of every frame, which this method returns. An engine with frame_energies sets the energies of the phase points that carry none (_fill_missing_energies()); it is built only for a path with such a phase point, and dropped when they are set.

Parameters:

pn (int) – The path number; traj_data holds its entry.
path (object like pyretis.core.path.Path) – The path, whose phase points name their stored frames.

Returns:

out (list of tuple or None) – One (vpot, ekin) pair per phase point, recomputed by a streaming internal integrator; None otherwise.

add_traj(ens, traj, valid, count=True, n=0)¶: Add traj to state and calculate P matrix.

archive_rejected_trial(rej_traj, ens_num, ens_save_idx, status)¶

Store a rejected trial the user asked to keep.

The trial is written to <ensemble>/rejected/ alongside the operational accepted/ and long-term archive/ stores.

It is named by the cycle, ensemble and status rather than given a path number: numbering happens only on acceptance, so taking a number here would collide with a live path and shift the sequence that appears in the output. The name is also what a user searches for – “the BWI rejection in ensemble 3 at cycle 1200”.

Parameters:

rej_traj (object like Path or None) – The rejected trial. None when the move recorded no trial to keep, in which case nothing is written.
ens_num (int) – The ensemble whose move was rejected.
ens_save_idx (int) – The birth-ensemble slot the rejected store nests under, as resolved by the caller.
status (str) – The rejection status, e.g. "BWI".

can_pick()¶

Return whether a move can be picked for a worker now.

A move holds its ensembles locked until it finishes, and a pick draws from the free ensembles with a positive pick weight (_pick_weights()). A zero swap or an ∞REPPTIS swap holds two ensembles, so the moves in flight can hold every ensemble before each worker has a move; the worker then waits for a move to finish (wait_for_move()). During the initiation of a resume, the moves in flight at the write the resume starts from are submitted first (pick_lock()); no other move holds their ensembles.

Returns:: out (boolean) – True when prep_md_items() can pick a move.

property cap¶: Retrieve the interface cap from config dict.

capture_pathensemble_row(pn, path, status)¶

Store the pathensemble.txt column data for a path.

The data is read back by pyretis.inout.pathensemble_output to format the per-ensemble pathensemble.txt rows. Stored at path-creation time because the live Path object (with its phase points, generated move tag and status) is not retained in traj_data.

Parameters:

pn (int) – The path number.
path (object like pyretis.core.path.Path) – The accepted path.
status (str) – The path status (e.g. "ACC").

cleanup_worker_dirs()¶

Remove the transient per-ensemble generate/ scratch dirs.

The NNN/generate/ directories hold only trial output; accepted trajectories are already moved out to the per-ensemble archive and nothing reads a scratch directory back, so removing them at the end of a graceful run leaves only the per-ensemble output store. Called after the scheduler stops cleanly (not on a crash, so failing scratch stays for debugging).

Both the scheduler-used scratch dirs (self._worker_dirs) and every ensemble’s generate/ are removed – the kick initiation (set_up_output) also creates a generate/ under each ensemble and an ensemble that was only ever a swap secondary (or unused) would otherwise leave an empty one behind.

compute_swap_matrix(input_mat, locks)¶

Return the infinite-swap probability matrix of the free paths.

Element [i, j] is the probability that ensemble j holds the path of row i. In infinite swapping it follows from the permanents of the weight matrix of the free paths and free ensembles; with the one-hot occupancy of ∞REPPTIS and of the runs without swaps it is the identity of the free ensembles. A locked ensemble and the path its move holds are left out: their column and row are zero. With every ensemble locked no free path is left, and the matrix is zero.

Parameters:

input_mat (numpy.ndarray) – The (path, ensemble) weight matrix, one row per slot.
locks (numpy.ndarray) – One entry per ensemble slot, 1 for a locked ensemble and 0 for a free one.

Returns:

out (numpy.ndarray) – The probability matrix, of the shape of input_mat.

configured_moves: dict¶

count_trials(md_items)¶

Count this cycle’s attempted moves, per ensemble.

Keeps the sampler’s own tally of what it tried and what it accepted, which print_acceptance() reports at the end of the run.

Parameters:: md_items (dict) – The cycle’s move data.

property cstep¶: Retrieve cstep from config dict.

cworker = None¶

property data_dir¶: Retrieve data_dir from config dict.

engine_occ: dict¶

ensembles: dict¶

fast_glynn_perm(M)¶: Glynn permanent.

find_blocks(arr, offset)¶: Find blocks in a W matrix.

initiate()¶: Initiate loop.

initiate_ensembles()¶

Create all the ensemble dicts from the TOML config dict.

configured_moves then holds the move each ensemble is built with, keyed like ensembles. _apply_freq_moves() sets mc_move of a picked ensemble to the move it draws, and takes the configured move from configured_moves.

property interfaces¶: Retrieve interfaces from config dict.

last_frac_increment: dict¶

live_paths()¶: Return list of live paths.

load_paths(paths)¶: Load paths.

lock(ens)¶: Lock ensemble.

locked_paths()¶: Return list of locked paths.

loop()¶: Check and iterate loop.

property mc_moves¶: Retrieve mc moves list from config dict.

property no_minus¶

True for the no-[0^-] topologies.

Single-ensemble TIS, explore, and PPTIS-without-zero_left all drop the [0^-] minus ensemble (and its +1 ensemble-key offset and trailing phantom cap slot); the standard RETIS / ∞REPPTIS routes keep them. It is a property, so it follows the flags when a test or tool sets them after construction.

pathensemble_nacc: dict¶

pathensemble_nshoot: dict¶

pathensemble_rows: dict¶

permanent_prob(arr)¶: P matrix calculation for specific W matrix.

pick()¶

Pick path and ens.

Raises:: RuntimeError – If no ensemble can be picked (can_pick()).

pick_lock()¶

Pick path and ens, starting with the moves a resume resubmits.

A resume first submits the moves that were in flight at the write it starts from (locked0) again, in the order that write recorded them. Each of them is recorded in locked as pick() records a fresh pick, so a write made while it is in flight records it and a resume from that write submits it again. A move whose spawn key the write recorded runs on the generator of that key (_move_rng()), the one it held when it was first submitted; a move recorded without one spawns the next child of the root generator (_spawn_move_rng()), which no move of the run has held (see set_rgen()). With locked0 empty, this is pick().

Returns:: picked (dict) – The picked ensembles, keyed by ensemble number, each with the path it starts from, as pick() returns them.

pick_traj_ens(ens)¶: Pick traj ens.

prep_md_items(md_items)¶: Fill md_items with picked path and ens.

print_acceptance()¶

Log the acceptance ratio of every move, per ensemble.

Counted from the trials the sampler attempted (count_trials()); an ensemble or a move that was never drawn is not listed.

print_end()¶: Print end.

print_pick(ens_nums, pat_nums, pin)¶: Print pick.

print_shooted(md_items, pn_news)¶: Print shooted.

print_start()¶: Print start.

print_state()¶: Print state.

printing()¶: Check if print.

property prob¶: Calculate the P matrix.

progress_tasks: dict¶

prune_pathensemble_rows()¶

Drop captured pathensemble rows the ensembles have released.

Only live paths receive frac increments (see treat_output), so a path that has left every ensemble can never contribute another per-ensemble output row. Its captured order/energy series would otherwise accumulate without bound over a long run.

quick_prob(arr)¶: Quick P matrix calculation for specific W matrix.

random_prob(arr, n=10000)¶: P matrix calculation for specific W matrix.

property screen¶: Retrieve screen print frequency from config dict.

set_rgen()¶

Rebuild the root random generator of a resumed run.

A run builds its root generator as default_rng of SeedSequence(seed), kept as root_seed_sequence (see __init__()). Every move runs on a child of that seed sequence (_spawn_move_rng()), and the child it gets is set by the seed and by the number of children spawned before it. The recorded bit-generator state ([current] rng_state) holds neither, so the seed sequence is built from the configured seed with the recorded number of children already spawned ([current] rng_children_spawned), and the recorded state is then set on its bit generator. Every fresh pick of the resume therefore spawns a child that no move of the run has held, whatever order the moves completed in.

A write that records no count holds no spawn keys either, and the seed sequence starts from cstep plus the number of moves in flight ([current] locked). Each pick of the run that wrote the state spawned one child of its root seed sequence, and each move it picked is either completed, and counted in cstep, or in flight, so that number is the number of children its root seed sequence had spawned. The fresh picks of the resume spawn the children that run would have spawned next, so with no move in flight the resume draws the streams of that run. A move in flight spawns the next child as well, not the one it held, which the write does not record: it runs on a stream that no move of the run has held (no move since the last resume, in a run resumed before), and the resume continues the chain but does not reproduce the run it resumes, which a warning says.

sort_trajstate()¶: Sort trajs and calculate P matrix.

swap(traj, ens)¶: Swap to keep the locks symmetric.

traj_data: dict¶

treat_output(md_items)¶: Treat output.

trial_stats: dict¶

property tsteps¶: Retrieve total steps from config dict.

unlock(ens)¶: Unlock ensemble.

wait_for_move(md_items)¶

Leave a worker without a move until a move finishes.

A worker of the initiation takes its pin here, as prep_md_items() gives it to a worker with a move, and keeps it for the move the scheduler submits for it once can_pick() is true again.

Parameters:: md_items (dict) – The move items of the worker.
Returns:: md_items (dict) – The move items of the worker, with its pin.

property workers¶: Retrieve workers from config dict.

write_toml()¶

Write the settings of the run and its state to ./output.toml.

output.toml is the single run file: it holds the canonical sections of the run (run_record) together with the running [current] state (cstep, RNG, frac, active paths). A configuration read from a file of the scheduler configuration, with no canonical sections, is written as it is, with its [current]. The scheduler writes the file once at start-up and then once per cycle; a resume reads the same file (see pyretis.simulation.setup.setup_config()).

The shared pyretis.inout.common.atomic_write() helper flushes the new payload, durably retains output.toml.prev, atomically replaces the target, and flushes the parent directory entry.

pyretis.simulation.repex.MIDDLE_CROSSING_ROLES = ('zero-plus', 'body')¶

Which ROLES carry the published middle-crossing requirement.

body is the definition itself: a body ensemble holds LML/LMR/RML /RMR partial paths, every one of which contains its middle interface.

zero-plus carries the requirement for a different reason, and the reason is worth stating because its geometry makes the requirement look vacuous. [0^+] has its middle ON its left interface, so the crossing test there reads ordermin < lambda_0 <= ordermax, which every path returning below lambda_0 satisfies. What it excludes is the path that does not: one that both starts and ends on the right. Where [0^+] carries the ["L", "R"] start condition it is past the 0-L rejection and past the crossing test that applies to single-sided windows, and this requirement is the one rejection an R–R path there still meets. Where it carries "R" those two apply as well, and this requirement is the one that does not depend on which side the path started.

pyretis.simulation.repex.MOVES_SUBMITTED_KEY = 'moves_submitted'¶: The [current] key of the state file that holds, per ensemble slot, the moves submitted so far when priority_shooting is on.

pyretis.simulation.repex._ensemble_role(slot, has_minus, has_zero_plus)¶

Return the role of the ensemble in a slot of the layout.

The middle-crossing requirement follows from an ensemble’s role, not from its slot number. Which windows a layout includes varies: a PPTIS route may omit the minus window, the [0^+] window, or both, so the same slot number holds a different kind of ensemble from one route to the next, and slot 0 can be a body ensemble. The role is recorded here, at construction, where the layout is known, and every consumer reads it.

Which windows are present is two independent facts, so they are two parameters.

Parameters:

slot (integer) – The ensemble’s index in the constructed list.
has_minus (boolean) – Whether the layout includes the minus/permeability window. When it does, that window is slot 0.
has_zero_plus (boolean) – Whether the layout includes the [0^+] window. When it does, that window is the first positive slot.

Returns:

out (string) – "minus", "zero-plus" or "body".

pyretis.simulation.repex._fill_missing_energies(engine, path)¶

Set the energies of the frames of a path that carry none.

The potential and the kinetic energy of each phase point whose vpot or ekin is None are computed by the engine from the stored frame the phase point names (OpenMMEngine.frame_energies()), and only the missing terms are set. A phase point with both terms is not read.

Parameters:

engine (object like OpenMMEngine) – The engine; its frame_energies returns one (vpot, ekin) pair per phase point it is given.
path (object like pyretis.core.path.Path) – The path, whose phase points name their stored frames by config.

pyretis.simulation.repex._normalise_relative_shoots(relative_shoots, n_slots, n_live)¶

Validate and normalise the relative_shoots weight vector.

relative_shoots sets fixed per-ensemble move-selection frequencies in interface slot order ([0^-] first when a minus ensemble exists). InfSwapState.pick() makes the ensemble marginal of its (traj, ens) probability matrix proportional to these weights (_reweight_ensembles()), so a heavier ensemble is picked (and hence shot in) more often. The weights are state-independent, so every ensemble samples its own stationary distribution; they set only how the moves are allocated.

Parameters:

relative_shoots (sequence of float or None) – One non-negative weight per live ensemble; None leaves the pick distribution untouched.
n_slots (integer) – The coordinator’s total slot count (InfSwapState.n). Routes with a [0^-] minus ensemble carry a trailing phantom cap slot (always locked) beyond the live ensembles; it is padded here with zero weight.
n_live (integer) – The number of live ensembles (config["current"]["size"]: [0^-] plus the positive ensembles, or just the positives on the no-minus routes).

Returns:

numpy.ndarray of float or None – The normalised weight vector of length n_slots, or None when the knob is unset.

pyretis.simulation.repex._reweight_ensembles(prob, weights)¶

Give the (traj, ens) pick distribution a chosen ensemble marginal.

The joint pick is factorised as P(traj, ens) = w_ens * P(traj | ens): each ensemble column is normalised before the weight product, which keeps the infinite-swap trajectory conditional untouched and makes the ensemble marginal proportional to weights over the unlocked ensembles. Locked or empty columns (sum zero) divide to NaN and are set to zero.

Parameters:

prob (numpy.ndarray) – The (traj, ens) probability matrix.
weights (numpy.ndarray) – One non-negative weight per ensemble slot.

Returns:

out (numpy.ndarray) – The reweighted matrix, not normalised.

pyretis.simulation.scheduler module¶

Main infinite-swapping scheduler loop.

pyretis.simulation.scheduler._complete_progress_task(state, md_items)¶: Replace a running task with a compact last-completed summary.

pyretis.simulation.scheduler._last_leg_progress(filename)¶: Return (leg, length) from one engine propagation message file.

pyretis.simulation.scheduler._last_step_in_tail(filename, tail_bytes=8192)¶

Return the last propagation step index recorded in a message file.

Only the end of the file is examined. GROMACS and CP2K append one line per propagation step, so a long trajectory produces a message file that grows without bound, and the progress bar refreshes several times a second. The step index lives on the last non-comment line, so reading a fixed-size tail answers the question in constant time.

Parameters:

filename (str) – The engine message file to inspect.
tail_bytes (int, optional) – How many bytes at the end of the file to examine.

Returns:

int or None – The last step index, or None if the tail holds no step line.

pyretis.simulation.scheduler._register_progress_task(state, md_items)¶: Record enough metadata to report a submitted worker’s progress.

pyretis.simulation.scheduler._submit_move(state, runner, futures, md_items)¶

Pick the next move for a worker and submit it to the runner.

Parameters:

state (object like InfSwapState) – The scheduler state, which picks the ensembles and paths.
runner (object like aiorunner) – The runner the move is submitted to.
futures (object like future_list) – The futures of the moves in flight; the move’s future is added.
md_items (dict) – The move items of the worker.

pyretis.simulation.scheduler.make_progress_bar(state, progress)¶

Build the sampling-cycle progress bar for a scheduler run.

The bar is restart-aware by construction: it starts at the state’s current cycle (cstep – the restored cycle on a resumed run, 0 on a fresh one) out of the total step target, so a restarted run shows the cycle it resumed from.

Parameters:

state (object like InfSwapState) – The scheduler state (read for cstep / tsteps).
progress (boolean) – If True, build the bar; otherwise return None.

Returns:

out (object like tqdm.tqdm or None) – The progress bar, or None when not requested.

pyretis.simulation.scheduler.scheduler(config, progress=False)¶

Run the infinite-swapping scheduler loop to completion.

Parameters:

config (dict) – The scheduler configuration dictionary.
progress (boolean, optional) – If True, display a progress bar over the sampling cycles (restart-aware: a resumed run starts at its restored cycle).

pyretis.simulation.scheduler.scheduler_cycles(config, progress_callback: Callable[[object], None] | None = None)¶

Run the scheduler, handing control back after every cycle.

This is the scheduler as a generator. It drives exactly the same loop scheduler() does – same setup, same moves, same output – but yields to the caller after each sampling cycle, so a script can look at (or draw) the simulation while it runs. That is the supported way to step a path simulation from your own code: PathSimulation.step() raises an error that points here.

The state is yielded once directly after initiation – before any cycle has run, so a caller can render the initial paths – and then once per completed cycle.

Stopping early is safe: abandoning the generator (or closing it) releases the worker pool, exactly as an interrupted run does.

Parameters:

config (dict) – The scheduler configuration dictionary.
progress_callback (callable, optional) – Called periodically with the live state while a worker trajectory is running. It is used by the CLI progress display and does not alter the generator’s one-yield-per-completed-cycle contract.

Yields:

state (object like InfSwapState) – The live scheduler state, after initiation and then after each completed cycle. state.cstep is the cycle just finished.

pyretis.simulation.scheduler.worker_progress_text(state)¶: Format the most recently advancing worker for the progress bar.

pyretis.simulation.setup module¶

Setup for the infinite-swapping scheduler.

Reads the TOML config, builds the replica-exchange (REPEX) state, and hands the worker pool to pyretis.simulation.async_runner.aiorunner.

pyretis.simulation.setup.ENSEMBLE_SUBDIRS = ('generate', 'archive', 'rejected', 'engine_logs')¶: The directories a run writes in each of its ensemble directories beside the store of the paths, <ensemble>/<load_dir>: the scratch directory of the moves, generate, which is removed at the end of a run (pyretis.simulation.repex.InfSwapState. cleanup_worker_dirs()); the long-term store, which receives the paths moved out of the store (pyretis.inout.archive_paths. LONG_TERM_DIR); the store of the rejected trials a run keeps (pyretis.inout.archive_paths.REJECTED_DIR); and the store of the engine logs (pyretis.engines._engine_logs. ENGINE_LOG_DIR).

exception pyretis.simulation.setup.TOMLConfigError¶

Bases: Exception

Raised when there is an error in the .toml configuration.

pyretis.simulation.setup._build_bootstrap_system(config: dict, run_dir: str) → System¶

Build the shared starting point as a file-backed snapshot.

Every kick job runs inside a scheduler worker, whose engines have already had setup_streaming/process-local construction applied (pyretis.simulation.async_runner.worker_initializer(), prepare_streaming_engines). The starting system of every kick job is a snapshot (has_particles=False) that names the frame of the bootstrap file, not the in-memory pyretis.setup.createsimulation.prepare_system() output: an external engine kicks from that file. OpenMM and the internal integrators read the snapshot into a phase point with particles in the worker and kick it in memory (pyretis.initiation.initiate_kick.run_parallel_kick_job()): an internal integrator in the box of its streaming template (pyretis.engines.internal.MDEngine.system_with_particles()), and OpenMM in the periodic box of the OpenMM simulation, which the box line of zeros gives it (pyretis.engines.openmm.OpenMMEngine.frame_cell()), the box of the system written here. An external engine (GROMACS, LAMMPS, CP2K) holds its starting configuration in a file of its own format, the conf of its input_path, and TurtleMD in the xyz file the setup of its system writes, without a box line, so it integrates in the box of its input (_reads_own_configuration()): the snapshot names that file and holds the box of the system the settings give, as the system of the sequential kick does, and no bootstrap file is written. The engine updates the size of that box from the frames it reads, so the phase points keep the periodicity the input states.

This resolves the full particle/box/forcefield setup once via prepare_system (handling every particle-input convention: inline pos, [particles.position] input_file, per-engine construction), then writes that resolved state out as a one-frame bootstrap trajectory file and returns a fresh snapshot System pointing at it – the same pattern pyretis.inout.config_adapter._write_inf_path_files() already uses to serialise an accepted in-memory path into the coordinator’s on-disk, file-backed format.

Parameters:

config (dict) – The translated scheduler config.
run_dir (str) – The absolute directory the simulation runs from; the bootstrap file is written there.

Returns:

System – A snapshot system (has_particles False) with .config pointing at the written bootstrap file, or at the configuration file of an external engine or of TurtleMD together with the box of the system the settings give.

pyretis.simulation.setup._build_ensemble_windows(config: dict) → InfSwapState¶

Build an InfSwapState with its ensemble windows initiated.

Shared by setup_internal() (the steady-state scheduler state) and run_kick_phase() (a throwaway state used only to read off .ensembles/.rgen/.repptis for the parallel kick phase). The two calls build INDEPENDENT InfSwapState instances – there is no shared mutable RNG state between the kick phase and the steady-state scheduler that follows it. The kick phase must give valid initial paths; it need not be byte-reproducible against the steady-state run’s own RNG stream.

Parameters:: config (dict) – The configuration dictionary.
Returns:: InfSwapState – A REPEX state with .ensembles already built (via initiate_ensembles); no paths are loaded.

pyretis.simulation.setup._build_fresh_current(config: dict) → dict¶

Build a fresh [current] state (cstep 0) for a new run.

The ensemble count depends on the route: a single-ensemble TIS run is ONE [i^+] ensemble (its three interfaces are the [left, middle, right] bounds), an EXPLORE run has N-1 independent positive ensembles, and a PPTIS-without-zero_left run has no [0^-]; every other route keeps the one-ensemble-per-interface layout.

Parameters:: config (dict) – The configuration dictionary.
Returns:: dict – The fresh [current] sub-dict.

pyretis.simulation.setup._build_kick_items(state: InfSwapState, system0, config: dict, run_dir: str) → list¶

Build one kick job dict per ensemble window.

Parameters:

state (InfSwapState) – A state with .ensembles/.rgen/.repptis already set (from _build_ensemble_windows()).
system0 – The shared starting System; a fresh copy is taken per ensemble.
config (dict) – The translated scheduler config.
run_dir (str) – The absolute directory the simulation runs from.

Returns:

list of dict – One kick job per ensemble, see pyretis.initiation.initiate_kick.run_parallel_kick_job() for the dict’s keys.

pyretis.simulation.setup._build_order_engine(config: dict)¶

Return an engine able to re-evaluate a stored frame.

Used by pyretis.core.path_load.align_order_width() to read the frames of the loaded paths back. Mirrors InfSwapState._energy_engine(): the internal integrators need setup_streaming before they can materialise a frame (it builds the particle/box template the stored coordinates are poured into); external engines read their own trajectory files and need no such preparation.

Parameters:: config (dict) – The translated scheduler config.
Returns:: object like EngineBase – An engine ready to evaluate order parameters on file-backed phase points.

pyretis.simulation.setup._check_resumed_draws(inp: str, config: dict, state: dict, section: str = '[simulation.tis_set]') → None¶

Stop a resume whose shooting draws differ from those of its state.

A state file without pyretis.core.velocity_draws.VELOCITY_RULE_KEY records the draws of pyretis.core.velocity_draws.unmarked_draws(), and a resume draws as its tis_set selects (pyretis.core.velocity_draws.recorded_draws()). For a state file that carries the key, both runs draw as its tis_set selects. [simulation] allow_setting_change skips the comparison.

Parameters:

inp (str) – The state file, named in the diagnostics.
config (dict) – Its configuration.
state (dict) – Its [current] section.
section (str, optional) – The section of the state file that holds the draw settings, named in the diagnostics: [tis] in a run file with the canonical sections of a run, [simulation.tis_set] in a file of the scheduler configuration.

Raises:

ValueError – If the resume draws the shooting velocities from another distribution than the run that wrote the state (pyretis.core.velocity_draws.refuse_changed_draws()).

pyretis.simulation.setup._check_resumed_subcycles(inp: str, config: dict, state: dict) → None¶

Stop a resume whose internal integrators stream otherwise.

A state file without pyretis.core.provenance.SUBCYCLES_RULE_KEY was written by a run whose internal integrators all streamed with [engine] subcycles, and a resume streams each with the subcycles of its own engine section (_unmarked_stream_changes()). The resume is refused when a built-in internal integrator of a section other than [engine] would stream with other subcycles than that run. A module engine for which the two differ is reported as UNKNOWN in a warning, because its class is known once the run imports it. [simulation] allow_setting_change skips the comparison.

Parameters:

inp (str) – The state file, named in the diagnostics.
config (dict) – Its configuration.
state (dict) – Its [current] section.

Raises:

ValueError – If a built-in internal integrator of the resume streams with other subcycles than the run that wrote the state, or if the state records another rule (pyretis.core.provenance.has_subcycles_rule()).

pyretis.simulation.setup._dispatch_kick_items(config: dict, kick_items: list) → list¶

Run every kick job through a short-lived worker pool.

Parameters:

config (dict) – The translated scheduler config (forwarded to the pool’s worker initializer, see pyretis.simulation.async_runner.aiorunner).
kick_items (list of dict) – One kick job per ensemble, from _build_kick_items().

Returns:

list of dict – One run_parallel_kick_job result per kick item.

pyretis.simulation.setup._evaluates_lammps_orders(engine, order_function) → bool¶

Return True if PyRETIS evaluates the orders of LAMMPS frames.

Parameters:

engine (object like EngineBase) – The engine that reads the frames of the run back (_build_order_engine()).
order_function (object like OrderParameter or None) – The configured order parameter.

Returns:

out (boolean) – True if engine is a LAMMPS engine with order_mode = "pyretis" and an order parameter is configured.

pyretis.simulation.setup._input_key(scheduler_path: str) → str¶

Return the input key a message names for a scheduler path.

Parameters:: scheduler_path (str) – The dotted path of the scheduler configuration, e.g. "simulation.tis_set.lambda_minus_one".
Returns:: str – The first input key the key table reads the path from (pyretis.inout.key_table.input_keys()), e.g. "[simulation] zero_left".

pyretis.simulation.setup._log_engine_warnings(found: list) → None¶

Log the path-sampling warnings of the engines of a run.

Parameters:: found (list of tuples) – (section, warnings) for each engine section built (refuse_path_sampling_engines()).

pyretis.simulation.setup._may_refuse_path_sampling(config: dict, section: str) → bool¶

Tell whether the engine of a section may refuse or warn.

Parameters:

config (dict) – The scheduler configuration.
section (str) – The engine section, "engine", "engine1", …

Returns:

bool – False when the section resolves to a class whose path_sampling_problem and path_sampling_warnings are those of pyretis.engines.engine.EngineBase (which accept every engine without a warning) or that has neither; True otherwise, also when the class cannot be resolved without building the engine.

pyretis.simulation.setup._outside_of(directories: list[str], parents: list[str]) → list[str]¶

Return the directories that lie in none of the given parents.

Parameters:

directories (list of str) – The absolute directories to select from.
parents (list of str) – The absolute directories whose contents are left out.

Returns:

out (list of str) – The entries of directories below none of parents, in their order.

pyretis.simulation.setup._read_run_config(inp: str) → tuple[dict, dict | None]¶

Return the scheduler configuration of a run file, and its record.

A run file with the canonical sections of a run (see pyretis.inout.run_record.is_run_record()) is read by pyretis.inout.run_record.load_run(): the settings parse of its sections, translated by the key table, with its [current] state, and its temperatures are resolved before any engine runs (_resolve_record_temperature()). The engine sections of a run file with a state are checked for an integrator a path-sampling run cannot use before load_run reads the [particles.velocity] temperature the state of an earlier run records (pyretis.engines.run_temperature.refuse_path_sampling_inputs(), leave_out_earlier_velocity_temperature()). An input of the legacy-runner schema (see pyretis.inout.run_record.is_legacy_runner_input()) has its engine sections checked for an integrator a path-sampling run cannot use first (pyretis.engines.run_temperature.refuse_path_sampling_inputs()), before the conversion reads the temperature of a TurtleMD or ASE engine section; it is then read in its canonical form, converted and checked by pyretis.inout.run_record.load_legacy_run(), and the temperatures of the canonical form are resolved (_resolve_converted_temperature()). Every other file is a state file of the scheduler configuration itself, written by an earlier PyRETIS, and is the configuration as it is; when it holds a [current] state, the run it records is resumed: its engine sections are checked for an integrator a path-sampling run cannot use (pyretis.engines.run_temperature.refuse_path_sampling_inputs()), the [particles.velocity] temperature the state of a run without the temperature_rule mark records is left out or refused as in a run file (leave_out_earlier_velocity_temperature()), and its temperatures are resolved as those of a run file (pyretis.engines.run_temperature.resolve_resumed_temperature()), in the directory of the file.

Parameters:

inp (str) – The run file.

Returns:

out[0] (dict) – The scheduler configuration, with the [current] state of the file when it holds one.
out[1] (dict or None) – The canonical sections of the file, or of the canonical form of a legacy-runner input; None for a state file of the scheduler configuration.

pyretis.simulation.setup._reads_own_configuration(particles) → bool¶

Return whether an engine reads its system from a file of its own.

The particles of an external engine (ParticlesExt) name the configuration file of its input. The particles of a TurtleMD system are in-memory Particles with a bolted-on config, which names the file TurtleMD reads its system from (pyretis.setup.createsystem._write_turtlemd_configuration()): the file holds the system of the input and no box line, and TurtleMD integrates in the box of its input. The particles of the internal integrators and of OpenMM name no file.

Parameters:: particles (object like Particles) – The particles of the system the run’s settings give.
Returns:: out (boolean) – True when particles.config names the file the engine reads the system from.

pyretis.simulation.setup._recorded_run_sections(config: dict) → list¶

Return the engine sections a state file of the scheduler runs.

Parameters:: config (dict) – A state file of the scheduler configuration, as it is read.
Returns:: list of strings – The sections of run_engine_sections(), with the engine sections of each ensemble that apply_config_defaults() gives a configuration without [simulation] ensemble_engines, that name an engine class (pyretis.engines.run_temperature.engine_sections()).

pyretis.simulation.setup._refuse_lammps_restart_paths(config: dict, paths: list) → None¶

Refuse the loaded paths of a LAMMPS run held in restart files.

Parameters:

config (dict) – The scheduler config.
paths (list of objects like Path) – The paths pyretis.core.path_load.load_paths_from_disk() loaded, each with its path_number.

Raises:

ValueError – For a run with a LAMMPS engine, if a phase point of a path is held in a LAMMPS restart file (refuse_lammps_restart_phasepoints()).

pyretis.simulation.setup._refuse_missing_active_paths(inp: str, config: dict, state: dict) → None¶

Refuse a resume whose active paths have no traj.txt.

A resume reads each active path from its directory in the store of its birth ensemble, <ensemble>/<load_dir>/<path number>, and from the flat <load_dir>/<path number> when only that directory exists (a load directory the user staged, or the store of a run of an earlier PyRETIS) (pyretis.inout.archive_paths.resolve_path_dir()). The store is named by the [simulation] load_dir of the run that wrote it.

Parameters:

inp (str) – The state file the resume reads.
config (dict) – The configuration of the resume.
state (dict) – The [current] section of the state file.

Raises:

FileNotFoundError – If the traj.txt of an active path is missing. The message names every missing file and the load_dir of the resume.

pyretis.simulation.setup._resolve_converted_temperature(settings: dict, current: None) → None¶

Resolve the temperatures of the canonical form of a legacy input.

An engine input whose integrator a path-sampling run cannot use is refused first, before a temperature of the input is read (pyretis.engines.run_temperature.refuse_path_sampling_inputs()).

Parameters:

settings (dict) – The canonical settings of a legacy-runner input; changed in place (pyretis.engines.run_temperature.resolve_run_temperature()).
current (None) – The state of the input, which has none.

pyretis.simulation.setup._resolve_record_temperature(inp: str, settings: dict, current: dict | None) → None¶

Resolve the temperatures of a run file before any engine runs.

An engine input whose integrator a path-sampling run cannot use is refused first, before a temperature of the input is read (pyretis.engines.run_temperature.refuse_path_sampling_inputs()). A run file without [current] starts a run: the record a new run writes after its set-up has resolved the temperatures of its engines, or a canonical input the scheduler reads itself. Its temperatures are resolved as those of a new run (pyretis.engines.run_temperature.resolve_run_temperature()). A run file with a state is resumed, and the temperatures it records are compared with the sources of its engines (pyretis.engines.run_temperature.resolve_resumed_temperature()).

Parameters:

inp (str) – The run file, as the messages name it.
settings (dict) – The parsed settings of the run file; changed in place.
current (dict or None) – The [current] state of the run file.

pyretis.simulation.setup._run_kick_task(kick_item: dict) → dict¶

Worker-side entry point for one ensemble’s parallel kick job.

Mirrors _run_md_task(): runs in the worker process and injects that worker’s process-local engine pool into pyretis.initiation.initiate_kick.run_parallel_kick_job().

pyretis.simulation.setup._run_md_task(md_items: dict) → dict¶

Worker-side entry point for the runner.

Runs in the worker process and injects that worker’s process-local engine pool into pyretis.core.moves.run_md(), so the runner stays engine-agnostic and run_md takes its engines explicitly.

pyretis.simulation.setup._runs_lammps(config: dict) → bool¶

Return True when an engine section of a run is a LAMMPS engine.

Parameters:: config (dict) – The scheduler config, whose engine sections run_engine_sections() lists.
Returns:: out (boolean) – True if the class of one of these sections is a LAMMPS engine of pyretis.engines.ENGINE_MAP (lammps, lammps2, lammps_steps).

pyretis.simulation.setup._staged_load_source(config: dict, base: str, flat: bool) → str¶

Return the sentence naming where the load of a new run reads from.

Parameters:

config (dict) – The scheduler config of the load.
base (str) – The absolute run directory.
flat (boolean) – True for a load of the flat store (see pyretis.inout.staged_paths.reads_flat_store()).

Returns:

out (str) – The sentence that opens the message of refuse_before_staged_load().

pyretis.simulation.setup._start_fresh(config: dict) → None¶

Give a scheduler configuration without state the state of step 0.

A new run records the acceptance rule it samples with, and takes the canonical default (high acceptance) when the configuration does not set it. A resumed configuration keeps the rule it recorded; one that records none is read as HIGH_ACCEPT_DEFAULT.

Parameters:: config (dict) – The scheduler configuration, without [current]; changed in place.

pyretis.simulation.setup._unmarked_stream_changes(config: dict) → tuple[int, list, list]¶

Return the engines that stream otherwise than a run without the rule.

A run whose state lacks pyretis.core.provenance.SUBCYCLES_RULE_KEY streamed every internal integrator with [engine] subcycles, 1 when [engine] leaves it out. A resume streams each internal integrator with the subcycles of the engine section it is built from, 1 when the section leaves it out (pyretis.engines.internal.MDEngine.setup_streaming()), and every other engine takes subcycles through its constructor, in both runs. The engine sections compared are those other than [engine] that an ensemble runs with: [simulation] ensemble_engines, or default_ensemble_engines() for a configuration without it.

Parameters:

config (dict) – The scheduler configuration of the state file.

Returns:

out[0] (int) – The [engine] subcycles the internal integrators of the run streamed with.
out[1] (list of tuples) – (section, subcycles) for each section whose class is a built-in internal integrator (pyretis.engines.factory.is_internal_integrator()) and whose own subcycles differs from out[0].
out[2] (list of tuples) – (section, subcycles) for each section whose class is not in the engine map, a module engine, and whose subcycles (None when the section leaves it out) is not out[0]: the engine streamed with out[0] if it is an internal integrator.

pyretis.simulation.setup._warn_unrecorded_load_orders(config: dict, paths: list, order_function) → None¶

Warn when a restart holds initial paths of an unrecorded load.

A load that evaluates the order values of its initial paths writes them into their order.txt and lists the paths in [current] load_recomputed. A state without that key does not record whether its load evaluated them, so its still-live initial paths are restored from their stored order.txt. Those values can differ from the ones the simulation sampled the paths with: in the decimals order.txt holds, or entirely when that load changed the coordinate.

Parameters:

config (dict) – The translated scheduler config of the restart.
paths (list of objects like Path) – The live paths read from disk, carrying the generated move [current] generated records for them.
order_function (object like OrderParameter or None) – The configured order parameter; None when the engine produces the order values, which a load keeps as they stand.

pyretis.simulation.setup._write_kick_results(config: dict, run_dir: str, results: list) → str¶

Serialise every kick result into its per-ensemble archive.

Reuses the same on-disk contract pyretis.inout.config_adapter.generate_load_dir() already writes (and pyretis.core.path_load.load_paths_from_disk() already reads), via the existing pyretis.inout.config_adapter._write_external_path_files() / pyretis.inout.config_adapter._write_inf_path_files() writers. Each initial path i (born in ensemble slot i) is seeded into its per-ensemble archive <ensemble>/<load_dir>/<i> – the same nested location the fresh [current] map records and the scheduler’s load_paths_from_disk reads back, so no trajectory has to move.

Parameters:

config (dict) – The translated scheduler config.
run_dir (str) – The absolute directory the simulation runs from.
results (list of dict) – One run_parallel_kick_job result per ensemble, from _dispatch_kick_items().

Returns:

str – The run directory (the per-ensemble archives live under it; there is no single top-level load path).

pyretis.simulation.setup._write_load_orders(config: dict, state: InfSwapState, paths: list, recomputed: bool) → list[int]¶

Keep the initial paths of a load in the run, with their values.

Each initial path is held in its archive directory, <ensemble>/<load_dir>/<pn> of its birth ensemble, where a restart reads it. A path read from a directory the user staged flat is copied there, and its phase points then name the frames of the copy (see copy_staged_paths()); the order values the load evaluated are written there when it evaluated them.

Parameters:

config (dict) – The translated scheduler config of the load.
state (object like InfSwapState) – The state the paths are loaded into. It holds the birth ensemble of each path, which names the path’s archive directory (see InfSwapState.load_paths()).
paths (list of objects like Path) – The paths the load read from disk and accepted.
recomputed (bool) – The return value of align_order_width() for the load: True when it replaced the order values of paths with the values evaluated from their frames.

Returns:

list of int – The sorted path numbers whose order.txt holds the evaluated values (see write_path_orders()) when recomputed is True, and an empty list otherwise: the stored values are then the ones the run samples with.

pyretis.simulation.setup.apply_config_defaults(config: dict) → dict¶

Fill in the resolved configuration defaults in place.

Sets the per-ensemble engine list (default_ensemble_engines() when the configuration names no pool, with the quantis engine of the [0^-]) and the [simulation] / [simulation.tis_set] / [output] defaults, and validates the engine sections and the output-deletion settings. The function does NOT touch [current] (the running state), so it is safe to call both before a [current] exists (when dumping a fresh output.toml) and from setup_config() after it has been built. Every assignment is a setdefault/idempotent guard, so a repeated call is a no-op.

Every route of a path-sampling run calls this function before any engine runs: pyretis.bin.pyretisrun.run_pyretis_path_sampling() before the initiation of the initial paths, and setup_config() for every input the scheduler reads, the state file of the scheduler configuration of an earlier PyRETIS among them. The engine sections of the run (run_engine_sections()) are therefore checked here for one time per step (pyretis.core.engine_time.one_time_per_step_problem()).

Parameters:: config (dict) – The configuration dictionary, mutated in place.
Returns:: dict – The same config dictionary, with defaults applied.
Raises:: TOMLConfigError – If two engine sections of the run have different times per step, timestep * subcycles, with a message that names each engine section and its time per step; or if an output setting is not valid.

pyretis.simulation.setup.check_config(config: dict) → None¶

Perform some checks on the settings from the .toml file.

Parameters:: config (dict) – The configuration dictionary.

pyretis.simulation.setup.default_ensemble_engines(config: dict) → list¶

Return the engine sections of each ensemble of a run without a pool.

A configuration without [simulation] ensemble_engines runs every ensemble with [engine], and the [0^-] ensemble of a quantis run ([tis] quantis) with [engine0].

Parameters:: config (dict) – A scheduler configuration.
Returns:: list of lists of strings – One list of engine sections per interface; for a biretis run, one per ensemble, in slot order.

pyretis.simulation.setup.fresh_scheduler_config(config: dict) → dict¶

Prepare a scheduler configuration for a new run, as setup_config does.

setup_config() reads a file of the scheduler configuration without [current] this way: it refuses a [simulation] load_dir that names no directory of its own, gives the configuration the state of step 0 (_start_fresh()), applies the configuration defaults (apply_config_defaults()) and checks it (check_config()). The check of the conversion of a legacy-runner input (pyretis.tools.convert_legacy_schema.convert_legacy_document()) prepares the input, as the scheduler read it, and the configuration the key table builds from its canonical form this way, and compares the two.

Parameters:: config (dict) – A scheduler configuration without [current]; changed in place.
Returns:: dict – The same config, prepared.
Raises:: TOMLConfigError – If the configuration is refused by refuse_reserved_load_dir(), apply_config_defaults() or check_config().

pyretis.simulation.setup.live_ensemble_count(config: dict) → int¶

Return the number of live path ensembles of a scheduler run.

Full RETIS has one live ensemble per interface ([0^-], [0^+], [1^+], …); explore and the PPTIS variants without a minus ensemble have fewer. The size of [current] holds the number, written by _build_fresh_current() from these route rules; a configuration without it gets the number from _build_fresh_current().

Parameters:: config (dict) – The scheduler configuration.
Returns:: out (int) – The number of live path ensembles.

pyretis.simulation.setup.parallel_kick_sections(config: dict) → list¶

Return the engine sections the parallel kick runs.

The job of each live ensemble kicks with the first engine section of the ensemble’s list of [simulation] ensemble_engines (_build_kick_items()); the live ensembles are numbered from 0, as live_ensemble_count() counts them.

Parameters:: config (dict) – The scheduler configuration, with ensemble_engines (apply_config_defaults()).
Returns:: list of strings – Each section once, in the order of the ensembles.

pyretis.simulation.setup.refuse_before_initiation(config: dict, run_dir: str) → None¶

Refuse to initiate a run beside files it would read as its own.

pyretis run generates the initial paths of a path-sampling run from [initial-path] and writes them into the per-ensemble store, <ensemble>/<load_dir>/<pn>. It refuses a run directory holding:

a directory staged flat for an initial path, <load_dir>/<pn>: the load of the new run reads its paths from the flat store when a path is staged there (see pyretis.inout.staged_paths.reads_flat_store()), in place of the paths the run generates;
the archive directory of an initial path, <ensemble>/<load_dir>/<pn> of its birth ensemble: the initiation writes the files of each path it generates into that directory, and the load reads the path from the files there, so a file an earlier run left in it would be read with the new path.

Parameters:

config (dict) – The translated scheduler config.
run_dir (str) – The directory the simulation runs from.

Raises:

FileExistsError – If the run directory holds any of these. The message names every directory to remove.

pyretis.simulation.setup.refuse_before_staged_load(config: dict, run_dir: str) → None¶

Refuse to start the load of a new run beside an earlier run’s files.

The load of a new run (see pyretis.inout.staged_paths.reads_staged_paths()) reads its initial paths from the flat store, <load_dir>/<pn>, when at least one active path is staged there, and keeps a copy of each in its archive directory, <ensemble>/<load_dir>/<pn>, where a restart reads it. With no active path staged flat, it reads the paths pyretis run generated, the interface optimizer seeded or a user placed in those archive directories (see pyretis.inout.staged_paths.reads_flat_store()). The load refuses when the run directory holds:

the ensemble output of an earlier run, a pathensemble.txt in an ensemble directory of the run, with data rows or with the header alone (see pyretis.inout.pathensemble_output. ensemble_output_files()). The scheduler writes the file once the load of a run has read its initial paths, so an earlier run has loaded its paths in the run directory, and the new run would read what that run left in the per-ensemble store and write the output afresh. A file with a data row records a simulation that has sampled cycles, which a restart continues;
for a load of the flat store, an archive directory of an active path (see pyretis.inout.staged_paths.left_copies()): it holds files an earlier run wrote, which a restart of the new run would read;
for a load of the flat store, a staged directory missing for an active path (see pyretis.inout.staged_paths.missing_staged_dirs()).

The check runs before the load reads or writes anything. A run of a legacy-runner input makes it before it writes the run file of its canonical form as well (see pyretis.bin.pyretisrun. run_legacy_runner_config()).

Parameters:

config (dict) – The scheduler config of the load.
run_dir (str) – The directory the simulation runs from.

Raises:

FileExistsError – If the run directory holds ensemble output or an archive directory of an active path. The message names every directory to remove, and every staged directory missing for an active path.
FileNotFoundError – If staged directories are missing for active paths and the run directory holds none of the directories above. The message names the missing directories.

pyretis.simulation.setup.refuse_path_sampling_engines(config: dict, log_warnings: bool = True) → list¶

Refuse, in this process, the engines a path-sampling run cannot use.

The engine sections of the run (run_engine_sections(): [engine] and each section [simulation] ensemble_engines names) are checked before the run writes or runs anything. A section whose class gives a reason to refuse an engine, or warnings, of its own (pyretis.engines.engine.EngineBase.path_sampling_problem(), pyretis.engines.engine.EngineBase.path_sampling_warnings()) is built once with pyretis.engines.factory.create_inf_engine(), which refuses an engine whose integrator a path-sampling run cannot use, with a message that starts with the section, [engine1]. A section of another class is accepted without being built. A section whose class cannot be resolved without building it (engine_section_class()) is built.

When every section is accepted, the warnings of each engine built (pyretis.engines.engine.path_sampling_warnings_of()) are logged once, after its section (pyretis.engines.engine.log_path_sampling_warnings()).

Every route of a path-sampling run calls this function before it writes a file of the run (refuse_run_engines()), and run_kick_phase() before its jobs start.

Parameters:

config (dict) – The scheduler configuration, with ensemble_engines (apply_config_defaults()).
log_warnings (bool, optional) – False when the caller logs the warnings itself, or has logged them on the same configuration.

Returns:

list of tuples – (section, warnings) for each section built, in the order of run_engine_sections().

Raises:

ValueError – If an engine integrates with an integrator a path-sampling run cannot use.

pyretis.simulation.setup.refuse_reserved_load_dir(config: dict) → None¶

Refuse a [simulation] load_dir that names no directory of its own.

load_dir names the store of the paths in each ensemble directory, <ensemble>/<load_dir>/<path number>, and the flat store the initial paths of a fresh run may be staged in, <load_dir>/<path number> of the run directory. The store needs a directory of its own, inside the ensemble directory. An absolute load_dir is refused: every ensemble would share its store, and the store would lie outside the run directory. The name is normalised with os.path.normpath() (./load and load/ are load), and its first component names the directory the store is created in. That component is refused when it is

..: the store would lie outside the ensemble directory, and the flat store outside the run directory;
.: the store would be the ensemble directory itself, and the flat store the run directory itself;
one of ENSEMBLE_SUBDIRS: a directory the run writes other files in, in each ensemble directory;
the name of an ensemble directory (see pyretis.inout.archive_paths.is_ensemble_dir_name()), which holds the output of that ensemble: the flat store in the run directory and the ensemble directories, in the run directory or in [output] data_dir, are told apart by their names.

Parameters:: config (dict) – The scheduler config; [simulation] load_dir is read with the default pyretis.inout.archive_paths.ARCHIVE_SUBDIR.
Raises:: TOMLConfigError – If load_dir is not a string, is an absolute path, or its first component is one of these names.

pyretis.simulation.setup.refuse_run_engines(config: dict, log_warnings: bool = True) → None¶

Refuse, before a run writes a file, the engines it cannot run.

Every route of a path-sampling run calls this function before it writes a file of the run: the scheduler (setup_internal()) before it loads its paths, the canonical route (pyretis.bin.pyretisrun.run_pyretis_path_sampling()) before its initiation or continuation, and the run of a legacy-runner input (pyretis.bin.pyretisrun.run_legacy_runner_config()) before it records its input. When no section is refused, the warnings of the engines are logged once per section (pyretis.engines.engine.log_path_sampling_warnings()).

Parameters:

config (dict) – The scheduler configuration, with ensemble_engines (apply_config_defaults()).
log_warnings (bool, optional) – False when another check of the same run logs the warnings: the check of pyretis.bin.pyretisrun.run_pyretis_path_sampling() before it initiates the paths that setup_internal() then loads, or the check of setup_internal() for a continuation and for the load of a new run.

Raises:

ValueError – If an engine section of the run integrates with an integrator a path-sampling run cannot use (refuse_path_sampling_engines()), or a GROMACS engine section, its class imported from a module included, sets no mdrun and the input sets no [runner] wmdrun (pyretis.inout.config_adapter.refuse_gromacs_without_mdrun()).

pyretis.simulation.setup.refuse_too_many_workers(config: dict) → None¶

Refuse a run with more workers than live path ensembles.

The workers are compared with the ensemble topology of the run (live_ensemble_count()): full RETIS has one live ensemble per interface ([0^-], [0^+], [1^+], …), explore and the PPTIS variants without a minus ensemble have fewer. The scheduler checks it (check_config()), and every route that writes a file before the scheduler starts checks it first: pyretis run before the initiation or the continuation of a run (pyretis.bin.pyretisrun.run_pyretis_path_sampling()), the run of a legacy-runner input before it records its input, and pyretis tools init before it makes its first step directory (pyretis.tools.interface_optimizer.run_infinit()).

Parameters:: config (dict) – The scheduler configuration, with [runner] workers.
Raises:: TOMLConfigError – If [runner] workers is larger than the number of live path ensembles.

pyretis.simulation.setup.run_engine_sections(config: dict) → list¶

Return the engine sections of a path-sampling run.

The sections are [engine], when the configuration holds it, and each section [simulation] ensemble_engines names. [engine] is one of them when no ensemble runs with it: the kick initiation generates the initial paths with it, and the analysis converts the path lengths to time with its time per step (pyretis.core.engine_time.engine_time_per_step()).

Parameters:: config (dict) – A scheduler configuration whose [simulation] ensemble_engines is set (apply_config_defaults()).
Returns:: list of strings – Each section once: "engine" first, then the others in the order of the ensembles.

pyretis.simulation.setup.run_kick_phase(config: dict, run_dir: str) → str¶

Kick-initiate every ensemble in parallel, one job per ensemble.

Builds a short-lived worker pool (the same aiorunner / worker_initializer / create_engines machinery setup_runner() uses for the steady-state scheduler loop), dispatches one kick job per ensemble, waits for all to complete, and serialises each accepted path into its per-ensemble archive <ensemble>/<load_dir>/<i>/ via the existing pyretis.inout.config_adapter._write_external_path_files() / pyretis.inout.config_adapter._write_inf_path_files() writers – the on-disk contract pyretis.core.path_load.load_paths_from_disk() reads when the steady-state scheduler that follows this call loads its paths.

Only [initial-path] kick-from = "initial" is supported here: each ensemble’s kick is initiated independently, from its own starting system, in parallel. kick-from = "previous" (each ensemble seeded from the closest phase point of the PREVIOUS ensemble’s just-kicked path) is inherently sequential – the caller is responsible for routing that case to the existing pyretis.inout.config_adapter.generate_load_dir() instead.

Parameters:

config (dict) – The translated scheduler config (see pyretis.inout.config_adapter.to_scheduler_config()), with apply_config_defaults already applied (so ensemble_engines/load_dir are populated).
run_dir (str) – The absolute directory the simulation runs from.

Returns:

str – The run directory (the per-ensemble archives live under it; there is no single top-level load path).

pyretis.simulation.setup.setup_config(inp: str = 'output.toml', re_inp: str = 'output.toml') → dict | None¶

Set dict from a TOML file up.

The single run file is output.toml: it carries the canonical sections of the run, every default resolved, and, once the scheduler has written it, the running [current] state. A fresh start and a resume therefore read the same file, through pyretis.inout.run_record.load_run(). An input of the legacy-runner schema ([simulation.tis_set], no [current]) is read in its canonical form, converted and checked by pyretis.inout.run_record.load_legacy_run(), with a deprecation notice. A state file of the scheduler configuration written by an earlier PyRETIS (an output.toml or restart.toml with [simulation.tis_set] and [current]) is read as it is. The configuration of a run file with canonical sections, and of a converted legacy-runner input, holds the canonical sections under pyretis.inout.run_record.RUN_RECORD_KEY, and the scheduler writes them back with [current].

Parameters:

inp (str) – A string specifying the input file (def: output.toml).
re_inp (str) – A string specifying the restart file (def: output.toml). When it differs from inp (a foreign run file is passed) and exists, it is rejected so a stray state file cannot shadow the run file.

Returns:

dict or None – A dictionary containing the configuration parameters; None when inp is missing, or when the state it holds has reached the step target, [simulation] steps.

Raises:

TOMLConfigError – If [simulation] load_dir names no directory of its own inside the ensemble directory (see refuse_reserved_load_dir()).
FileNotFoundError – If a resumed state lists an active path whose traj.txt is missing (see _refuse_missing_active_paths()).
ValueError – If the resume draws the shooting velocities from another distribution than the run that wrote the state (see _check_resumed_draws()), or streams a built-in internal integrator with other subcycles than that run (see _check_resumed_subcycles()); or if a legacy-runner input has no canonical form, or gives a key that takes no effect on its run.
RuntimeError – If the canonical form of a legacy-runner input does not give the scheduler configuration of the input (see pyretis.tools.convert_legacy_schema.convert_legacy_document()).

pyretis.simulation.setup.setup_internal(config: dict) → tuple[dict, InfSwapState]¶

Run the various setup functions.

The engine sections are checked first (refuse_run_engines()), and the warnings of their engines are logged, except for a run whose initial paths the caller has just generated: the caller checked the engines, and logged their warnings, before the initiation.

Parameters:

config (dict) – the configuration dictionary. The keys pyretis.inout.staged_paths.INITIATED_PATHS_KEY and pyretis.inout.run_record.RUN_RECORD_KEY are removed from it; the recorded sections go to the state, which writes them into output.toml.

Returns:

tuple – A blank md_items dict An initialized REPEX state

Raises:

ValueError – If the run cannot run an engine section of the configuration (refuse_run_engines()), before a path is loaded or written.
ValueError – For a run with a LAMMPS engine, if a loaded path has a phase point held in a LAMMPS restart file (_refuse_lammps_restart_paths()).

pyretis.simulation.setup.setup_runner(state: InfSwapState) → tuple[aiorunner, future_list]¶

Set the task runner class up.

Parameters:: state (InfSwapState) – A REPEX state from which to get the config dict

pyretis.simulation.setup.warn_workers_without_swapping(config: dict) → None¶

Warn when the workers leave the swaps of a run without effect.

A move locks the ensemble it runs in and the path it starts from until it ends. With [runner] workers equal to the number of live path ensembles, every pick after the first moves finds one free ensemble and one free path. Two runs swap paths between ensembles, and with as many workers as live ensembles neither swaps a path:

a retis run swaps by infinite swapping, which then exchanges no path between ensembles: the run samples as replica exchange without swaps;
a repptis run with a swap probability above zero ([retis] swapfreq) swaps a path with a neighbouring ensemble, which is then always locked: the run samples as PPTIS.

The warning is logged and the run continues. The other runs swap no paths between ensembles (tis, pptis, explore, a run of one ensemble, a repptis run with swapfreq = 0), and are not warned.

Parameters:: config (dict) – The scheduler configuration, checked by check_config().

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)¶

Bases: object

This class defines a generic simulation.

Variables:

cycle (dict of integers) –
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.
exe_dir (string) – The path we are running the simulation from.
restart_freq (integer) – The frequency for creating restart files.
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.
simulation_output (list of dicts) – This list defines the output tasks associated with the simulation.
simulation_type (string) – An identifier for the simulation.
tasks (list of objects like SimulationTask) – This is the list of simulation tasks to execute.

__init__(settings, controls)¶

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__()¶: Just a small function to return some info about the simulation.

add_task(task, position=None)¶

Add a new simulation task.

A task can also be added manually by simply appending to 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, the label for 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)¶

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()¶

Execute all the tasks in sequential order.

Returns:: results (dict) – The results from the different tasks (if any).

extend_cycles(steps)¶

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()¶

Determine if the simulation is finished.

In this object, the simulation is done if the current step number is larger than or equal to 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)¶

Load restart information.

The full cycle state is restored from the restart file; the NEW input then defines where the continued run ends: steps on a restart is the run’s TOTAL step target (a restart of a 125-step run with steps = 200 continues 125 -> 200), exactly like the scheduler route’s restart contract. startcycle becomes the resume point (the restored step), where the -p progress bar of the continued run starts.

Parameters:: info (dict) – The dictionary with the restart information.

restart_info()¶

Return information which can be used to restart the simulation.

Returns:: info (dict,) – Contains all the updated simulation settings and counters, and the provenance of the restart file, which carries pyretis.core.provenance.TEMPERATURE_RULE_KEY: the temperature of the system is the temperature the run ran at (pyretis.engines.run_temperature.resolve_restart_temperature()).

run()¶

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)¶

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()¶: Force simulation to stop at the current step.

step()¶

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)¶

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.

class pyretis.simulation.simulation_task.SimulationTask(function, args=None, kwargs=None, when=None, result=None, first=False)¶

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).

Variables:

function (function) – The function to execute.
when (dict) – Determines when 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)¶

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)¶

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__()¶: Output info about the task.

execute(step)¶

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()¶: Return True if task should be executed before first step.

task_dict()¶: Return a dict representing the task.

pyretis.simulation.simulation_task._check_args(function, given_args=None, given_kwargs=None)¶

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 input function is inspected with pyretis.core.common.inspect_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 is 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.