Introduction to Uncertainty Quantification and Management¶

Operate in an uncertain world¶

Uncertainty Quantification and Management (UQ&M) is a field of engineering on the rise where several questions arise for the user:

uncertainty quantification: how to represent the sources of uncertainties, whether by expert opinion or via data?
uncertainty propagation: how to propagate these uncertainties through a model or a system of coupled models?
uncertainty quantification (again!): how to represent the resulting uncertainty about the output quantity of interest?
sensitivity analysis: how to explain this output uncertainty from the input ones? Are there non-influential sources? Can the others be ordered?
reliability: what is the probability that the quantity of interest exceeds a threshold? Conversely, what is the guaranteed threshold for a given confidence level?
robust optimization: what would be a good design solution in terms of performance (or cost) and constraints satisfaction, in an uncertain world? Rather than looking for the best solution in the worst case scenario, which would lead to a very conservative solution, why not relax the constraints by guaranteeing them in 99% of cases while maximizing an average performance (or minimizing an average cost)?

GEMSEO implements several UQ&M key concepts through a dedicated package. Moreover, its class ParameterSpace extends the notion of DesignSpace by defining both deterministic and uncertain variables. It can already be used in a DOEScenario to sample a multidisciplinary system. Moreover, the GEMSEO community is currently working on extending its use to any kind of Scenario for robust MDO purposes (see Roadmap) by means of dedicated MDO formulations.

The package uncertainty¶

Uncertainty quantification and management.

The package uncertainty provides several functionalities to quantify and manage uncertainties. Most of them can be used from the high-level functions provided by this module.

The sub-package distributions offers an abstract level for probability distributions, as well as interfaces to the OpenTURNS and SciPy ones. It is also possible to fit a probability distribution from data or select the most likely one from a list of candidates. These distributions can be used to define random variables in a ParameterSpace before propagating these uncertainties through a system of MDODiscipline, by means of a DOEScenario.

gemseo.uncertainty.create_distribution(variable, distribution_name, dimension=1, **options)[source]

Create a distribution.

Parameters:

variable (str) – The name of the random variable.
distribution_name (str) – The name of a class implementing a probability distribution, e.g. ‘OTUniformDistribution’ or ‘SPDistribution’.
dimension (int) –
The dimension of the random variable.

By default it is set to 1.
**options – The distribution options.

Return type:

Distribution

Examples

>>> from gemseo.uncertainty import create_distribution
>>>
>>> distribution = create_distribution(
...     "x", "OTNormalDistribution", dimension=2, mu=1, sigma=2
... )
>>> print(distribution)
Normal(mu=1, sigma=2)
>>> print(distribution.mean, distribution.standard_deviation)
[1. 1.] [2. 2.]
>>> samples = distribution.compute_samples(10)
>>> print(samples.shape)
(10, 2)

gemseo.uncertainty.create_sensitivity_analysis(analysis, disciplines, parameter_space, **options)[source]

Create the sensitivity analysis.

Parameters:

analysis (str) – The name of a sensitivity analysis class.
disciplines (Collection[MDODiscipline]) – The disciplines.
parameter_space (ParameterSpace) – A parameter space.
**options – The DOE algorithm options.

Returns:

The toolbox for these sensitivity indices.

Return type:

SensitivityAnalysis

Examples

>>> from gemseo import create_discipline, create_parameter_space
>>> from gemseo.uncertainty import create_sensitivity_analysis
>>>
>>> expressions = {"y1": "x1+2*x2", "y2": "x1-3*x2"}
>>> discipline = create_discipline(
...     "AnalyticDiscipline", expressions=expressions
... )
>>>
>>> parameter_space = create_parameter_space()
>>> parameter_space.add_random_variable(
...     "x1", "OTUniformDistribution", minimum=-1, maximum=1
... )
>>> parameter_space.add_random_variable(
...     "x2", "OTNormalDistribution", mu=0.5, sigma=2
... )
>>>
>>> analysis = create_sensitivity_analysis(
...     "CorrelationIndices", [discipline], parameter_space, n_samples=1000
... )
>>> indices = analysis.compute_indices()

gemseo.uncertainty.create_statistics(dataset, variable_names=None, tested_distributions=None, fitting_criterion='BIC', selection_criterion='best', level=0.05, name=None)[source]

Create a statistics toolbox, either parametric or empirical.

If parametric, the toolbox selects a distribution from candidates, based on a fitting criterion and on a selection strategy.

Parameters:

dataset (Dataset) – A dataset.
variable_names (Iterable[str] | None) – The variables of interest. If None, consider all the variables from dataset.
tested_distributions (Sequence[str] | None) – The names of the tested distributions.
fitting_criterion (str) –
The name of a goodness-of-fit criterion, measuring how the distribution fits the data. Use ParametricStatistics.get_criteria() to get the available criteria.

By default it is set to “BIC”.
selection_criterion (str) –
The name of a selection criterion to select a distribution from candidates. Either ‘first’ or ‘best’.

By default it is set to “best”.
level (float) –
A test level, i.e. the risk of committing a Type 1 error, that is an incorrect rejection of a true null hypothesis, for criteria based on a test hypothesis.

By default it is set to 0.05.
name (str | None) – A name for the statistics toolbox instance. If None, use the concatenation of class and dataset names.

Returns:

A statistics toolbox.

Return type:

Statistics

Examples

>>> from gemseo import (
...     create_discipline,
...     create_parameter_space,
...     create_scenario,
... )
>>> from gemseo.uncertainty import create_statistics
>>>
>>> expressions = {"y1": "x1+2*x2", "y2": "x1-3*x2"}
>>> discipline = create_discipline(
...     "AnalyticDiscipline", expressions=expressions
... )
>>>
>>> parameter_space = create_parameter_space()
>>> parameter_space.add_random_variable(
...     "x1", "OTUniformDistribution", minimum=-1, maximum=1
... )
>>> parameter_space.add_random_variable(
...     "x2", "OTNormalDistribution", mu=0.5, sigma=2
... )
>>>
>>> scenario = create_scenario(
...     [discipline],
...     "DisciplinaryOpt",
...     "y1",
...     parameter_space,
...     scenario_type="DOE",
... )
>>> scenario.execute({"algo": "OT_MONTE_CARLO", "n_samples": 100})
>>>
>>> dataset = scenario.to_dataset(opt_naming=False)
>>>
>>> statistics = create_statistics(dataset)
>>> mean = statistics.compute_mean()

gemseo.uncertainty.get_available_distributions(base_class_name='Distribution')[source]

Get the available probability distributions.

Parameters:

base_class_name (str) –

The name of the base class of the probability distributions, e.g. "Distribution", "OTDistribution" or "SPDistribution".

By default it is set to “Distribution”.

Returns:

The names of the available probability distributions.

Return type:

list[str]

gemseo.uncertainty.get_available_sensitivity_analyses()[source]

Get the available sensitivity analyses.

Return type:: list[str]

gemseo.uncertainty.load_sensitivity_analysis(file_path)[source]

Load a sensitivity analysis from the disk.

Parameters:: file_path (str | Path) – The path to the file.
Returns:: The sensitivity analysis.
Return type:: SensitivityAnalysis