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

• pyretis.simulation.mc_simulation

• pyretis.simulation.md_simulation

• pyretis.simulation.path_simulation

• pyretis.simulation.repex

• pyretis.simulation.scheduler

• pyretis.simulation.setup

• pyretis.simulation.simulation

• pyretis.simulation.simulation_task

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:

asyncio.Future – A future wih the results of the work

async _cancel_pending_tasks() → None

Cancel the worker-wrapper tasks and await their completion.

_start_event_loop() → None

Start the event loop in a separate thread.

async _start_tasks() → None

Launch the background tasks.

async _task_wrapper(stop_event: Event, queue: Queue, executor: Executor, taskID: int) → None

Wrap the sync task.

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

Parameters:

• stop_event (asyncio.Event) – a asyncio event to stop the worker

• queue (asyncio.Queue) – an asyncio queue to get work from

• executor (concurrent.futures.Executor) – an executor

• taskID (int) – an ID for the long running task

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:

Future – A future wih the results of the work

async wait_for_tasks_to_end() → None

Async function waiting for tasks to end.

class pyretis.simulation.async_runner.future_list

Bases: object

A managed list of future.

__init__() → None

Initialize future list.

add(future: Future) → None

Add a future to list.

as_completed() → Future | None

Get future as they are done.

Returns:

asyncio.Future, optional – return a future from the list, whenever it is done or return 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 natively; 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 native [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 pyretis.core.tis.make_tis_step_ensemble() method will make use of additional keys from settings['tis']. Please see this method for further details. For the settings['retis'] we expect to find the following keys:

  • swapfreq: The frequency for swapping moves.

  • relative_shoots: If we should do relative shooting for the path ensembles.

  • nullmoves: Should we perform null moves.

  • swapsimul: Should we just swap a single pair or several pairs.

  required_settingstuple of strings

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

__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 – The native in-process loop has been retired. All path-sampling tasks now route through the scheduler.

simulation_output = [{'name': 'path_ensemble', 'result': ('pathensemble-{}',), 'type': 'pathensemble'}, {'name': 'path_ensemble-order', 'result': ('path-{}', 'status-{}'), 'type': 'path-order'}, {'name': 'path_ensemble-traj', 'result': ('path-{}', 'status-{}', 'pathensemble-{}'), 'type': 'path-traj-{}'}, {'name': 'path_ensemble-energy', 'result': ('path-{}', 'status-{}'), 'type': 'path-energy'}]

simulation_type = 'generic-path'

step()

Perform a TIS/RETIS/PPRETIS simulation step.

Raises:

RuntimeError – The native in-process loop has been retired. All path-sampling tasks now route through the scheduler (pyretisrun dispatches to the infinite-swapping scheduler at n_workers=1).

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', 'result': ('pathensemble-{}',), 'type': 'pathensemble'}, {'name': 'path_ensemble-order', 'result': ('path-{}', 'status-{}'), 'type': 'path-order'}, {'name': 'path_ensemble-traj', 'result': ('path-{}', 'status-{}', 'pathensemble-{}'), 'type': 'path-traj-{}'}, {'name': 'path_ensemble-energy', 'result': ('path-{}', 'status-{}'), 'type': 'path-energy'}, {'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', 'result': ('pathensemble-{}',), 'type': 'pathensemble'}, {'name': 'path_ensemble-order', 'result': ('path-{}', 'status-{}'), 'type': 'path-order'}, {'name': 'path_ensemble-traj', 'result': ('path-{}', 'status-{}', 'pathensemble-{}'), 'type': 'path-traj-{}'}, {'name': 'path_ensemble-energy', 'result': ('path-{}', 'status-{}'), 'type': 'path-energy'}, {'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 pyretis’s native move suite swap moves.

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 native frequency move for a single pick.

Ports the per-cycle move selection of the native make_tis_step_ensemble routine onto the scheduler. For a single-ensemble (non-swap) pick the configured shooting move is replaced, with the native [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 – native ensemble_number == 0, which is scheduler pick key -1 – matching native’s 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 native), and the result overrides mc_move on the (locked, hence worker-private for this cycle) ensemble dict. The move order in the draw matches native (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 initiate_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 unconditionally (rather than filtering on mc_move == 'bias') keeps every ensemble-construction branch covered and is immune to the init-time vs _apply_freq_moves move-index offset.

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

_native_energy_engine()

Return a cached streaming engine for native 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 native energy.txt keeps the engine’s in-memory terms (nan when absent).

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

Add traj to state and calculate P matrix.

property cap

Retrieve mc moves list from config dict.

capture_native_row(pn, path, status)

Store the native 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 native path status (e.g. "ACC").

compute_swap_matrix(input_mat, locks)

Permanent calculator (the infinite-swap probability matrix).

property cstep

Retrieve cstep from config dict.

cworker = None

property data_dir

Retrieve data_dir from config 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.

property interfaces

Retrieve interfaces from config 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 maxop

Get the maximum orderparameter seen during the simulation.

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.

permanent_prob(arr)

P matrix calculation for specific W matrix.

pick()

Pick path and ens.

pick_lock()

Pick path and ens.

In case a crash, we pick lock locked from previous simulation.

pick_traj_ens(ens)

Pick traj ens.

prep_md_items(md_items)

Fill md_items with picked path and ens.

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.

prune_native_rows()

Drop captured native rows for paths that are no longer live.

Only live paths receive frac increments (see treat_output), so a path that has left every ensemble can never contribute another native 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()

Set numpy random generator state from restart.

sort_trajstate()

Sort trajs and calculate P matrix.

swap(traj, ens)

Swap to keep the locks symmetric.

treat_output(md_items)

Treat output.

property tsteps

Retrieve total steps from config dict.

unlock(ens)

Unlock ensemble.

property workers

Retrieve workers from config dict.

write_toml()

Write the fully-resolved config + state to ./output.toml.

output.toml is the single run file: it holds the resolved configuration (settings with their applied defaults) together with the running [current] state (cstep, RNG, frac, active paths). The scheduler writes it once at start-up and then once per cycle; a resume reads the same file (see pyretis.simulation.setup.setup_config()).

Sequence: serialise to output.toml.tmp with an explicit fsync so the new payload is on disk; copy any existing output.toml to output.toml.prev so the previous cycle’s state survives even if the final rename loses a race with a power loss; os.replace the tmp file over output.toml (POSIX-atomic on the same filesystem); finally best-effort fsync the parent directory so the rename commit is past the filesystem journal.

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.scheduler(config)

Run the infinite-swapping scheduler loop.

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.

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 native 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 native in-memory pyretis.setup.createsimulation.prepare_system() output.

This resolves the full native particle/box/forcefield setup once via prepare_system (handling every native 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._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._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._write_kick_results(config: dict, run_dir: str, results: list) → str

Serialise every kick result into load_dir/<i>/.

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.

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 absolute path to the populated load_dir.

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

Fill in the resolved configuration defaults in place.

Sets the per-ensemble engine list and the [simulation] / [simulation.tis_set] / [output] defaults, validates the output-deletion settings, and applies the quantis engine override. 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.

Parameters:

config (dict) – The configuration dictionary, mutated in place.

Returns:

dict – The same config dictionary, with defaults applied.

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.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 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.native_to_infswap_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 absolute path to the populated load_dir.

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 fully-resolved configuration (settings + applied defaults) and, once the scheduler has written it, the running [current] state. A fresh start and a resume therefore read the same file. The legacy infswap.toml / restart.toml names are still accepted (an existing on-disk run started before the consolidation keeps resuming) – the caller just passes that filename as inp.

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 or None.

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

Run the various setup functions.

Parameters:

config (dict) – the configuration dictionary

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, used to label the result.

• position (int, optional) – Can be used to give the tasks a specific position in the task list.

create_output_tasks(settings, progress=False)

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.

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

Parameters:

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

restart_info()

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.