gemseo / algos

parameter_space module¶

Variable space defining both deterministic and uncertain variables.

Overview¶

The ParameterSpace class describes a set of parameters of interest which can be either deterministic or uncertain. This class inherits from DesignSpace.

Capabilities¶

The DesignSpace.add_variable() aims to add deterministic variables from:

a variable name,
an optional variable size (default: 1),
an optional variable type (default: float),
an optional lower bound (default: - infinity),
an optional upper bound (default: + infinity),
an optional current value (default: None).

The add_random_variable() aims to add uncertain variables (a.k.a. random variables) from:

a variable name,
a distribution name (see uncertainty.get_available_distributions()),
an optional variable size,
optional distribution parameters (parameters set as a tuple of positional arguments for OTDistribution or a dictionary of keyword arguments for SPDistribution, or keyword arguments for standard probability distribution such as OTNormalDistribution and SPNormalDistribution).

The ParameterSpace also provides the following methods:

ParameterSpace.compute_samples(): returns several samples of the uncertain variables,
evaluate_cdf(): evaluate the cumulative density function for the different variables and their different
get_range() returns the numerical range of the different uncertain parameters,
get_support(): returns the mathematical support of the different uncertain variables,
is_uncertain(): checks if a parameter is uncertain,
is_deterministic(): checks if a parameter is deterministic.

class gemseo.algos.parameter_space.ParameterSpace(name='')[source]

Bases: DesignSpace

Parameter space.

Parameters:

name (str) –

The name to be given to the design space. If empty, the design space is unnamed.

By default it is set to “”.

add_random_variable(name, distribution, size=1, interfaced_distribution='', interfaced_distribution_parameters=(), **parameters)[source]

Add a random variable from a probability distribution.

Parameters:

name (str) – The name of the random variable.
distribution (str) – The name of a class implementing a probability distribution, e.g. "OTUniformDistribution" or "SPUniformDistribution", or an interface to a library of probability distributions, e.g. "OTDistribution" or "SPDistribution".
size (int) –
The dimension of the random variable. The parameters of the distribution are shared by all the components of the random variable.

By default it is set to 1.
interfaced_distribution (str) –
The name of the distribution in the library of probability distributions when distribution is the name of a class implementing an interface to this library.

By default it is set to “”.
interfaced_distribution_parameters (tuple[Any] | Mapping[str, Any]) –
The parameters of the distribution in the library of probability distributions when distribution is the name of a class implementing an interface to this library; if empty, use the default ones.

By default it is set to ().
**parameters (Any) – The parameters of the distribution; otherwise, use the default ones.

Return type:

None

Warning

The probability distributions must have the same DISTRIBUTION_FAMILY_ID. For instance, one cannot mix a random variable distributed as an OTUniformDistribution with identifier "OT" and a random variable distributed as a SPNormalDistribution with identifier "SP".

add_random_vector(name, distribution, size=0, interfaced_distribution='', interfaced_distribution_parameters=(), **parameters)[source]

Add a d-length random vector from a probability distribution.

Warning

The probability distributions must have the same DISTRIBUTION_FAMILY_ID. For instance, one cannot mix a random vector using a OTUniformDistribution with identifier "OT" and a random vector using a SPNormalDistribution with identifier "SP".

Parameters:

name (str) – The name of the random vector.
distribution (str) – The name of a class implementing a probability distribution, e.g. "OTUniformDistribution" or "SPUniformDistribution", or an interface to a library of probability distributions, e.g. "OTDistribution" or "SPDistribution".
size (int) –
The length d of the random vector. If 0, deduce it from the parameters.

By default it is set to 0.
interfaced_distribution (str) –
The name of the distribution in the library of probability distributions when distribution is the name of a class implementing an interface to this library.

By default it is set to “”.
interfaced_distribution_parameters (tuple[list[Any]] | Mapping[str, list[Any]]) –
The parameters of the distribution in the library of probability distributions when distribution is the name of a class implementing an interface to this library. The values of the data structure (mapping or tuple) must be set either as [p_1,...,p_d] (one value per component of the random vector) or as [p] (one value for all the components) If empty, use the default ones.

By default it is set to ().
**parameters (list[Any]) – The parameters of the distribution, either as [p_1,...,p_d] (one value per component of the random vector) or as [p] (one value for all the components); otherwise, use the default ones.

Raises:

ValueError – When mixing probability distributions from different families, e.g. an OTDistribution and a SPDistribution or when the lengths of the distribution parameter collections are not consistent.

Return type:

None

build_composed_distribution(copula=None)[source]

Build the joint probability distribution.

Parameters:: copula (Any | None) – A copula distribution defining the dependency structure between random variables; if None, consider an independent copula.
Return type:: None

compute_samples(n_samples=1, as_dict=False)[source]

Sample the random variables and return the realizations.

Parameters:

n_samples (int) –
A number of samples.

By default it is set to 1.
as_dict (bool) –
The type of the returned object. If True, return a dictionary. Otherwise, return an array.

By default it is set to False.

Returns:

The realizations of the random variables, either stored in an array or in a dictionary whose values are the names of the random variables and the values are the evaluations.

Return type:

dict[str, ndarray] | ndarray

evaluate_cdf(value, inverse=False)[source]

Evaluate the cumulative density function (or its inverse) of each marginal.

Parameters:

value (dict[str, ndarray]) – The values of the uncertain variables passed as a dictionary whose keys are the names of the variables.
inverse (bool) –
The type of function to evaluate. If True, compute the cumulative density function. Otherwise, compute the inverse cumulative density function.

By default it is set to False.

Returns:

A dictionary where the keys are the names of the random variables and the values are the evaluations.

Return type:

dict[str, ndarray]

extract_deterministic_space()[source]

Define a new DesignSpace from the deterministic variables only.

Returns:: A DesignSpace defined by the deterministic variables only.
Return type:: DesignSpace

extract_uncertain_space(as_design_space=False)[source]

Define a new DesignSpace from the uncertain variables only.

Parameters:

as_design_space (bool) –

If False, return a ParameterSpace containing the original uncertain variables as is; otherwise, return a DesignSpace where the original uncertain variables are made deterministic. In that case, the bounds of a deterministic variable correspond to the limits of the support of the original probability distribution and the current value correspond to its mean.

By default it is set to False.

Returns:

A ParameterSpace defined by the uncertain variables only.

Return type:

DesignSpace | ParameterSpace

get_pretty_table(fields=None, with_index=False, capitalize=False, simplify=False)[source]

Build a tabular view of the design space.

Parameters:

fields (Sequence[str] | None) – The name of the fields to be exported. If None, export all the fields.
with_index (bool) –
Whether to show index of names for arrays. This is ignored for scalars.

By default it is set to False.
capitalize (bool) –
Whether to capitalize the field names and replace "_" by " ".

By default it is set to False.
simplify (bool) –
Whether to return a simplified tabular view.

By default it is set to False.

Returns:

A tabular view of the design space.

Return type:

PrettyTable

get_range(variable)[source]

Return the numerical range of a random variable.

Parameters:: variable (str) – The name of the random variable.
Returns:: The range of the components of the random variable.
Return type:: list[ndarray]

get_support(variable)[source]

Return the mathematical support of a random variable.

Parameters:: variable (str) – The name of the random variable.
Returns:: The support of the components of the random variable.
Return type:: list[ndarray]

get_tabular_view(decimals=2)[source]

Return a tabular view of the parameter space.

This view contains statistical information.

Parameters:

decimals (int) –

The number of decimals to print.

By default it is set to 2.

Returns:

The tabular view.

Return type:

str

static init_from_dataset(dataset, groups=None, uncertain=None, copula=None)[source]

Initialize the parameter space from a dataset.

Parameters:

dataset (Dataset) – The dataset used for the initialization.
groups (Iterable[str] | None) – The groups of the dataset to be considered. If None, consider all the groups.
uncertain (Mapping[str, bool] | None) – Whether the variables should be uncertain or not.
copula (Any) – A name of copula defining the dependency between random variables.

Return type:

ParameterSpace

is_deterministic(variable)[source]

Check if a variable is deterministic.

Parameters:: variable (str) – The name of the variable.
Returns:: True is the variable is deterministic.
Return type:: bool

is_uncertain(variable)[source]

Check if a variable is uncertain.

Parameters:: variable (str) – The name of the variable.
Returns:: True is the variable is uncertain.
Return type:: bool

normalize_vect(x_vect, minus_lb=True, use_dist=False, out=None)[source]

Normalize a vector of the parameter space.

If use_dist is True, use the cumulative probability distributions of the random variables to scale the components of the random variables between 0 and 1. Otherwise, use the approach defined in DesignSpace.normalize_vect() with minus_lb.

For the components of the deterministic variables, use the approach defined in DesignSpace.normalize_vect() with minus_lb.

Parameters:

x_vect (ndarray) – The values of the design variables.
minus_lb (bool) –
If True, remove the lower bounds at normalization.

By default it is set to True.
use_dist (bool) –
If True, normalize the components of the random variables with their cumulative probability distributions.

By default it is set to False.
out (ndarray | None) – The array to store the normalized vector. If None, create a new array.

Returns:

The normalized vector.

Return type:

ndarray

remove_variable(name)[source]

Remove a variable from the probability space.

Parameters:: name (str) – The name of the variable.
Return type:: None

rename_variable(current_name, new_name)[source]

Rename a variable.

Parameters:

current_name (str) – The name of the variable to rename.
new_name (str) – The new name of the variable.

Return type:

None

to_design_space()[source]

Convert the parameter space into a DesignSpace.

The original deterministic variables are kept as is while the original uncertain variables are made deterministic. In that case, the bounds of a deterministic variable correspond to the limits of the support of the original probability distribution and the current value correspond to its mean.

Returns:: A DesignSpace where all original variables are made deterministic.
Return type:: DesignSpace

transform_vect(vector, out=None)[source]

Map a point of the design space to a vector with components in \([0,1]\).

Parameters:

vector (ndarray) – A point of the design space.
out (ndarray | None) – The array to store the transformed vector. If None, create a new array.

Returns:

A vector with components in \([0,1]\).

Return type:

ndarray

unnormalize_vect(x_vect, minus_lb=True, no_check=False, use_dist=False, out=None)[source]

Unnormalize a normalized vector of the parameter space.

If use_dist is True, use the inverse cumulative probability distributions of the random variables to unscale the components of the random variables. Otherwise, use the approach defined in DesignSpace.unnormalize_vect() with minus_lb and no_check.

For the components of the deterministic variables, use the approach defined in DesignSpace.unnormalize_vect() with minus_lb and no_check.

Parameters:

x_vect (ndarray) – The values of the design variables.
minus_lb (bool) –
Whether to remove the lower bounds at normalization.

By default it is set to True.
no_check (bool) –
Whether to check if the components are in \([0,1]\).

By default it is set to False.
use_dist (bool) –
Whether to unnormalize the components of the random variables with their inverse cumulative probability distributions.

By default it is set to False.
out (ndarray | None) – The array to store the unnormalized vector. If None, create a new array.

Returns:

The unnormalized vector.

Return type:

ndarray

untransform_vect(vector, no_check=False, out=None)[source]

Map a vector with components in \([0,1]\) to the design space.

Parameters:

vector (ndarray) – A vector with components in \([0,1]\).
no_check (bool) –
Whether to check if the components are in \([0,1]\).

By default it is set to False.
out (ndarray | None) – The array to store the untransformed vector. If None, create a new array.

Returns:

A point of the variables space.

Return type:

ndarray

property deterministic_variables: list[str]: The deterministic variables.

dimension: int: The total dimension of the space, corresponding to the sum of the sizes of the variables.

distribution: ComposedDistribution: The joint probability distribution of the uncertain variables.

distributions: dict[str, ComposedDistribution]

The marginal probability distributions of the uncertain variables.

These variables are defined as random vectors with independent components.

name: str | None: The name of the space.

normalize: dict[str, ndarray]: The normalization policies of the variables components indexed by the variables names; if True, the component can be normalized.

uncertain_variables: list[str]: The names of the uncertain variables.

variable_names: list[str]: The names of the variables.

variable_sizes: dict[str, int]: The sizes of the variables.

variable_types: dict[str, ndarray]: The types of the variables components, which can be any DesignSpace.DesignVariableType.

class gemseo.algos.parameter_space.RandomVariable(distribution, size, parameters)

Bases: tuple

Create new instance of RandomVariable(distribution, size, parameters)

distribution: Alias for field number 0

parameters: Alias for field number 2

size: Alias for field number 1

class gemseo.algos.parameter_space.RandomVector(distribution, size, parameters)

Bases: tuple

Create new instance of RandomVector(distribution, size, parameters)

distribution: Alias for field number 0

parameters: Alias for field number 2

size: Alias for field number 1

Examples using ParameterSpace¶

Parameter space

Comparing sensitivity indices

Sobol' analysis