Solvers#

The package contains several solvers for rare event estimation problems. If you initialize a solver object, you can specify some options which are described here.

class rareeventestimation.CBREE(stepsize_tolerance=0.5, t_step=-1, num_steps=100, tgt_fun='algebraic', observation_window=5, seed=None, sigma_adaptivity='cvar', beta_adaptivity=True, cvar_tgt=2, sfp_tgt=0.3333333333333333, ess_tgt=0.5, lip_sigma=1, divergence_check=True, convergence_check=True, mixture_model='GM', resample=False, verbose=False, save_history=False, return_other=False, return_caches=False, name=None, callback=None)#

Instances of this class hold all the options for consensus based sampling.

Set solver options in the constructor. Use method solve to apply consensus based sampling to a problem.

The constructor can handle the following keyword arguments.

Parameters:

  • stepsize_tolerance (float, optional) – Tolerance for updating t_step. Defaults to 0.5.

  • t_step (float, optional) – Set to a positive number to set a constant

  • -1. (stepssize. Otherwise choose stepsize adaptively. Defaults to) –

  • num_steps (int, optional) – Maximal number of steps. Defaults to 100.

  • tgt_fun (str, optional) –

    Which smoothing function should be used. Can be one of:

    • ”algebraic”

    • ”tanh”

    • ”arctan”

    • ”erf”

    • ”relu”

    • ”sigmoid”

    Defaults to “algebraic” if not provided or not set to one of the above.

  • observation_window (int|Real, optional) – How many steps should be considered for the divergence check

  • 5. (and the average failure estimates. Defaults to) –

  • seed (int, optional) – Seed for the random number generator. Defaults to None.

  • sigma_adaptivity (str|Real, optional) –

    Method of updating sigma. Can be one of:

    • ”cvar”: Update sigma based of coefficient of variation of importance sampling weights.

    • ”sfp”: Update sigma based on share of failure particles.

    • positive number: sigma is constant to this value.

    Defaults to “cvar”.

  • beta_adaptivity (bool|Real, optional) –

    Whether to update the temperature beta Can be one of:

    • True

    • positive number: Temperature is constant to this value.

    Defaults to True

  • cvar_tgt (Real, optional) – Stop if coefficient of variation is smaller than this and sigma_adaptivity==”cvar”. Is also used for updating sigma if sigma_adaptivity==”cvar”. Defaults to 2.

  • sfp_tgt (Real, optional) – Stop if share of failure particles is greater than this and sigma_adaptivity==”sfp”. Is also used for updating sigma if sigma_adaptivity==”sfp” or if sigma_adaptivity==”cvar”` and share of failure particles is smaller sfp_tgt Defaults to 1/3.

  • ess_tgt (Real, optional) – Target for relative effective sample size used to update temperature beta. Defaults to 1/2.

  • lip_sigma (Real, optional) – Limits increase of sigma by -lip_sigma*log(t_step). Defaults to 1.

  • divergence_check (bool, optional) – Whether to check for divergence by looking at the last observation_window iterations. Defaults to True.

  • convergence_check (bool, optional) – Whether to check for convergence by looking at the last ensemble. Defaults to True.

  • mixture_model (str, optional) –

    Which model is used to for resampling. Defaults to “GM”. Can be one of:

    • ”GM”

    • ”vMFNM”

  • resample (bool, optional) – Whether to resample each iteration using the density specified by mixture_model. Defaults to False.

  • verbose (bool, optional) – Whether to print information during solving. Defaults to False.

  • save_history (bool, optional) – Whether to return information of all iterations. Defaults to False.

  • return_other (bool, optional) –

    Whether to return additional information as a dictionary in the attribute other of the solution. Defaults to False. The dictionary contains among other the keys the averaged estimates based on the last observation_window previous iterations:

    • ”Average Estimate”: Uniform average of the observation_window last estimates. (best)

    • ”Root Weighted Average Estimate”: Weighted average of the observation_window last estimates. Weights decay proportional to sqrt(final_iteration - iteration). (good default choice)

    • ”VAR Weighted Average Estimate”: Weighted Average Estimate”: Weighted average of the observation_window last estimates. Weights are proportional to the inverse of the estimates coefficient of variation. (unstable)

  • return_caches (bool, optional) – Whether to return a list of the caches. Defaults to False. Mainly for debugging and more intricate testing.

  • name (str, optional) – Name of the solver. Defaults to “CBREE”.

  • callback (Callable, optional) – Apply this function to the current CBREECache after each iteration. Defaults to None.

class rareeventestimation.SIS(**kwargs)#

This class is a wrapper for code from the Engineering Risk Analysis Group, TU Munich. Please consult the credits section of the package’s readme file.

The constructor can handle the following keyword arguments.

Parameters:

  • num_chains_wrt_sample – Use `num_chains_wrt_sample`*sample-size number of chains for the MCMC routine.

  • burn_in – burn-in period for MCMC routine.

  • cvar_tgt (Real, optional) – Stop if coefficient of variation is smaller than this. Defaults to 1.

  • mixture_model (str, optional) –

    Which method is used to for resampling. Defaults to “GM”. Can be one of:

    • ”GM”

    • ”aCS”

    • ”vMFNM”

  • num_comps – Number of components for multimodal problems. Defaults to 1.

  • seed (int, optional) – Seed for the random number generator. Defaults to None.

  • fixed_initial_sample (bool) – Whether to use the initial sample provided by prob in solve. Defaults to True.

  • verbose (bool, optional) – Whether to print information during solving. Defaults to False.

  • return_other (bool, optional) – Whether to return the final number of components and coefficient of variation of the weights.

class rareeventestimation.ENKF(**kwargs)#

This class is a wrapper for code from Fabian Wagner. Please consult the credits section of the package’s readme file.

The constructor can handle the following keyword arguments.

Parameters:

  • cvar_tgt – Stop if coefficient of variation is smaller than this, Defaults to 1.

  • mixture_model –

    Which model is used to for resampling. Defaults to “GM”. Can be one of:

    • ”GM”

    • ”vMFNM”

  • num_steps – Maximal number of steps. Defaults to 100.

  • num_comps – Number of components for multimodal problems. Defaults to 1.

  • localize – Whether to use local covariances.

  • seed – Seed for the random number generator. Defaults to None.

class rareeventestimation.CMC(num_runs: int, seed: int | None = None, verbose=True)#

Crude Monte Carlo simulation.

The constructor can handle the following keyword arguments.

Parameters:

  • num_runs (int) – How often to sample from the problems distribution.

  • seed (int, optional) – Seed for sampling from the problems distribution. Defaults to None.

  • verbose (bool, optional) – Whether to print information during solving. Defaults to True.