libopenturns-dev 1.9-5 / usr / include / openturns / swig / EfficientGlobalOptimization_doc.i

%feature("docstring") OT::EfficientGlobalOptimization
"Efficient Global Optimization algorithm.

The EGO algorithm [Jones1998]_ is an adaptative optimization method based on
kriging.
An initial design of experiment is used to build a first metamodel.
At each iteration a new point that maximizes a criterion is chosen as
optimizer candidate.
The criterion uses a tradeoff between the metamodel value and the conditional
variance.
Then the new point is evaluated using the original model and the metamodel is
relearnt on the extended design of experiment.

Available constructors:
    EfficientGlobalOptimization(*problem, krigingResult*)

Parameters
----------
problem : :class:`~openturns.OptimizationProblem`
    The optimization problem to solve
    optionally, a 2nd objective marginal can be used as noise
krigingResult : :class:`~openturns.KrigingResult`
    The result of the meta-model on the first design of experiment

Notes
-----
Each point added to the metamodel design seeks to improve the current minimum.
We chose the point so as to maximize an improvement criterion based on the
metamodel.

.. math::

    I(x_{new}) = max(f_{min} - Y_{new}, 0)

The default criteria is called EI (Expected Improvement) and aims at maximizing
the mean improvement:

.. math::

    \\\\mathbb{E}\\\\left[I(x_{new})\\\\right] = \\\\mathbb{E}\\\\left[max(f_{min} - Y_{new}, 0)\\\\right]

This criterion is explicited using the kriging mean and variance:

.. math::

    \\\\mathbb{E}\\\\left[I(x_{new})\\\\right] = (f_{min} - m_K(x_{new})) \\\\Phi\\\\left( \\\\frac{f_{min} - m_K(x_{new})}{s_K(x_{new})} \\\\right) + s_K(x_{new}) \\\\phi\\\\left( \\\\frac{f_{min} - m_K(x_{new})}{s_K(x_{new})} \\\\right)

An observation noise variance can be provided thanks to a 2nd objective marginal.

.. math:: Y_{obs} = Y(x) + \\\\sigma_{\\\\epsilon}(x) \\\\epsilon

In that case the AEI (Augmented Expected Improvement) formulation is used.
As we don't have access to the real minimum of the function anymore a quantile
of the kriging prediction is used, with the constant :math:`c`:

.. math:: u(x) = m_K(x) + c s_K(x)

This criterion is minimized over the design points:

.. math:: x_{min} = \\\\argmax_{x_i} (u(x_i))

The AEI criterion reads:

.. math::

    AEI(x_{new}) = \\\\mathbb{E}\\\\left[max(m_K(x_{min}) - Y_{new}, 0)\\\\right] \\\\times \\\\left(1 - \\\\frac{\\\\sigma_{\\\\epsilon}(x_{new})}{\\\\sqrt{\\\\sigma_{\\\\epsilon}^2(x_{new})+s^2_K(x_{new})}} \\\\right)

with

.. math::

    \\\\mathbb{E}\\\\left[max(m_K(x_{min}) - Y_{new}, 0)\\\\right] = (m_K(x_{min}) - m_K(x_{new})) \\\\Phi\\\\left( \\\\frac{m_K(x_{min}) - m_K(x_{new})}{s_K(x_{new})} \\\\right) + s_K(x_{new}) \\\\phi\\\\left( \\\\frac{m_K(x_{min}) - m_K(x_{new})}{s_K(x_{new})} \\\\right)

A less computationally expensive noise function can be provided through
:func:`setNoiseModel()` to evaluate :math:`\\\\sigma^2_{\\\\epsilon}(x)`
for the improvement criterion optimization, the objective being only used to
compute values and associated noise at design points.

By default the criteria is minimized using :class:`~openturns.MultiStart`
with starting points uniformly sampled in the optimization problem bounds,
see :func:`setMultiStartExperimentSize` and :func:`setMultiStartNumber`.
This behavior can be overridden by using another solver with :func:`setOptimizationAlgorithm`.

Examples
--------
>>> import openturns as ot
>>> ot.RandomGenerator.SetSeed(0)
>>> dim = 4
>>> model = ot.SymbolicFunction(['x1', 'x2', 'x3', 'x4'],
...     ['x1*x1+x2^3*x1+x3+x4'])
>>> bounds = ot.Interval([-5.0] * dim, [5.0] * dim)
>>> problem = ot.OptimizationProblem()
>>> problem.setObjective(model)
>>> problem.setBounds(bounds)
>>> experiment = ot.Composite([0.0] * dim, [1.0, 2.0, 4.0])
>>> inputSample = experiment.generate()
>>> outputSample = model(inputSample)
>>> covarianceModel = ot.SquaredExponential([2.0] * dim, [0.1])
>>> basis = ot.ConstantBasisFactory(dim).build()
>>> kriging = ot.KrigingAlgorithm(inputSample, outputSample, covarianceModel, basis)
>>> kriging.run()
>>> algo = ot.EfficientGlobalOptimization(problem, kriging.getResult())
>>> algo.setMaximumIterationNumber(2)
>>> algo.run()
>>> result = algo.getResult()"

// ---------------------------------------------------------------------

%feature("docstring") OT::EfficientGlobalOptimization::setOptimizationAlgorithm
"Expected improvement solver accessor.

Parameters
----------
solver : :class:`~openturns.OptimizationSolver`
    The solver used to optimize the expected improvement"

// ---------------------------------------------------------------------

%feature("docstring") OT::EfficientGlobalOptimization::getOptimizationAlgorithm
"Expected improvement solver accessor.

Returns
-------
solver : :class:`~openturns.OptimizationSolver`
    The solver used to optimize the expected improvement"

// ---------------------------------------------------------------------

%feature("docstring") OT::EfficientGlobalOptimization::setMultiStartExperimentSize
"Size of the design to draw starting points.

Parameters
----------
multiStartExperimentSize : int
    The size of the Monte Carlo design from which to select the best starting
    points.
    The default number can be tweaked with the
    `EfficientGlobalOptimization-DefaultMultiStartExperimentSize` key from
    :class:`~openturns.ResourceMap`."

// ---------------------------------------------------------------------

%feature("docstring") OT::EfficientGlobalOptimization::getMultiStartExperimentSize
"Size of the design to draw starting points.

Returns
-------
multiStartExperimentSize : int
    The size of the Monte Carlo design from which to select the best starting
    points."

// ---------------------------------------------------------------------

%feature("docstring") OT::EfficientGlobalOptimization::setMultiStartNumber
"Number of starting points for the criterion optimization.

Parameters
----------
multiStartNumber : int
    The number of starting points for the criterion optimization.
    The default number can be tweaked with the
    `EfficientGlobalOptimization-DefaultMultiStartNumber` key from
    :class:`~openturns.ResourceMap`."

// ---------------------------------------------------------------------

%feature("docstring") OT::EfficientGlobalOptimization::getMultiStartNumber
"Number of starting points for the criterion optimization.

Returns
-------
multiStartNumber : int
    The number of starting points for the criterion optimization."

// ---------------------------------------------------------------------

%feature("docstring") OT::EfficientGlobalOptimization::setParameterEstimationPeriod
"Parameter estimation period accessor.

Parameters
----------
period : int
    The number of iterations between covariance parameters re-learn.
    Default is 1 (each iteration). Can be set to 0 (never).
    The default number can be tweaked with the
    `EfficientGlobalOptimization-DefaultParameterEstimationPeriod` key from
    :class:`~openturns.ResourceMap`."

// ---------------------------------------------------------------------

%feature("docstring") OT::EfficientGlobalOptimization::getParameterEstimationPeriod
"Parameter estimation period accessor.

Returns
-------
period : int
    The number of iterations between covariance parameters re-learn.
    Default is 1 (each iteration). Can be set to 0 (never)."

// ---------------------------------------------------------------------

%feature("docstring") OT::EfficientGlobalOptimization::setImprovementFactor
"Improvement criterion factor accessor.

Parameters
----------
a : float
    Used to define a stopping criterion on the improvement criterion:
    :math:`I_{max} < \\\\alpha |Y_{min}|`
    with :math:`I_{max}` the current maximum of the improvement
    and :math:`Y_{min}` the current optimum."

// ---------------------------------------------------------------------

%feature("docstring") OT::EfficientGlobalOptimization::getImprovementFactor
"Improvement criterion factor accessor.

Returns
-------
a : float
    Used to define a stopping criterion on the improvement criterion:
    :math:`I_{max} < \\\\alpha |Y_{min}|`
    with :math:`I_{max}` the current maximum of the improvement
    and :math:`Y_{min}` the current optimum."

// ---------------------------------------------------------------------

%feature("docstring") OT::EfficientGlobalOptimization::setCorrelationLengthFactor
"Correlation length stopping criterion factor accessor.

Parameters
----------
b : float
    Used to define a stopping criterion on the minimum correlation length:
    :math:`\\\\theta_i < \\\\frac{\\\\Delta_i^{min}}{b}`
    with :math:`\\\\Delta^{min}` the minimum distance between design points."

// ---------------------------------------------------------------------

%feature("docstring") OT::EfficientGlobalOptimization::getCorrelationLengthFactor
"Correlation length stopping criterion factor accessor.

Returns
-------
b : float
    Used to define a stopping criterion on the minimum correlation length:
    :math:`\\\\theta_i < \\\\frac{\\\\Delta_i^{min}}{b}`
    with :math:`\\\\Delta^{min}` the minimum distance between design points."

// ---------------------------------------------------------------------

%feature("docstring") OT::EfficientGlobalOptimization::setAIETradeoff
"AEI tradeoff constant accessor.

Parameters
----------
c : float
    Used to define a quantile of the kriging prediction at the design points.
    :math:`u(x)=m_K(x)+c*s_K(x)`"

// ---------------------------------------------------------------------

%feature("docstring") OT::EfficientGlobalOptimization::getAIETradeoff
"AEI tradeoff constant accessor.

Returns
-------
c : float
    Used to define a quantile of the kriging prediction at the design points.
    :math:`u(x)=m_K(x)+c*s_K(x)`"

// ---------------------------------------------------------------------

%feature("docstring") OT::EfficientGlobalOptimization::getExpectedImprovement
"Expected improvement values.

Returns
-------
ei : :class:`~openturns.Sample`
    The expected improvement optimal values."

// ---------------------------------------------------------------------

%feature("docstring") OT::EfficientGlobalOptimization::setNoiseModel
"Improvement noise model accessor.

Parameters
----------
noiseVariance : :class:`~openturns.Function`
    The noise variance :math:`\\\\sigma^2_{\\\\epsilon}(x)` used for the AEI
    criterion optimization only.
    Of same input dimension than the objective and 1-d output."

// ---------------------------------------------------------------------

%feature("docstring") OT::EfficientGlobalOptimization::getNoiseModel
"Improvement noise model accessor.

Returns
-------
noiseVariance : :class:`~openturns.Function`
    The noise variance :math:`\\\\sigma^2_{\\\\epsilon}(x)` used for the AEI
    criterion optimization only.
    Of same input dimension than the objective and 1-d output."