pyretis.simulation package

pyretis.simulation package

This package defines different simulations for use with PyRETIS.

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

Package structure

Modules

md_simulation.py (pyretis.simulation.md_simulation)

Defines simulation classes for molecular dynamics simulations.

mc_simulation.py (pyretis.simulation.mc_simulation)

Define simulation classes for Monte Carlo simulations.

path_simulation.py (pyretis.simulation.path_simulation)

Defines simulation classes for path simulations.

simulation.py (pyretis.simulation.simulation)

Defines the Simulation class which is the base class for simulations.

simulation_task.py (pyretis.simulation.simulation_task)

Defines classes for the handling of simulation tasks.

Important classes defined in this package

Simulation (Simulation)

The base class for simulations.

SimulationTask (SimulationTask)

A class for creating tasks for simulations.

SimulationSingleTIS (SimulationSingleTIS)

A class for running a TIS simulation for a single ensemble.

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.

List of submodules

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)

Initialize function for each worker process.

pyretis.simulation.mc_simulation module

Definition of simulation objects for Monte Carlo simulations.

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

Important classes defined here

UmbrellaWindowSimulation (UmbrellaWindowSimulation)

Defines a simulation for performing umbrella window simulations. Several umbrella window simulations can be joined to perform a umbrella simulation.

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

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:

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

  • 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

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

__init__(ensemble, settings, controls=None)

Initialise the umbrella simulation 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:

    • mincycle : int, optional The MINIMUM number of cycles to perform. Note that in base Simulation class this is the MAXIMUM number of cycles to perform. The meaning is redefined in this class by overriding self.simulation_finished.

    • 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 we cycle is larger than maxcycle and all particles have crossed self.overlap.

Returns:

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

load_restart_info(info)

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 somply MD.

SimulationMDFlux (SimulationMDFlux)

Definition of a simulation for determining the initial flux. This is used for calculating rates in TIS simulations.

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

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)

Only add variable.

Parameters:

  • ensemble (dict) – It contains the simulations info

    • system : object like System This is the system we are investigating.

    • engine : object like EngineBase This is the integrator that is used to propagate the system in time.

    • order_function : object like OrderParameter, optional. A class that can be used to calculate an order parameter, if needed.

  • settings (dict, optional) – This dictionary contains the settings for the simulation.

  • controls (dict of parameters, optional) – It contains:

    • steps : int, optional The number of simulation steps to perform.

    • startcycle : int, optional The cycle we start the simulation on, can be useful if restarting.

__str__()

Return a string with info about the simulation.

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 we here require that the engine supports NVE dynamics.

__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 (SimulationSingleTIS)

Definition of a TIS simulation for a single path ensemble.

SimulationRETIS (SimulationRETIS)

Definition of a RETIS simulation.

SimulationPPRETIS (SimulationPPRETIS)

Definition of a PPRETIS simulation.

class pyretis.simulation.path_simulation.PathSimulation(ensembles, settings, controls)

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.

    Note that the classic make_tis_step_ensemble routine made use of additional keys from settings['tis']; that routine was retired with the in-process native loop. 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. A future phase will collapse this with pyretis’s classic move suite swap moves.

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.

Ports the per-cycle move selection of the classic make_tis_step_ensemble routine onto the scheduler. 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 – classic ensemble_number == 0, which is scheduler pick key -1 – matching the classic ensemble_number != 0 gate.

The draw is taken from the ensemble’s per-cycle rgen (the same generator the move itself consumes, so the choice-then-move ordering follows the classic layout), and the result overrides mc_move on the (locked, hence worker-private for this cycle) ensemble dict. The move order in the draw matches the classic one (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_energy_engine()

Return a cached streaming engine for energy recompute.

Built once from self.config (force field + masses, via the engine’s setup_streaming) and reused for every captured path. Returns None when the configured engine is not a streaming internal integrator that can recompute energy from stored frames (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).

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

_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 or explore) has no [0^-]: ensemble ens_num is keyed at ens_num.

_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 base distribution is the infinite-swap probability matrix (prob), optionally reweighted per ensemble column by the inf-init pick_scheme exponent and by the fixed relative_shoots frequencies. Split out of pick() so the weighting is unit-testable without driving the full pick/lock machinery.

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

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

property cap

Retrieve mc moves list 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)

Permanent calculator (the infinite-swap probability matrix).

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, so the run can report a true acceptance ratio without re-reading its output.

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.

No explicit date: lines here (or in initiate()): every log line already carries its own timestamp through the file formatter (pyretis.inout.formats.formatter .PyretisLogFormatter).

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. A live property (not cached in __init__) so a test or tool that toggles the flags after construction is reflected.

pathensemble_nacc: dict
pathensemble_nshoot: dict
pathensemble_rows: dict
permanent_prob(arr)

P matrix calculation for specific W matrix.

pick()

Pick path and ens.

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 actually attempted, so a move that was never drawn is reported as such rather than as a ratio.

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.

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)

Name what an ensemble IS, rather than where it sits.

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. Deriving one from the other labels a body window in slot 0 as the [0^+] that is absent, or the [0^+] in slot 0 as the minus window that is absent.

Geometry alone will not do it either, and the two cases that defeat it are both real. [0^+] has its middle ON its left interface, so left < middle < right is false for an ensemble that is a positive one; and the permeability [0^-] has a genuine midpoint, so the same test is true for an ensemble that is not a body.

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._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() multiplies its (traj, ens) probability matrix by these weights column-wise, so a heavier ensemble is simply picked (and hence shot in) more often – the retired in-process loop’s weighted per-step ensemble selection (relative_shoots_select). The weights are state-independent, so every ensemble still samples its own stationary distribution; only the allocation of moves changes.

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. A plain column-wise product would skew the marginal by the unequal column sums of the base matrix. 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.repex.spawn_rng(rgen)

Reimplementation of np.random.Generator.spawn() for numpy <= 1.24.4.

Spawns a new random number generator (RNG) from an existing RNG.

This function creates a new instance of the same type of RNG as the input RNG, using a seed generated from the input RNG’s bit generator.

Parameters:

rgen (np.random.Generator) – The input random number generator.

Returns:

np.random.Generator – A new random number generator instance.

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; the progress bar refreshes several times a second, and reading the whole file each time would cost more the longer the trajectory ran – on a shared filesystem, exactly when it is least affordable. 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.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 its true position instead of starting over from zero.

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 instead of waiting for it to finish. That is the supported way to step a path simulation from your own code: the in-process loop that PathSimulation.step for providing is gone, but this gives back the same control without a second implementation of the sampling.

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). For an internal engine, this means EngineBase._is_streaming – which gates whether modify_velocities takes the streaming (raw-numpy-rgen-compatible) branch or the legacy classic one (which needs a pyretis.core.random_gen.RandomGenerator-wrapped rgen, the wrong type for the scheduler’s rgen convention) – is true only when the system handed to it carries NO in-memory particles (has_particles=False, a file-backed snapshot). External engines are file-backed by construction already. So the starting system for every kick job must be a snapshot, not the in-memory pyretis.setup.createsimulation.prepare_system() output.

This resolves the full particle/box/forcefield setup once via prepare_system (handling every classic 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.

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, which is acceptable under “init = validity not identity” (the kick phase does not need to 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._build_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:
Returns:

list of dict – One run_parallel_kick_job result per kick item.

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._left_wavefunction_store(base: str) → list[str]

Return the CP2K wavefunction store of a run directory, if any.

Parameters:

base (str) – The absolute run directory.

Returns:

out (list of str) – The store pyretis.engines.cp2k.WFN_STORE of base when it exists, and an empty list otherwise.

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. An input of the legacy-runner schema (see pyretis.inout.run_record.is_legacy_runner_input()) is read in its canonical form, converted and checked by pyretis.inout.run_record.load_legacy_run(). Every other file is a state file of the scheduler configuration itself, written by an earlier PyRETIS, and is the configuration as it is.

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._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> for a run whose paths were stored before the per-ensemble nesting (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._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 rather than reading a module global.

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

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

  • the wavefunction store pyretis.engines.cp2k.WFN_STORE of an earlier run: a streaming CP2K engine of the new run, the initiation included, would start its SCF from the wavefunctions found there.

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

  • for a load of the flat store, and for a run directory that holds ensemble output, the wavefunction store pyretis.engines.cp2k.WFN_STORE: a streaming CP2K engine of the new run would start its SCF from the wavefunctions found there.

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, an archive directory of an active path or the wavefunction store. 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_left_wavefunction_store(run_dir: str) → None

Refuse to start a run of staged paths beside a CP2K store.

A run of a legacy-runner input starts a new simulation from the initial paths staged in the run directory, and runs no engine before the scheduler loads them. The wavefunction store pyretis.engines.cp2k.WFN_STORE that the run directory holds before such a run starts was written by an earlier run, and a streaming CP2K engine of the new run would start its SCF from it.

Parameters:

run_dir (str) – The directory the simulation runs from.

Raises:

FileExistsError – If the run directory holds the store. The message names it.

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;

  • pyretis.engines.cp2k.WFN_STORE, the directory of the run directory the streaming CP2K engine keeps its wavefunctions in;

  • 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.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 same on-disk contract pyretis.core.path_load.load_paths_from_disk() reads, so the steady-state scheduler that follows this call needs no changes.

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:
pyretis.simulation.setup.setup_internal(config: dict) → tuple[dict, InfSwapState]

Run the various setup functions.

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

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.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 still be added manually by simply appending to py:attr:.tasks. This function will, however, do some checks so that the task added can be executed.

Parameters:

  • task (dict) – A dict defining the task. A task is represented by an object of type SimulationTask with some additional settings on how to store the output and when to execute the task. The keywords in the dict defining the task are:

    • func: Callable, this is a function to execute in the task.

    • args: List, with arguments for the function.

    • kwargs: Dict, with the keyword arguments for the function.

    • when: Dict, which defines when the task should be executed.

    • first: Boolean, determines if the task should be executed on the initial step, i.e. before the full simulation starts.

    • result: String, 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 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 truthful resume point (the restored step), which is what keeps the -p progress bar honest across restarts. The previous code instead clobbered startcycle with the OLD run’s step target (dict-order dependent), so an interrupted-run restart displayed a full/ overflowing progress bar from its first step.

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.

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.

SimulationTaskList (SimulationTaskList)

A class for representing a list of simulation tasks. This class defines functionality for adding tasks from a dictionary description.

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

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 function inspect.getargspec is used to check the input function.

Parameters:

  • function (callable) – The function we will inspect.

  • given_args (list, optional) – A list of the arguments to pass to the function. ‘self’ will not be considered here since it passed implicitly.

  • given_kwargs (dict, optional) – A dictionary with keyword arguments.

Returns:

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