wepy.sim_manager module

Module for the main simulation management class.

All component class interfaces are set by how the manager interacts with them.

Managers should implement a three phase protocol for running simulations:

  • init

  • run_simulation

  • cleanup

The separate init method is different than the constructor __init__ method and instead calls the special init method on all wepy components (runner, resampler, boundary conditions, and reporters) at runtime.

This allows for a things that need to be done at runtime before a simulation begins, e.g. opening files, that you don’t want done at construction time.

This is useful for orchestration because the complete simulation ‘image’ can be made before runtime (and pickled or otherwise persisted) without producing external effects.

This is used primarily for reporters, which perform I/O, and work mappers which may spawn processes.

The cleanup method should be called either when the simulation ends normally as well as when the simulation ends abnormally.

This allows file handles to be closed and processes to be killed at the end of a simulation and upon failure.

The base methods for running simulations is run_cycle which runs a cycle of weighted ensemble given the state of all the components.

The simulation manager should provide multiple ways of running simulations depending on if the number of cycles is known up front or to be determined adaptively (e.g. according to some time limit).

class wepy.sim_manager.Manager(init_walkers, runner=None, work_mapper=None, resampler=None, boundary_conditions=None, reporters=None, sim_monitor=None)[source]

Bases: object

The class that coordinates wepy simulations.

The Manager class is the lynchpin of wepy simulations and is where all the different components are composed.

Strictly speaking the Manager defines the interfaces each component must provide to function.

Developers can call run_cycle directly but the following convenience functions are provided to run many cycles in succession as a single ‘run’ with consecutive cycle idxs:

  • run_simulation_by_time

  • run_simulation

The corresponding ‘continue’ run methods will simply pass a run index to reporters indicating that the run continues another.

For these run methods the init method is called followed by iterative calls to run_cycle and finally with a call to cleanup.

The order of application of wepy components are:

  • runner

  • boundary_conditions

  • resampler

  • reporters

Constructor for Manager.

Parameters

  • init_walkers (list of walkers) – The list of the initial walkers that will be run.

  • runner (object implementing the Runner interface) – The runner to be used for propagating sampling segments of walkers.

  • work_mapper (object implementing the WorkMapper interface) – The object that will be used to perform a set of runner segments in a cycle.

  • resampler (object implementing the Resampler interface) – The resampler to be used in the simulation

  • boundary_conditions (object implementing BoundaryCondition interface, optional) – The boundary conditions to apply to walkers

  • reporters (list of objects implenting the Reporter interface, optional) – Reporters to be used. You should provide these if you want to keep data.

  • sim_monitor (SimMonitor object) – An object implementing SimMonitor interface for providing monitoring metrics of a simulation.

Warning

While reporters are strictly optional, you probably want to provide some because the simulation manager provides no utilities for saving data from the simulations except for the walkers at the end of a cycle or simulation.

See also

wepy.reporter.hdf5

The standard reporter for molecular simulations in wepy.

wepy.orchestration.orchestrator.Orchestrator

for running simulations with checkpointing, restarting, reporter localization, and configuration hotswapping with command line interface.

REPORT_ITEM_KEYS = ('cycle_idx', 'n_segment_steps', 'new_walkers', 'resampled_walkers', 'warp_data', 'bc_data', 'progress_data', 'resampling_data', 'resampler_data', 'worker_segment_times', 'cycle_runner_time', 'cycle_bc_time', 'cycle_resampling_time')

Keys of values that will be passed to reporters.

This indicates the values that the reporters will have access to.

run_segment(walkers, segment_length, cycle_idx)[source]

Run a time segment for all walkers using the available workers.

Maps the work for running each segment for each walker using the work mapper.

Walkers will have the same weights but different states.

Parameters

  • walkers (list of walkers) –

  • segment_length (int) – Number of steps to run in each segment.

Returns

new_walkers – The walkers after the segment of sampling simulation.

Return type

list of walkers

run_cycle(walkers, n_segment_steps, cycle_idx, runner_opts=None)[source]

Run a full cycle of weighted ensemble simulation using each component.

The order of application of wepy components are:

  • runner

  • boundary_conditions

  • resampler

  • reporters

The init method should have been called before this or components may fail.

This method is not idempotent and will alter the state of wepy components.

The cycle is not kept as a state variable of the simulation manager and so myst be provided here. This motivation for this is that a cycle index is really a property of a run and runs can be composed in many ways and is then handled by higher-level methods calling run_cycle.

Each component should implement its respective interface to be called in this method, the order and names of the methods called are as follows:

  1. runner.pre_cycle

  2. run_segment -> work_mapper.map(runner.run_segment)

  3. runner.post_cycle

  4. boundary_conditions.warp_walkers (if present)

  5. resampler.resample

  6. reporter.report for all reporters

The pre and post cycle calls to the runner allow for a parity of one call per cycle to the runner.

The boundary_conditions component is optional, as are the reporters (although it won’t be very useful to run this without any).

Parameters

  • walkers (list of walkers) –

  • n_segment_steps (int) – Number of steps to run in each segment.

  • cycle_idx (int) – The index of this cycle.

Returns

  • new_walkers (list of walkers) – The resulting walkers of the cycle

  • sim_components (list) – The runner, resampler, and boundary conditions objects at the end of the cycle.

See also

run_simulation

To run a simulation by the number of cycles

run_simulation_by_time

_run_cycle(walkers, n_segment_steps, cycle_idx, runner_opts=None)[source]

See run_cycle.

init(num_workers=None, continue_run=None)[source]

Initialize wepy configuration components for use at runtime.

This init method is different than the constructor __init__ method and instead calls the special init method on all wepy components (runner, resampler, boundary conditions, and reporters) at runtime.

This allows for a things that need to be done at runtime before a simulation begins, e.g. opening files, that you don’t want done at construction time.

It calls the init methods on:

  • work_mapper

  • reporters

Passes the segment_func of the runner and the number of workers to the work_mapper.

Passes the following things to each reporter init method:

  • init_walkers

  • runner

  • resampler

  • boundary_conditions

  • work_mapper

  • reporters

  • continue_run

Parameters

  • num_workers (int) –

    The number of workers to use in the work mapper.

    (Default value = None)

  • continue_run (int) –

    Index of a run this one is continuing.

    (Default value = None)

cleanup()[source]

Perform cleanup actions for wepy configuration components.

Allow components to perform actions before ending the main simulation manager process.

Calls the cleanup method on:

  • work_mapper

  • reporters

Passes nothing to the work mapper.

Passes the following to each reporter:

  • runner

  • work_mapper

  • resampler

  • boundary_conditions

  • reporters

run_simulation_by_time(run_time, segments_length, num_workers=None)[source]

Run a simulation for a certain amount of time.

This starts timing as soon as this is called. If the time before running a new cycle is greater than the runtime the run will exit after cleaning up. Once a cycle is started it may also run over the wall time.

All this does is provide a run idx to the reporters, which is the run that is intended to be continued. This simulation manager knows no details and is left up to the reporters to handle this appropriately.

Parameters

  • run_time (float) – The time to run in seconds.

  • segments_length (int) – The number of steps for each runner segment.

  • num_workers (int) –

    The number of workers to use for the work mapper.

    (Default value = None)

Returns

  • new_walkers (list of walkers) – The resulting walkers of the cycle

  • sim_components (list) – Deep copies of the runner, resampler, and boundary conditions objects at the end of the cycle.

See also

wepy.orchestration.orchestrator.Orchestrator

for running simulations with checkpointing, restarting, reporter localization, and configuration hotswapping with command line interface.

run_simulation(n_cycles, segment_lengths, num_workers=None)[source]

Run a simulation for an explicit number of cycles.

Parameters

  • n_cycles (int) – Number of cycles to perform.

  • segment_lengths (int) – The number of steps for each runner segment.

  • num_workers (int) –

    The number of workers to use for the work mapper.

    (Default value = None)

Returns

  • new_walkers (list of walkers) – The resulting walkers of the cycle

  • sim_components (list) – Deep copies of the runner, boundary conditions, and resampler objects at the end of the simulation.

See also

wepy.orchestration.orchestrator.Orchestrator

for running simulations with checkpointing, restarting, reporter localization, and configuration hotswapping with command line interface.

continue_run_simulation(run_idx, n_cycles, segment_lengths, num_workers=None)[source]

Continue a simulation. All this does is provide a run idx to the reporters, which is the run that is intended to be continued. This simulation manager knows no details and is left up to the reporters to handle this appropriately.

Parameters

  • run_idx (int) – Index of the run you are continuing.

  • n_cycles (int) – Number of cycles to perform.

  • segment_lengths (int) – The number of steps for each runner segment.

  • num_workers (int) –

    The number of workers to use for the work mapper.

    (Default value = None)

Returns

  • new_walkers (list of walkers) – The resulting walkers of the cycle

  • sim_components (list) – Deep copies of the runner, resampler, and boundary conditions objects at the end of the cycle.

See also

wepy.orchestration.orchestrator.Orchestrator

for running simulations with checkpointing, restarting, reporter localization, and configuration hotswapping with command line interface.

continue_run_simulation_by_time(run_idx, run_time, segments_length, num_workers=None)[source]

Continue a simulation with a separate run by time.

This starts timing as soon as this is called. If the time before running a new cycle is greater than the runtime the run will exit after cleaning up. Once a cycle is started it may also run over the wall time.

All this does is provide a run idx to the reporters, which is the run that is intended to be continued. This simulation manager knows no details and is left up to the reporters to handle this appropriately.

Parameters

run_idx (int) – Deep copies of the runner, resampler, and boundary conditions objects at the end of the cycle.

See also

wepy.orchestration.orchestrator.Orchestrator

for running simulations with checkpointing, restarting, reporter localization, and configuration hotswapping with command line interface.