pyrevs.strategies.ams

Submodules

• pyrevs.strategies.ams.ams
• pyrevs.strategies.ams.config
• pyrevs.strategies.ams.extension
• pyrevs.strategies.ams.sql

Classes

AMS	A strategy class implementing (T)AMS.
AMSConfig	AMS strategy configuration.
AMSDatabaseExtension	An extension class for the AMS strategy.

Functions

load_database_extension(→ extension.AMSDatabaseExtension)

A factory function to instanciate the extension from the database.

Package Contents

class AMS(fmodel_t: Any, runtime_cfg: pyrevs.core.RuntimeConfig, runner_cfg: pyrevs.runner.RunnerConfig, strategy_cfg: pyrevs.strategies.ams.config.AMSConfig, deterministic: bool)

Bases: pyrevs.strategies.base.BaseSamplingStrategy

A strategy class implementing (T)AMS.

The interface to (T)AMS, implementing the main steps of the algorithm.

Initialization of the (T)AMS class requires a forward model type which encapsulate all the model-specific code, and an optional list of options.

The algorithm is roughly divided in two steps: 1. Initialization of the trajectory ensemble 2. Splitting iterations

Separate control of the parallelism is provided for both steps.

All the algorithm data are contained in the (T)AMS database. For control purposes, a walltime limit is also provided. It is passed to working and lead to the termination of the algorithm in a state that can be saved to disk and restarted at a later stage.

Variables:

• _fmodel_t – the forward model type

• _config – the config object

• _wallTime – the walltime limit

• _init_ensemble_only – whether or not to stop after initializing the trajectory ensemble

generate_trajectory_ensemble(tdb: pyrevs.database.Database) → None

Schedule the generation of an ensemble of stochastic trajectories.

Loop over all the trajectories in the database and schedule advancing them to either end time or convergence with the runner.

The runner will use the number of workers specified in the input file under the runner section.

Parameters:

tdb – the AMS database

Raises:

Error if the runner fails –

check_exit_splitting_loop(tdb: pyrevs.database.Database, k: int) → tuple[bool, numpy.typing.NDArray[numpy.number]]

Check for exit criterion of the splitting loop.

Parameters:

• tdb – the AMS database

• k – loop counter

Returns:

bool to trigger splitting loop break array of maximas across all trajectories

finish_ongoing_splitting(tdb: pyrevs.database.Database) → None

Check and finish unfinished splitting iterations.

If the run was interrupted during a splitting iteration, the branched trajectories might not have terminated yet. In that case, a list of trajectories to finish is listed in the database.

get_restart_at_random(tdb: pyrevs.database.Database, min_idx_list: list[int]) → list[int]

Get a list of trajectory index to restart from at random.

Select trajectories to restart from among the ones not in min_idx_list.

Parameters:

• tdb – the AMS database

• min_idx_list – list of trajectory index to restart from

Returns:

list of trajectory index to restart from

do_multilevel_splitting(tdb: pyrevs.database.Database, plot_diags: bool) → None

Schedule splitting of the initial ensemble of stochastic trajectories.

Perform the multi-level splitting iterations, possibly restarting multiple trajectories at each iterations. All the trajectories in an iterations are advanced together, such that each iteration takes the maximum duration among the branched trajectories.

If the walltime is exceeded, the splitting loop is stopped and ongoing trajectories are flagged in the database in order to finish them upon restart.

The runner will use the number of workers specified in the input file under the runner section.

Parameters:

• tdb – the AMS database

• plot_diags – whether or not to plot diagnostics

Raises:

Error if the runner fails –

compute_probability(tdb: pyrevs.database.Database, plot_diags: bool) → float

Compute the probability using AMS.

Parameters:

• tdb – the AMS database

• plot_diags – whether or not to plot diagnostics

Returns:

the rare-event probability

initialize_database_schema(database: pyrevs.database.Database, diag_configs: dict[str, pyrevs.core.Config] | None) → None

Initialize database core state.

class AMSConfig

AMS strategy configuration.

ntrajectories: int = -1

nsplititer: int = -1

variant: str = 'tams'

l_j: int = 1

init_ensemble_only: bool = False

end_time: float = -1.0

min_score: float | None = None

validate() → None

Validate AMS configuration.

class AMSDatabaseExtension

Bases: pyrevs.database.StrategyDatabaseExtension

An extension class for the AMS strategy.

Variables:

• _nsplitting – maximum number of splitting iterations

• _ams_db – an instance of AMSDB, extending the SQL database

initialize(nsplitting: int, tdb: pyrevs.database.Database) → None

Initialize the AMS database extension.

Parameters:

• nsplitting – maximum number of splitting iterations

• tdb – the core trajectory database

initialize_from_database(tdb: pyrevs.database.Database) → None

Initialize the AMS database extension.

Parameters:

tdb – the core trajectory database

serialize() → None

Serialize the extension.

deserialize() → None

Serialize the extension.

k_split() → int

Get the current splitting iteration index.

The current splitting iteration index is equal to the ksplit + bias (number of branching event in the last iteration) entries of last entry in the SQL db table

Returns:

Internal splitting iteration index

init_ensemble_done() → bool

Get the initial ensemble status flag.

Returns:

the flag indicating that the initial ensemble is finished

set_init_ensemble_flag(status: bool) → None

Change the initial ensemble status flag.

Parameters:

status – the new status

get_ongoing() → list[int] | None

Get the list of ongoing trajectories if any.

Returns:

Either a list trajectories or None if nothing was left to do

weights() → numpy.typing.NDArray[numpy.number]

Splitting iterations weights.

mark_last_splitting_iteration_as_done() → None

Flag the last splitting iteration as done.

append_splitting_iteration_data(ksplit: int, bias: int, discarded_ids: list[int], ancestor_ids: list[int], min_vals: list[float], min_max: list[float]) → None

Append a set of splitting data to internal list.

Parameters:

• ksplit – The splitting iteration index

• bias – The number of restarted trajectories, also ref. to as bias

• discarded_ids – The list of discarded trajectory ids

• ancestor_ids – The list of trajectories used to restart (ancestors)

• min_vals – The list of minimum values

• min_max – The score minimum and maximum values

Raises:

ValueError if the provided ksplit is incompatible with the db state –

update_splitting_iteration_data(ksplit: int, bias: int, discarded_ids: list[int], ancestor_ids: list[int], min_vals: list[float], min_max: list[float]) → None

Update the last set of splitting data to internal list.

Parameters:

• ksplit – The splitting iteration index

• bias – The number of restarted trajectories, also ref. to as bias

• discarded_ids – The list of discarded trajectory ids

• ancestor_ids – The list of trajectories used to restart (ancestors)

• min_vals – The list of minimum values

• min_max – The score minimum and maximum values

Raises:

ValueError if the provided ksplit is incompatible with the db state –

update_trajectories_weights() → None

Update the weights of all the trajectories.

Using the the current splitting iteration weight.

get_event_probability() → float

Return the event probability.

plot_min_max_span(fname: str | None = None) → None

Plot the evolution of the ensemble min/max during iterations.

get_trajectory_active_at_k(k_in: int) → list[pyrevs.trajectory.Trajectory[T_Noise, T_State]]

Return the list of trajectory active at a given splitting iteration.

To explore the ensemble evolution during splitting iterations, it is useful to reconstruct the list of active trajectories at the beginning of any given splitting iteration.

Note that k here is not the splitting index, but the iteration index. Since more than one child can be spawned at each splitting iteration, the two might differ.

Parameters:

k_in – the index of the splitting iteration

Returns:

The list of trajectories active at the beginning of iteration k

load_database_extension(tdb: pyrevs.database.Database) → extension.AMSDatabaseExtension

A factory function to instanciate the extension from the database.