Parameter space#
The class ParameterSpace#
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 ParameterSpace(name='')[source]
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] | 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
DISTRIBUTION_FAMILY_ID
. For instance, one cannot mix a random variable distributed as anOTUniformDistribution
with identifier"OT"
and a random variable distributed as aSPNormalDistribution
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 aOTUniformDistribution
with identifier"OT"
and a random vector using aSPNormalDistribution
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 aSPDistribution
or when the lengths of the distribution parameter collections are not consistent.- Return type:
None
- 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 | 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, 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 aParameterSpace
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_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:
- get_range(variable)[source]
Return the numerical range of a random variable.
- get_support(variable)[source]
Return the mathematical support of a random variable.
- 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: 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.
- class RandomVariable(distribution, size, parameters)
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 RandomVector(distribution, size, parameters)
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