LineSampling¶

class LineSampling(*args)¶

Line sampling algorithm.

Warning

This class is experimental and likely to be modified in future releases. To use it, import the openturns.experimental submodule.

This class implements the line sampling algorithm from [koutsourelakis2004] with adaptation of the important direction from [angelis2015], which is also known as adaptive line sampling.

Let $\inputRV$ be a random vector of dimension $\inputDim$ , distributed according to the measure $\inputMeasure$ , and $\model: \Rset^\inputDim \rightarrow \Rset$ be the limit state function (where we only write the random input parameters). We define the event $\cD_f$ by:

$\cD_f = \{\vect{x} \in \Rset^{\inputDim} \, | \,\model(\vect{x}) \leq 0\}$

The line sampling algorithm estimates the probability of the event $\cD_f$ :

$P_f = \Prob{\model\left( \inputRV \right) \leq 0} = \int_{\Rset^{\inputDim}} \mathbf{1}_{\{\model(\vect{x}) \leq 0 \}}\inputMeasure(\vect{x})\di{\vect{x}}$

Let $T$ be the iso-probabilistic transformation to the standard space: $T(\vect{X}) = \vect{Z}$ . The random vector $\vect{Z}$ is a $\inputDim$ -dimensional Gaussian vector following the standard normal distribution.

For any direction $\vect{\alpha} \in \Rset^d$ such that $||\vect{\alpha}||_2=1$ , let $P_{\vect{\alpha}}$ be the orthogonal projection from $\Rset^d$ to the one-dimensional vector space (line) spanned by $\vect{\alpha}$ (we call $\vect{\alpha}$ the important direction) and let $P^{\perp}_{\vect{\alpha}}$ be the orthogonal projection from $\Rset^d$ to the hyperplane of $\Rset^d$ normal to the one-dimensional vector space spanned by $\vect{\alpha}$ .

Then $P_f$ can be rewritten:

$P_f = \Expect{\Prob{P_{\vect{\alpha}}(\vect{Z}) + P^{\perp}_{\vect{\alpha}}(\vect{Z}) \in T(\cD_f) | P^{\perp}_{\vect{\alpha}}(\vect{Z})}}$

Since $\vect{Z}$ follows a standard multivariate normal distribution, $P_{\vect{\alpha}}(\vect{Z})$ and $P^{\perp}_{\vect{\alpha}}(\vect{Z})$ are independent.

Therefore, given that $P_{\vect{\alpha}}(\vect{Z})$ follows the same distribution as $R \vect{\alpha}$ where $R$ is a scalar random variable following the standard normal distribution, we have:

$P_f = \Expect{\Prob{R \vect{\alpha} + P^{\perp}_{\vect{\alpha}}(\vect{Z}) \in T(\cD_f) | P^{\perp}_{\vect{\alpha}}(\vect{Z})}}$

Now, for any vector $\vect{u} \in \Rset^d$ that is orthogonal to $\vect{\alpha}$ , we define $I_u$ as the set

$I_u = \{ r \in \Rset, r \vect{\alpha} + u \in T(\cD_f) \}$

We can rewrite

$P_f = \Expect{\Prob{R \in I_{P_{\vect{\alpha}}(\vect{Z})} | P^{\perp}_{\vect{\alpha}}(\vect{Z}}}$

Letting $I_u^0$ be the interior of $I_u$ , we assume $I_u^0$ to be the union of a finite number of open intervals.

Then there exists $n_u \in \Nset$ and $r_0, \hdots, r_{2 n_u + 1} \in \Rset \cup \{-\infty, +\infty\}$ such that $r_0 < \hdots < r_{2 n_u + 1}$ and $I_u^0 = \bigcup_{i=0}^{n_u} (r_{2i}, r_{2i+1})$ .

$r_0$ is either $-\infty$ or a root of $r \mapsto g \circ T^{-1}(r \vect{\alpha} + u)$ . $r_{2 n_u + 1}$ is either $+\infty$ or a root of $r \mapsto g \circ T^{-1}(r \vect{\alpha} + u)$ . All the other $r_j$ are roots of $r \mapsto g \circ T^{-1}(r \vect{\alpha} + u)$ .

With $\Phi$ denoting the CDF of the standard normal distribution we have

$\Prob{R \in I_u} = \Prob{I_u^0} = \sum_{i=0}^{n_u} \Prob{r_{2 i} < R < r_{2 i + 1}} \\ = \sum_{i=0}^{n_u} \Prob{R < r_{2 i + 1}} - \Prob{R \leq r_{2 i}} \\ = \sum_{0 < i < 2 n_u + 1} (-1)^{j+1} \Phi(r_j)$

The generic line sampling algorithm follows the steps for $k=1, \hdots \sampleSize$ :

Draw a sample $\vect{z_k} \sim Z$ and project it on the hyperplane normal to $\vect{\alpha}$ to obtain $P^{\perp}_{\vect{\alpha}}(\vect{z_k})$ .
Find the roots of $r \mapsto g \circ T^{-1}(r \vect{\alpha} + P^{\perp}_{\vect{\alpha}}(\vect{z_k}))$ .
Use the roots to compute $p_{\vect{z_k}} = \Prob{R \in I_{P^{\perp}_{\vect{\alpha}}(\vect{z_k})}}$ .

The global probability $P_f$ is computed from all the $p_{\vect{z_k}}$ probabilities.

$\widehat{P}_{f,LS} = \frac{1}{\sampleSize} \sum_{i=1}^{\sampleSize} p_{\vect{z_k}}$

The adaptive variant of the algorithm consists in updating the important direction $\vect{\alpha}$ by the selecting the direction given by the nearest intersection with the frontiers of $\cD_f$ from the origin as given by the root search for each new line explored.

Parameters:

eventRandomVector: Event we are computing the probability.
initialAlphasequence of float: The initial important direction $\vect{\alpha}$ .
rootStrategyRootStrategy, optional: Strategy used to evaluate the frontiers of the event along each direction in the standard space. By default SafeAndSlow.

Methods

`drawProbabilityConvergence`(*args)	Draw the probability convergence at a given level.
`getAdaptiveImportantDirection`()	Accessor to the adaptive important direction flag.
`getAlphaHistory`()	Accessor to the important direction history.
`getBlockSize`()	Accessor to the block size.
`getClassName`()	Accessor to the object's name.
`getConvergenceStrategy`()	Accessor to the convergence strategy.
`getEvent`()	Accessor to the event.
`getInitialAlpha`()	Initial important direction accessor.
`getMaximumCoefficientOfVariation`()	Accessor to the maximum coefficient of variation.
`getMaximumOuterSampling`()	Accessor to the maximum iterations number.
`getMaximumStandardDeviation`()	Accessor to the maximum standard deviation.
`getMaximumTimeDuration`()	Accessor to the maximum duration.
`getName`()	Accessor to the object's name.
`getResult`()	Accessor to the results.
`getRootPointsHistory`()	Accessor to the root points history.
`getRootStrategy`()	Get the root strategy.
`getRootValuesHistory`()	Accessor to the root values history.
`getSearchOppositeDirection`()	Opposite direction search flag accessor.
`getStoreHistory`()	Accessor to the important direction history.
`hasName`()	Test if the object is named.
`run`()	Launch simulation.
`setAdaptiveImportantDirection`(...)	Accessor to the adaptive important direction flag.
`setBlockSize`(blockSize)	Accessor to the block size.
`setConvergenceStrategy`(convergenceStrategy)	Accessor to the convergence strategy.
`setInitialAlpha`(initialAlpha)	Initial important direction accessor.
`setMaximumCoefficientOfVariation`(...)	Accessor to the maximum coefficient of variation.
`setMaximumOuterSampling`(maximumOuterSampling)	Accessor to the maximum iterations number.
`setMaximumStandardDeviation`(...)	Accessor to the maximum standard deviation.
`setMaximumTimeDuration`(maximumTimeDuration)	Accessor to the maximum duration.
`setName`(name)	Accessor to the object's name.
`setProgressCallback`(*args)	Set up a progress callback.
`setRootStrategy`(rootStrategy)	Set the root strategy.
`setSearchOppositeDirection`(...)	Opposite direction search flag accessor.
`setStopCallback`(*args)	Set up a stop callback.
`setStoreHistory`(storeHistory)	Accessor to the important direction history.

See also

openturns.EventSimulation.setBlockSize
openturns.EventSimulation.setMaximumOuterSampling
openturns.ResourceMap
openturns.SimulationResult

Notes

It launches the simulation and creates a SimulationResult, structure containing all the results obtained after simulation. It computes the probability of occurrence of the given event by computing the empirical mean of a sample of size at most outerSampling * blockSize, this sample being built by blocks of size blockSize. It allows one to use efficiently the distribution of the computation as well as it allows one to deal with a sample size $> 2^{32}$ by a combination of blockSize and outerSampling.

setAdaptiveImportantDirection(adaptiveImportantDirection)¶

Accessor to the adaptive important direction flag.

Parameters:

adaptiveImportantDirectionbool: Whether the important direction is adapted according to new design points.

setBlockSize(blockSize)¶

Accessor to the block size.

Parameters:

blockSizeint, $blockSize \geq 1$: Number of simultaneous evaluations of the limit-state function. It is set by default to 1.

Notes

If the function supports batch evaluations this parameter can be set to the number of available CPUs to benefit from parallel execution (multithreading, multiprocessing, …); except for the Directional Sampling, where we recommend to set it to 1. It also decides the frequency of the stopping criteria and progress callbacks update as they are called once the whole block of fonction evaluations is completed.

setConvergenceStrategy(convergenceStrategy)¶

Accessor to the convergence strategy.

Parameters:

storage_strategyHistoryStrategy: Storage strategy used to store the values of the probability estimator and its variance during the simulation algorithm.

setInitialAlpha(initialAlpha)¶

Initial important direction accessor.

Parameters:

alphasequence of float: Initial important direction.

setMaximumCoefficientOfVariation(maximumCoefficientOfVariation)¶

Accessor to the maximum coefficient of variation.

Parameters:

coefficientfloat: Maximum coefficient of variation of the simulated sample.

setMaximumOuterSampling(maximumOuterSampling)¶

Accessor to the maximum iterations number.

Parameters:

outerSamplingint: Maximum number of iterations, each iteration performing a block of evaluations.

setMaximumStandardDeviation(maximumStandardDeviation)¶

Accessor to the maximum standard deviation.

Parameters:

sigmafloat, $\sigma > 0$: Maximum standard deviation of the estimator.

setMaximumTimeDuration(maximumTimeDuration)¶

Accessor to the maximum duration.

Parameters:

maximumTimeDurationfloat: Maximum optimization duration in seconds.

setName(name)¶

Accessor to the object’s name.

Parameters:

namestr: The name of the object.

setProgressCallback(*args)¶

Set up a progress callback.

Can be used to programmatically report the progress of a simulation.

Parameters:

callbackcallable: Takes a float as argument as percentage of progress.

Examples

>>> import sys
>>> import openturns as ot
>>> experiment = ot.MonteCarloExperiment()
>>> X = ot.RandomVector(ot.Normal())
>>> Y = ot.CompositeRandomVector(ot.SymbolicFunction(['X'], ['1.1*X']), X)
>>> event = ot.ThresholdEvent(Y, ot.Less(), -2.0)
>>> algo = ot.ProbabilitySimulationAlgorithm(event, experiment)
>>> algo.setMaximumOuterSampling(100)
>>> algo.setMaximumCoefficientOfVariation(-1.0)
>>> def report_progress(progress):
...     sys.stderr.write('-- progress=' + str(progress) + '%\n')
>>> algo.setProgressCallback(report_progress)
>>> algo.run()

setRootStrategy(rootStrategy)¶

Set the root strategy.

Parameters:

strategyRootStrategy: Root strategy to evaluate the frontiers of the event along each direction in the standard space.

setSearchOppositeDirection(searchOppositeDirection)¶

Opposite direction search flag accessor.

Parameters:

searchOppositeDirectionbool: Whether to search in the opposite direction of the important direction.

setStopCallback(*args)¶

Set up a stop callback.

Can be used to programmatically stop a simulation.

Parameters:

callbackcallable: Returns an int deciding whether to stop or continue.

setStoreHistory(storeHistory)¶

Accessor to the important direction history.

Parameters:

storeHistorybool: Whether to store alpha, root values and points histories.

Examples using the class¶

Estimate a probability using Line Sampling

OpenTURNS

An Open source initiative for the Treatment of Uncertainties, Risks'N Statistics

Table of Contents

Previous topic

Next topic

This Page

LineSampling¶

Examples using the class¶