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 forOTDistribution
or a dictionary of keyword arguments forSPDistribution
, or keyword arguments for standard probability distribution such asOTNormalDistribution
andSPNormalDistribution
).
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 differentget_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, **parameters)[source]
Add a random variable from a probability distribution.
Warning
The probability distributions must have the same
DISTRIBUTION_FAMILY_ID
. For instance, one cannot mix a random variable distributed as aOTUniformDistribution
with identifier"OT"
and a random variable distributed as aSPNormalDistribution
with identifier"SP"
.- Parameters:
name (str) – The name of the random variable.
distribution (str) – The name of a class implementing a probability distribution, e.g.
"OTUniformDistribution"
or"SPDistribution"
.size (int) –
The dimension of the random variable.
By default it is set to 1.
**parameters (int | Tuple[str, int, float] | Mapping[str, str | int | float] | None | float) – The parameters of the distribution.
- Raises:
ValueError – When mixing probability distributions from different families, e.g. an
OTDistribution
and aSPDistribution
.- 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:
- 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:
- evaluate_cdf(value, inverse=False)[source]
Evaluate the cumulative density function (or its inverse) of each marginal.
- Parameters:
value (dict[str, numpy.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:
- extract_deterministic_space()[source]
Define a new
DesignSpace
from the deterministic variables only.- Returns:
A
DesignSpace
defined by the deterministic variables only.- Return type:
- 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 aDesignSpace
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:
- 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:
- 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:
- get_tabular_view(decimals=2)[source]
Return a tabular view of the parameter space.
This view contains statistical information.
- 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:
- is_deterministic(variable)[source]
Check if a variable is deterministic.
- is_uncertain(variable)[source]
Check if a variable is uncertain.
- 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.
- 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:
- 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 inDesignSpace.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
- 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, Distribution]
The marginal probability distributions of the uncertain variables.
- normalize: dict[str, ndarray]
The normalization policies of the variables components indexed by the variables names; if True, the component can be normalized.
- 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