gemseo_umdo / statistics / multilevel / mlmc

Hide inherited members

mlmc module

A generic algorithm for multilevel Monte Carlo (MLMC) sampling.

class gemseo_umdo.statistics.multilevel.mlmc.mlmc.MLMC(levels, uncertain_space, n_samples, pilot_statistic_name='Mean', seed=0)[source]

Bases: object

Multilevel Monte Carlo (MLMC) algorithm.

This algorithm aims at sampling the different model levels in an adaptive way, with many evaluations for the coarsest model and a few evaluations for the finest one.

This adaptive sampling is guided by a [Pilot][gemseo_umdo.statistics.multilevel.pilot.Pilot].

This algorithm depends on the execution cost ratio between two consecutive levels, that can be estimated from the models, and on the sampling size ratio between two sampling steps on the same level.

At a given iteration, the algorithm

  1. considers a level $ell^*$ and a sample size $n_{ell^*}$

  2. samples the models involved in the statistic $T_{ell^*}$ of the telescoping sum (TS) $theta_L = sum_{ell=0}^L T_ell$,

  3. computes the new level $ell^*$ to sample and the corresponding sample size $n_{ell^*}$.

Parameters:

  • levels (Iterable[Level]) – The levels defined in terms of model, evaluation cost and initial number of calls.

  • uncertain_space (ParameterSpace) – The uncertain space on which to sample the functions.

  • n_samples (float) – The sampling budget expressed as the number of model evaluations equivalent to evaluations of the finest model. This number is not necessarily an integer; for instance, if $f_L$ is twice as expensive as $f_{L-1}$, then n_samples=1.5 can correspond to 1 evaluation of $f_L$ and 1 evaluation of $f_{L-1}$.

  • pilot_statistic_name (str) –

    The name of the statistic used to drive the algorithm.

    By default it is set to “Mean”.

  • seed (int) –

    The initial random seed for reproducibility. Then, the seed is incremented at each level of the telescopic sum and at each algorithm iteration.

    By default it is set to 0.

Raises:

ValueError – When the minimum cost is greater than the maximum cost.

execute()[source]

Execute the algorithm.

Return type:

None

plot_evaluation_history(show=True, file_path=None, log_n_evaluations=True, log_budget=False)[source]

Plot the history of the model evaluations in terms of sample size and budget.

Parameters:

  • show (bool) –

    Whether to display the graph.

    By default it is set to True.

  • file_path (str | Path) – The file path to save the graph.

  • log_n_evaluations (bool) –

    Whether to use a log-scale for the number of evaluations.

    By default it is set to True.

  • log_budget (bool) –

    Whether to use a log-scale for the budget.

    By default it is set to False.

Return type:

None

property budget_history: ndarray[Any, dtype[float]]

The history of the budget.

algo.budget_history[i] is the budget at iteration i+1.

property level_costs: ndarray[Any, dtype[float]]

The evaluation costs of the different levels.

algo.level_costs[l] is the cost of one evaluation of the l-th level.

property model_costs: ndarray[Any, dtype[float]]

The evaluation costs of the different models.

algo.model_costs[l] is the cost of one evaluation of the l-th model.

property n_total_samples: ndarray[Any, dtype[int]]

The total numbers of samples per level.

algo.n_total_samples[l] is the total number of samples at level l.

property pilot_statistic_estimation: ndarray[Any, dtype[float]]

The estimation of the pilot statistic.

property sampling_history: ndarray[Any, dtype[int]]

The history of the numbers of samples of each level of the telescopic sum.

algo.sampling_size_history[i, l] is the number of samples at iteration i+1 and level l.