pyrevs.strategies.ams ===================== .. py:module:: pyrevs.strategies.ams Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/pyrevs/strategies/ams/ams/index /autoapi/pyrevs/strategies/ams/config/index /autoapi/pyrevs/strategies/ams/extension/index /autoapi/pyrevs/strategies/ams/sql/index Classes ------- .. autoapisummary:: pyrevs.strategies.ams.AMS pyrevs.strategies.ams.AMSConfig pyrevs.strategies.ams.AMSDatabaseExtension Functions --------- .. autoapisummary:: pyrevs.strategies.ams.load_database_extension Package Contents ---------------- .. py: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: :py:obj:`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. :ivar _fmodel_t: the forward model type :ivar _config: the config object :ivar _wallTime: the walltime limit :ivar _init_ensemble_only: whether or not to stop after initializing the trajectory ensemble .. py:method:: 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. :param tdb: the AMS database :raises Error if the runner fails: .. py:method:: 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. :param tdb: the AMS database :param k: loop counter :returns: bool to trigger splitting loop break array of maximas across all trajectories .. py:method:: 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. .. py:method:: 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. :param tdb: the AMS database :param min_idx_list: list of trajectory index to restart from :returns: list of trajectory index to restart from .. py:method:: 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. :param tdb: the AMS database :param plot_diags: whether or not to plot diagnostics :raises Error if the runner fails: .. py:method:: compute_probability(tdb: pyrevs.database.Database, plot_diags: bool) -> float Compute the probability using AMS. :param tdb: the AMS database :param plot_diags: whether or not to plot diagnostics :returns: the rare-event probability .. py:method:: initialize_database_schema(database: pyrevs.database.Database, diag_configs: dict[str, pyrevs.core.Config] | None) -> None Initialize database core state. .. py:class:: AMSConfig AMS strategy configuration. .. py:attribute:: ntrajectories :type: int :value: -1 .. py:attribute:: nsplititer :type: int :value: -1 .. py:attribute:: variant :type: str :value: 'tams' .. py:attribute:: l_j :type: int :value: 1 .. py:attribute:: init_ensemble_only :type: bool :value: False .. py:attribute:: end_time :type: float :value: -1.0 .. py:attribute:: min_score :type: float | None :value: None .. py:method:: validate() -> None Validate AMS configuration. .. py:class:: AMSDatabaseExtension Bases: :py:obj:`pyrevs.database.StrategyDatabaseExtension` An extension class for the AMS strategy. :ivar _nsplitting: maximum number of splitting iterations :ivar _ams_db: an instance of AMSDB, extending the SQL database .. py:method:: initialize(nsplitting: int, tdb: pyrevs.database.Database) -> None Initialize the AMS database extension. :param nsplitting: maximum number of splitting iterations :param tdb: the core trajectory database .. py:method:: initialize_from_database(tdb: pyrevs.database.Database) -> None Initialize the AMS database extension. :param tdb: the core trajectory database .. py:method:: serialize() -> None Serialize the extension. .. py:method:: deserialize() -> None Serialize the extension. .. py:method:: 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 .. py:method:: init_ensemble_done() -> bool Get the initial ensemble status flag. :returns: the flag indicating that the initial ensemble is finished .. py:method:: set_init_ensemble_flag(status: bool) -> None Change the initial ensemble status flag. :param status: the new status .. py:method:: 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 .. py:method:: weights() -> numpy.typing.NDArray[numpy.number] Splitting iterations weights. .. py:method:: mark_last_splitting_iteration_as_done() -> None Flag the last splitting iteration as done. .. py:method:: 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. :param ksplit: The splitting iteration index :param bias: The number of restarted trajectories, also ref. to as bias :param discarded_ids: The list of discarded trajectory ids :param ancestor_ids: The list of trajectories used to restart (ancestors) :param min_vals: The list of minimum values :param min_max: The score minimum and maximum values :raises ValueError if the provided ksplit is incompatible with the db state: .. py:method:: 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. :param ksplit: The splitting iteration index :param bias: The number of restarted trajectories, also ref. to as bias :param discarded_ids: The list of discarded trajectory ids :param ancestor_ids: The list of trajectories used to restart (ancestors) :param min_vals: The list of minimum values :param min_max: The score minimum and maximum values :raises ValueError if the provided ksplit is incompatible with the db state: .. py:method:: update_trajectories_weights() -> None Update the weights of all the trajectories. Using the the current splitting iteration weight. .. py:method:: get_event_probability() -> float Return the event probability. .. py:method:: plot_min_max_span(fname: str | None = None) -> None Plot the evolution of the ensemble min/max during iterations. .. py:method:: 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. :param k_in: the index of the splitting iteration :returns: The list of trajectories active at the beginning of iteration k .. py:function:: load_database_extension(tdb: pyrevs.database.Database) -> extension.AMSDatabaseExtension A factory function to instanciate the extension from the database.