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 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 "".

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 empty, 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

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 | BaseDistribution_Settings) -- Either the name of a class implementing a probability distribution, e.g. "OTUniformDistribution" or "SPUniformDistribution", the name of a class implementing an interface to a library of probability distributions, e.g. "OTDistribution" or "SPDistribution", or the settings of the distribution. In the case of settings, the argument interfaced_distribution, interfaced_distribution_parameters and parameters are ignored.
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] | StrKeyMapping) --
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 identifier. 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".

Examples

>>> from gemseo.algos.parameter_space import ParameterSpace
>>> from gemseo.settings.probability_distributions import (
...     SPNormalDistribution_Settings,
... )
>>> from gemseo.settings.probability_distributions import (
...     SPUniformDistribution_Settings,
... )
>>> parameter_space = ParameterSpace()
>>> # Add a normally distributed variable
>>> # with mean equal to 3 and standard deviation equal to 1.
>>> parameter_space.add_random_variable(
...     "u", SPNormalDistribution_Settings(mu=3.0)
... )
>>> # Add a 2-length uniformly distributed vector variable
>>> # with minimum equal to 0 and maximum equal to 2
>>> # (the components are stochastically independent).
>>> parameter_space.add_random_variable(
...     "v", SPUniformDistribution_Settings(maximum=2.0), size=2
... )

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 identifier. 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 | Iterable[BaseDistribution_Settings]) -- Either te name of a class implementing a probability distribution, e.g. "OTUniformDistribution" or "SPUniformDistribution", an interface to a library of probability distributions, e.g. "OTDistribution" or "SPDistribution", or a collection of distribution settings. In the case of settings, the argument size, interfaced_distribution, interfaced_distribution_parameters and parameters are ignored.
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

Examples

>>> from gemseo.algos.parameter_space import ParameterSpace
>>> from gemseo.settings.probability_distributions import (
...     SPNormalDistribution_Settings,
... )
>>> from gemseo.settings.probability_distributions import (
...     SPUniformDistribution_Settings,
... )
>>> parameter_space = ParameterSpace()
>>> # Add a normally distributed variable
>>> # with mean equal to 3 and standard deviation equal to 1.
>>> parameter_space.add_random_vector(
...     "u", (SPNormalDistribution_Settings(mu=3.0),)
... )
>>> # Add a uniformly distributed vector variable
>>> # with minimum equal to 0 and maximum equal to 2.
>>> parameter_space.add_random_vector(
...     "v",
...     (
...         SPUniformDistribution_Settings(maximum=2.0),
...         SPUniformDistribution_Settings(maximum=2.0),
...     ),
... )

add_variables_from(space, *names)[source]#

Add variables from another variable space.

Parameters:

space (DesignSpace) -- The other variable space.
*names (str) -- The names of the variables.

Return type:

None

build_joint_distribution(copula=None)[source]#

Build the joint probability distribution.

Parameters:: copula (Any) -- 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=(), with_index=False, capitalize=False, simplify=False)[source]#

Build a tabular view of the design space.

Parameters:

fields (Sequence[str]) --
The name of the fields to be exported. If empty, export all the fields.

By default it is set to ().
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

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.

distribution: BaseJointDistribution#: The joint probability distribution of the uncertain variables.

distributions: dict[str, BaseJointDistribution]#

The marginal probability distributions of the uncertain variables.

These variables are defined as random vectors with independent components.

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

gemseo.algos.parameter_space module#

Overview#

Capabilities#

This Page