RatioOfUniforms¶
(Source code
, svg
)
- class RatioOfUniforms(*args)¶
Ratio of Uniforms simulation algorithm.
Warning
This class is experimental and likely to be modified in future releases. To use it, import the
openturns.experimental
submodule.- Available constructors:
RatioOfUniforms(dist)
RatioOfUniforms(logUnscaledF, rangeF, isScaled)
- Parameters:
- dist
Distribution
Distribution to sample.
With that constructor, the range is the distribution range and isScaled = True.
- logUnscaledPDF
Function
Function
such that
is proportional to the PDF
we want to sample.
- rangeF
Interval
Interval
outside which
.
- isScaledbool, optional
Flag telling if the input logUnscaledPDF is such that
is an actual PDF of a distribution.
Default value is False.
- dist
Methods
If the random vector can be viewed as the composition of several
ThresholdEvent
objects, this method builds and returns the composition.Accessor to the acceptance ratio.
Accessor to the antecedent RandomVector in case of a composite RandomVector.
getC
()Accessor to the
normalization factor.
Accessor to the maximum number of points tested to find admissible starting points.
Accessor to the object's name.
Accessor to the covariance of the RandomVector.
Accessor to the description of the RandomVector.
Accessor to the dimension of the RandomVector.
Accessor to the distribution of the RandomVector.
Accessor to the domain of the Event.
getFrozenRealization
(fixedPoint)Compute realizations of the RandomVector.
getFrozenSample
(fixedSample)Compute realizations of the RandomVector.
Accessor to the Function in case of a composite RandomVector.
getInfV
()Accessor to the
-lower bound of
.
Accessor to the function
.
getMarginal
(*args)Get the random vector corresponding to the
marginal component(s).
Accessor to the maximum number of starting points for the multistart algorithm.
getMean
()Accessor to the mean of the RandomVector.
getName
()Accessor to the object's name.
Accessor to the comparaison operator of the Event.
Accessor to the optimization algorithm.
Accessor to the parameter of the distribution.
Accessor to the parameter description of the distribution.
Get the stochastic process.
getR
()Accessor to the
parameter.
getRange
()Accessor to the interval
where the function
.
Generate a realization.
getSample
(size)Generate a sample.
getSampleWithTryNumber
(size)Sample with number of realizations needed to get it.
getSupU
()Accessor to the
-upper bound of
.
getSupV
()Accessor to the
-upper bound of
.
Accessor to the threshold of the Event.
hasName
()Test if the object is named.
Trigger to the initializationof the class.
Accessor to know if the RandomVector is a composite one.
isEvent
()Whether the random vector is an event.
Flag telling if the algorithm has been initialized.
setCandidateNumber
(candidateNumber)Accessor to the maximum number of points tested to find admissible starting points.
setDescription
(description)Accessor to the description of the RandomVector.
setLogUnscaledPDFAndRange
(logUnscaledPDF, ...)Accessor to the function
and the range
.
setMaximumMultiStart
(maximumMultiStart)Accessor to the maximum number of starting points for the multistart algorithm.
setName
(name)Accessor to the object's name.
setOptimizationAlgorithm
(optimizationAlgorithm)Accessor to the optimization algorithm.
setParameter
(parameters)Accessor to the parameter of the distribution.
setR
(r)Accessor to the
parameter.
Notes
This algorithm samples a multivariate distribution whose probability density probability is known up to a multiplicative factor, see [stadlober1990] for the unidimensional case and [gobet2016] for the multivariate case.
Let
be a probability density function of dimension
and
a function such that:
with
. We can write
as:
with
. It implies that the numerical range of
is inluced in
. We note:
If the function
is an actual PDF and
its numerical range, then
. In the general case,
is unknown and assumed to be difficult to compute.
Let
. By default,
. Let
be the domain defined by:
The Lebesgue measure of
is equal to
.
Let
be a random variable uniformly distributed on
. Then,
is a random vector distributed according to
.
Under the condition that the functions
and
for all
are bounded, then the domain
is bounded and can be included in a rectangular bounding box
defined by:
(1)¶
This allows one to sample uniformly the set
by rejection sampling inside
.
How to calculate the rectangular bounding box
?
The upper bound
is calculated by maximizing the log of the function rather than the function:
To compute the second part of
, we note that:
If the upper bound
, then:
Otherwise, we solve the maximization problem for
:
which is equivalent to the problem:
If the lower bound
, then:
Otherwise, we solve the minimization problem for
and note that:
which is equivalent to the problem:
For the effective solution of these optimization problems, the initial point
must be such that
. Such points are found by scrolling through a Sobol multivariate low discrepancy sequence: the maximum number of points of the sequence to generate is fixed by the entry RatioOfUniforms-CandidateNumber of
ResourceMap
. The maximum number of points selected as starting points is controlled by the entry RatioOfUniforms-MaximumMultiStart. All the optimization problems are solved using aMultiStart
algorithm based on these selected starting points. When no point has been selected, an exception is sent.The acceptance ratio of the rejection algorithm is defined by:
(2)¶
It is computed by the initialize method: if
, the rate is computed by (2). If not, it is estimated as (3).
This class uses the following entries of
ResourceMap
:RatioOfUniforms-OptimizationAlgorithm: the optimization algorithm used to compute the bounding box of
,
RatioOfUniforms-CandidateNumber: maximum number of points of the Sobol low discrepancy sequence of dimension
used to find admissible starting points,
RatioOfUniforms-MaximumMultiStart: maximum number of points selected as starting points for the multistart optimization algorithm,
RatioOfUniforms-NormalizationSampleSize: size of the sample used to estimate the acceptance ratio.
Examples
Create a ratio of uniforms algorithm and get the multistart optimization problems used to compute the bounds of
:
>>> import openturns as ot >>> import openturns.experimental as otexp >>> from math import pi >>> f = ot.SymbolicFunction('x', '(1.5+sin(x))*exp(x)') >>> log_UnscaledPDF = ot.ComposedFunction(ot.SymbolicFunction('x', 'log(x)'), f) >>> range_PDF = ot.Interval(0.0, 2.0 * pi) >>> ratioOfU = otexp.RatioOfUniforms(log_UnscaledPDF, range_PDF, False) >>> collMultiStart = ratioOfU.initialize() >>> x = ratioOfU.getRealization() >>> sample = ratioOfU.getSample(10) >>> ratioOfU = otexp.RatioOfUniforms(ot.Student(8.5, 3))
- __init__(*args)¶
- asComposedEvent()¶
If the random vector can be viewed as the composition of several
ThresholdEvent
objects, this method builds and returns the composition. Otherwise throws.- Returns:
- composed
RandomVector
Composed event.
- composed
- getAcceptanceRatio()¶
Accessor to the acceptance ratio.
- Returns:
- accepRatiofloat,
,
Acceptance ratio
.
- accepRatiofloat,
Notes
The acceptance ratio is computed at the initialization of the class by the ethod initialize, according to (2) where
if the class has been created with a log-PDF and estimated by (3) in the other case.
- getAntecedent()¶
Accessor to the antecedent RandomVector in case of a composite RandomVector.
- Returns:
- antecedent
RandomVector
Antecedent RandomVector
in case of a
CompositeRandomVector
such as:.
- antecedent
- getC()¶
Accessor to the
normalization factor.
- Returns:
- cfloat,
,
The
normalization factor.
- cfloat,
Notes
If the class has been created with a scaled function, then
.
If the class has been created with an unscaled function, the acceptance ratio is estimated at the initialization of the class by the method initialize. From
defined in (3), we get an estimate of the normalization factor defined by:
- getCandidateNumber()¶
Accessor to the maximum number of points tested to find admissible starting points.
- Returns:
- nint,
Maximum number of points tested to find admissible points for the optimization algorithm.
- nint,
Notes
As long as the number of selected starting points is less than the number defined in
ResourceMap
, entry RatioOfUniforms-MaximumMultiStart, a new point of the Sobol low discrepancy sequence of dimensionis considered. The maximum points of the Sobol sequence is
. If no starting point has been selected, a warning is sent.
- getClassName()¶
Accessor to the object’s name.
- Returns:
- class_namestr
The object class name (object.__class__.__name__).
- getCovariance()¶
Accessor to the covariance of the RandomVector.
- Returns:
- covariance
CovarianceMatrix
Covariance of the considered
UsualRandomVector
.
- covariance
Examples
>>> import openturns as ot >>> distribution = ot.Normal([0.0, 0.5], [1.0, 1.5], ot.CorrelationMatrix(2)) >>> randomVector = ot.RandomVector(distribution) >>> ot.RandomGenerator.SetSeed(0) >>> print(randomVector.getCovariance()) [[ 1 0 ] [ 0 2.25 ]]
- getDescription()¶
Accessor to the description of the RandomVector.
- Returns:
- description
Description
Describes the components of the RandomVector.
- description
- getDimension()¶
Accessor to the dimension of the RandomVector.
- Returns:
- dimensionpositive int
Dimension of the RandomVector.
- getDistribution()¶
Accessor to the distribution of the RandomVector.
- Returns:
- distribution
Distribution
Distribution of the considered
UsualRandomVector
.
- distribution
Examples
>>> import openturns as ot >>> distribution = ot.Normal([0.0, 0.0], [1.0, 1.0], ot.CorrelationMatrix(2)) >>> randomVector = ot.RandomVector(distribution) >>> ot.RandomGenerator.SetSeed(0) >>> print(randomVector.getDistribution()) Normal(mu = [0,0], sigma = [1,1], R = [[ 1 0 ] [ 0 1 ]])
- getDomain()¶
Accessor to the domain of the Event.
- Returns:
- domain
Domain
Describes the domain of an event.
- domain
- getFrozenRealization(fixedPoint)¶
Compute realizations of the RandomVector.
In the case of a
CompositeRandomVector
or an event of some kind, this method returns the value taken by the random vector if the root cause takes the value given as argument.- Parameters:
- fixedPoint
Point
Point chosen as the root cause of the random vector.
- fixedPoint
- Returns:
- realization
Point
The realization corresponding to the chosen root cause.
- realization
Examples
>>> import openturns as ot >>> distribution = ot.Normal() >>> randomVector = ot.RandomVector(distribution) >>> f = ot.SymbolicFunction('x', 'x') >>> compositeRandomVector = ot.CompositeRandomVector(f, randomVector) >>> event = ot.ThresholdEvent(compositeRandomVector, ot.Less(), 0.0) >>> print(event.getFrozenRealization([0.2])) [0] >>> print(event.getFrozenRealization([-0.1])) [1]
- getFrozenSample(fixedSample)¶
Compute realizations of the RandomVector.
In the case of a
CompositeRandomVector
or an event of some kind, this method returns the different values taken by the random vector when the root cause takes the values given as argument.- Parameters:
- fixedSample
Sample
Sample of root causes of the random vector.
- fixedSample
- Returns:
- sample
Sample
Sample of the realizations corresponding to the chosen root causes.
- sample
Examples
>>> import openturns as ot >>> distribution = ot.Normal() >>> randomVector = ot.RandomVector(distribution) >>> f = ot.SymbolicFunction('x', 'x') >>> compositeRandomVector = ot.CompositeRandomVector(f, randomVector) >>> event = ot.ThresholdEvent(compositeRandomVector, ot.Less(), 0.0) >>> print(event.getFrozenSample([[0.2], [-0.1]])) [ y0 ] 0 : [ 0 ] 1 : [ 1 ]
- getFunction()¶
Accessor to the Function in case of a composite RandomVector.
- Returns:
- function
Function
Function used to define a
CompositeRandomVector
as the image through this function of the antecedent:
.
- function
- getInfV()¶
Accessor to the
-lower bound of
.
Notes
The
-lower bound of
is
.
- getLogUnscaledPDF()¶
Accessor to the function
.
- Returns:
- logUnscaledPDF
Function
, Function
such that
is proportional to the PDF
we want to sample.
- logUnscaledPDF
- getMarginal(*args)¶
Get the random vector corresponding to the
marginal component(s).
- Parameters:
- iint or list of ints,
Indicates the component(s) concerned.
is the dimension of the RandomVector.
- iint or list of ints,
- Returns:
- vector
RandomVector
RandomVector restricted to the concerned components.
- vector
Notes
Let’s note
a random vector and
a set of indices. If
is a
UsualRandomVector
, the subvector is defined by. If
is a
CompositeRandomVector
, defined bywith
,
some scalar functions, the subvector is
.
Examples
>>> import openturns as ot >>> distribution = ot.Normal([0.0, 0.0], [1.0, 1.0], ot.CorrelationMatrix(2)) >>> randomVector = ot.RandomVector(distribution) >>> ot.RandomGenerator.SetSeed(0) >>> print(randomVector.getMarginal(1).getRealization()) [0.608202] >>> print(randomVector.getMarginal(1).getDistribution()) Normal(mu = 0, sigma = 1)
- getMaximumMultiStart()¶
Accessor to the maximum number of starting points for the multistart algorithm.
- Returns:
- nint
Maximum number of starting points for the multistart algorithm.
Notes
A tested point
is a starting point of the multistart algorithm if
.
- getMean()¶
Accessor to the mean of the RandomVector.
- Returns:
- mean
Point
Mean of the considered
UsualRandomVector
.
- mean
Examples
>>> import openturns as ot >>> distribution = ot.Normal([0.0, 0.5], [1.0, 1.5], ot.CorrelationMatrix(2)) >>> randomVector = ot.RandomVector(distribution) >>> ot.RandomGenerator.SetSeed(0) >>> print(randomVector.getMean()) [0,0.5]
- getName()¶
Accessor to the object’s name.
- Returns:
- namestr
The name of the object.
- getOperator()¶
Accessor to the comparaison operator of the Event.
- Returns:
- operator
ComparisonOperator
Comparaison operator used to define the
RandomVector
.
- operator
- getOptimizationAlgorithm()¶
Accessor to the optimization algorithm.
- Returns:
- algo
OptimizationAlgorithm
Optimization algorithm that computes the bounds of
.
- algo
- getParameter()¶
Accessor to the parameter of the distribution.
- Returns:
- parameter
Point
Parameter values.
- parameter
- getParameterDescription()¶
Accessor to the parameter description of the distribution.
- Returns:
- description
Description
Parameter names.
- description
- getProcess()¶
Get the stochastic process.
- Returns:
- process
Process
Stochastic process used to define the
RandomVector
.
- process
- getR()¶
Accessor to the
parameter.
- Returns:
- rfloat
The
parameter.
- getRange()¶
Accessor to the interval
where the function
.
- Returns:
- rangeF
Interval
Interval
where the function
.
- rangeF
Notes
As
, then
outside
.
- getRealization()¶
Generate a realization.
- Returns:
- point:
Point
A pseudo-random realization of the distribution.
- point:
- getSample(size)¶
Generate a sample.
- Returns:
- sample:
Sample
A pseudo-random sample of the distribution.
- sample:
- getSampleWithTryNumber(size)¶
Sample with number of realizations needed to get it.
- Parameters:
- sizeint,
The number of accepted realizations of the rejection algorithm.
- Returns:
- sample:
Sample
, A pseudo-random realization of the distribution of size size.
- tryNumberint,
The number realizations needed to produce size accepted realizations.
- sample:
Notes
The rejection algorithm produces tryNumber realizations of the uniform distribution on
to produce size realizations inside
.
- getSupU()¶
Accessor to the
-upper bound of
.
- Returns:
- supUfloat, positive
The
-upper bound of
defined in (1).
Notes
The
-upper bound of
is
.
- getSupV()¶
Accessor to the
-upper bound of
.
Notes
The
-upper bound of
is
.
- getThreshold()¶
Accessor to the threshold of the Event.
- Returns:
- thresholdfloat
Threshold of the
RandomVector
.
- hasName()¶
Test if the object is named.
- Returns:
- hasNamebool
True if the name is not empty.
- initialize()¶
Trigger to the initializationof the class.
- Returns:
- collMutliStartcollection of
MultiStart
Collection of the multistart optimization algorithms used to compute the bounds of
.
- collMutliStartcollection of
Notes
A call to that method triggers the computation of the bounding box
and the estimation of the acceptance ratio.
The methods returns a collection of multistart optimization algorithms containing:
the multistart optimization algorithm used to compute
,
for each
, the multistart optimization algorithm used to compute
if required, the one used to compute
if required.
Then, the size of the collection of
MultiStart
is less thanand at least 1. These multistart optimization algorithms give access to the starting points used to compute the optimization problem and all the results associated.
Within the initialization of the class, the acceptance ratio is computed:
If the class has been created with a scaled function, the acceptance ratio is defined by (2) where
. If the acceptance ratio is greater than 1, then it means that the optimization problem has not worked well and a warning is sent.
If the class has been created with an unscaled function, the acceptance ratio is estimated with the method getSampleWithTryNumber: if
is the number of realizations uniformly generated inside
to get
accepted realizations, then we have:
(3)¶
In that case,
is always less than 1.
- isComposite()¶
Accessor to know if the RandomVector is a composite one.
- Returns:
- isCompositebool
Indicates if the RandomVector is of type Composite or not.
- isEvent()¶
Whether the random vector is an event.
- Returns:
- isEventbool
Whether it takes it values in {0, 1}.
- isInitialized()¶
Flag telling if the algorithm has been initialized.
- Returns:
- answer: bool
Flag telling if the bounding box
and the acceptance ratio has already been computed.
- setCandidateNumber(candidateNumber)¶
Accessor to the maximum number of points tested to find admissible starting points.
- Parameters:
- nint,
Maximum number of points tested to find admissible points for the optimization algorithm.
- nint,
Notes
As long as the number of selected starting points is less than the number defined in
ResourceMap
, entry RatioOfUniforms-MaximumMultiStart, a new point of the Sobol low discrepancy sequence of dimensionis considered. The maximum points of the Sobol sequence is
. If no starting point has been selected, a warning is sent.
- setDescription(description)¶
Accessor to the description of the RandomVector.
- Parameters:
- descriptionstr or sequence of str
Describes the components of the RandomVector.
- setLogUnscaledPDFAndRange(logUnscaledPDF, range, isScaled)¶
Accessor to the function
and the range
.
- setMaximumMultiStart(maximumMultiStart)¶
Accessor to the maximum number of starting points for the multistart algorithm.
- Parameters:
- nint,
Maximum number of starting points for the multistart algorithm.
- nint,
Notes
A tested point
is kept as a starting point of the multistart algorithm if
.
- setName(name)¶
Accessor to the object’s name.
- Parameters:
- namestr
The name of the object.
- setOptimizationAlgorithm(optimizationAlgorithm)¶
Accessor to the optimization algorithm.
- Parameters:
- algo
OptimizationAlgorithm
Optimization algorithm that computes the bounds of
.
- algo
- setParameter(parameters)¶
Accessor to the parameter of the distribution.
- Parameters:
- parametersequence of float
Parameter values.
- setR(r)¶
Accessor to the
parameter.
- Parameters:
- rfloat
The
parameter.
Notes
This method triggers the initialization of the class.
Examples using the class¶
Use the Ratio of Uniforms algorithm to sample a distribution