Package: rareeventestimation
rareeventestimationEstimate rare events with consensus-based sampling and other methods.Installation$pipinstallrareeventestimationIntroduction and UsageIn reliability analysis, it is often crucial to estimate the probability of failure of a system.For a $d$-dimensional system the notion of failure is encoded in a limit state function (LSF) $G:\mathbb{R}^d \rightarrow \mathbb{R}$, which maps safe states to positive values and failure states to values of at most $0$.If the states follow some distribution that has with respect to the Lebesgue measure on $\mathbb{R}^d$ the density $\pi$,
then the probability of failure $P_f$ is defined as the probability mass of all failure states.
Namely, $P_f =\int_{G\leq 0}\pi(x)dx$.By construction the probability of failure is small and additionally, the evaluation of the limit state function is often computationally expensive.
This package contains algorithm for the numerical estimation of $P_f$.
Here is an example with the standard assumption $\pi \sim \mathcal{N}(0,I_d)$:importrareeventestimationasreefromnumpyimportndarray,sum,sqrt# define problem with normal distribution:# lsf does not need to be vectorizeddefmy_lsf(x:ndarray)->ndarray:"""Affine limit state functionArgs:x: Numpy array. Last axis is the problems dimension.Returns:Evaluation of LSF in `x` as a numpy array of shape `x.shape[0:-2]`."""return-sum(x,axis=-1)/sqrt(x.shape[-1])+3.5prob_dim=4# specify or write down the problem dimensionsample_size=2000# specify size of initial sampleproblem=ree.NormalProblem(my_lsf,prob_dim,sample_size)# initialize solver with all options, here CBREE with default values:solver=ree.CBREE()# estimate failure probability:solution=solver.solve(problem)print(solution.prob_fail_hist[-1])# print estimate of last (=best) iterationFeaturesImplementation of the Consensus-Based Rare Event EstimationInterface and implementation for other rare event estimations methods:Sequential Importance Sampling[1],Ensemble Kalman Filter for Rare Event Estimation[3],Multilevel Sequential² Monte Carlo for Rare Event Estimation[2],Numerical studies of all methodsAboutThis package was developed during my master's thesis and the publication of a paper about a new method for rare event estimation (the CBREE method).
Therefore this package contains multiple notebooks which produce the figures used in those two publications.If you want to reproduce the figures of the paperK. Althaus I. Papaioannou, and E. Ullmann, Consensus-based rare event estimation, (2023),https://doi.org/10.48550/arXiv.2304.09077,
use the notebooks indocs/figures_paper.ContentHere is an incomplete overview of the folder structure of the package.If you are here to reproduce figures from the literature, the tree will point you to the right directory.
If you run a notebook in one of thefigures_*folders,
the underlying precomputed data is downloaded fromarchive.org.
The data is encoded as.jsonfiles and you can have look at those online before loading them.Of course you can also compute the data yourself using the
the scripts indocs/benchmarking-scripts.
These scripts populate the the emptydocs/datadirectory.
Then you can compile the data indocs/datawith the notebooks (uncomment the respective code block) to produce the datasets that are also available online.Furthermore, you see in the tree below several folders with code I  have not written myself.
These folders contain various benchmark methods.
The result of these benchmarks  can be found in thefigures_*folders and are interpreted in the literature.├── dist
├── docs
│   ├── benchmarking
│   │   ├── benchmarking-scripts # scripts to fill data folder
│   │   └── data # empty
│   ├── figures_paper # make figures from paper
│   └── figures_thesis # make figures from thesis
├── src
│   └── rareeventestimation
│       ├── enkf # enkf solver, cf. credits
│       ├── era # subroutines, cf. credits
│       ├── evaluation # code for figures
│       ├── mls2mc # mls2mc solver, cf. credits
│       ├── problem # code to define problems
│       └── sis # sis solver, cf. credits
└── testCreditsThis package contains code I have not written myself.Code from the Engineering Risk Analysis Group, Technical University of MunichAll files inrareeventestimation/src/eraandrareeventestimation/src/sisare
written by theERA Groupand
licensed under the MIT license. I have added minor changes.Code from Dr. Fabian WagnerAll files inrareeventestimation/src/enkf,rareeventestimation/src/mls2mcandsrc/rareeventestimation/problem/diffusion.pyare written byDr. Fabian Wagner. I have added minor changes.StackoverflowI have used several snippets from the almighty community onstackoverflow.rareeventestimationwas created withcookiecutterand thepy-pkgs-cookiecuttertemplate.Licenserareeventestimationwas created by Konstantin Althaus. It is licensed under the terms of the MIT license.References[1]I. Papaioannou, C. Papadimitriou, and D. Straub, Sequential importance sampling for structural reliability analysis, Structural Safety, 62 (2016), pp. 66–75,https://doi.org/10.1016/j.strusafe.2016.06.002.[2]F. Wagner, J. Latz, I. Papaioannou, and E. Ullmann, Multilevel Sequential Importance Sampling for Rare Event Estimation, SIAM Journal on Scientific Computing, 49 (2020), pp. A2062-A2087,https://doi.org/10.1137/19M1289601[3]F. Wagner, I. Papaioannou, and E. Ullmann, The ensemble kalman ﬁlter for rare event estimation, SIAM/ASA Journal on Uncertainty Quantiﬁcation, 10 (2022), pp. 317–349,https://doi.org/10.1137/21m1404119.