criterion_min module¶
Minimum distance between a point and the learning dataset.
- class gemseo_mlearning.adaptive.criteria.distances.criterion_min.MinimumDistance(algo_distribution, **options)[source]¶
Bases:
gemseo_mlearning.adaptive.criterion.MLDataAcquisitionCriterionMinimum distance to the learning dataset.
This infill criterion computes the minimum distance between a new point and the point of the learning dataset, scaled by the maximum distance between two learning points.
# noqa: D205 D212 D415 :param algo_distribution: The distribution of a machine learning algorithm. :param **options: The acquisition criterion options.
- Parameters
algo_distribution (MLRegressorDistribution) –
**options (Any) –
- Return type
None
- check_grad(x_vect, method='FirstOrderFD', step=1e-06, error_max=1e-08)¶
Check the gradients of the function.
- Parameters
x_vect (numpy.ndarray) – The vector at which the function is checked.
method (str) –
The method used to approximate the gradients, either “FirstOrderFD” or “ComplexStep”.
By default it is set to FirstOrderFD.
step (float) –
The step for the approximation of the gradients.
By default it is set to 1e-06.
error_max (float) –
The maximum value of the error.
By default it is set to 1e-08.
- Raises
ValueError – Either if the approximation method is unknown, if the shapes of the analytical and approximated Jacobian matrices are inconsistent or if the analytical gradients are wrong.
- Return type
None
- static concatenate(functions, name, f_type=None)¶
Concatenate functions.
- Parameters
functions (Iterable[MDOFunction]) – The functions to be concatenated.
name (str) – The name of the concatenation function.
f_type (str | None) –
The type of the concatenation function. If None, the function will have no type.
By default it is set to None.
- Returns
The concatenation of the functions.
- Return type
- convex_linear_approx(x_vect, approx_indexes=None, sign_threshold=1e-09)¶
Compute a convex linearization of the function.
\(\newcommand{\xref}{\hat{x}}\newcommand{\dim}{d}\) The convex linearization of a function \(f\) at a point \(\xref\) is defined as
\[\begin{split}\newcommand{\partialder}{\frac{\partial f}{\partial x_i}(\xref)} f(x) \approx f(\xref) + \sum_{\substack{i = 1 \\ \partialder > 0}}^{\dim} \partialder \, (x_i - \xref_i) - \sum_{\substack{i = 1 \\ \partialder < 0}}^{\dim} \partialder \, \xref_i^2 \, \left(\frac{1}{x_i} - \frac{1}{\xref_i}\right).\end{split}\]\(\newcommand{\approxinds}{I}\) Optionally, one may require the convex linearization of \(f\) with respect to a subset of its variables \(x_{i \in \approxinds}\), \(I \subset \{1, \dots, \dim\}\), rather than all of them:
\[\begin{split}f(x) = f(x_{i \in \approxinds}, x_{i \not\in \approxinds}) \approx f(\xref_{i \in \approxinds}, x_{i \not\in \approxinds}) + \sum_{\substack{i \in \approxinds \\ \partialder > 0}} \partialder \, (x_i - \xref_i) - \sum_{\substack{i \in \approxinds \\ \partialder < 0}} \partialder \, \xref_i^2 \, \left(\frac{1}{x_i} - \frac{1}{\xref_i}\right).\end{split}\]- Parameters
x_vect (ndarray) – The input vector at which to build the convex linearization.
approx_indexes (ndarray | None) –
A boolean mask specifying w.r.t. which inputs the function should be approximated. If None, consider all the inputs.
By default it is set to None.
sign_threshold (float) –
The threshold for the sign of the derivatives.
By default it is set to 1e-09.
- Returns
The convex linearization of the function at the given input vector.
- Return type
- static deserialize(file_path)¶
Deserialize a function from a file.
- Parameters
file_path (str | Path) – The path to the file containing the function.
- Returns
The function instance.
- Return type
- evaluate(x_vect)¶
Evaluate the function and store the dimension of the output space.
- Parameters
x_vect (numpy.ndarray) – The value of the inputs of the function.
- Returns
The value of the output of the function.
- Return type
- static filt_0(arr, floor_value=1e-06)¶
Set the non-significant components of a vector to zero.
The component of a vector is non-significant if its absolute value is lower than a threshold.
- Parameters
arr (numpy.ndarray) – The original vector.
floor_value (float) –
The threshold.
By default it is set to 1e-06.
- Returns
The original vector whose non-significant components have been set at zero.
- Return type
- static generate_args(input_dim, args=None)¶
Generate the names of the inputs of the function.
- Parameters
input_dim (int) – The dimension of the input space of the function.
args (Sequence[str] | None) –
The initial names of the inputs of the function. If there is only one name, e.g. [“var”], use this name as a base name and generate the names of the inputs, e.g. [“var!0”, “var!1”, “var!2”] if the dimension of the input space is equal to 3. If None, use “x” as a base name and generate the names of the inputs, i.e. [“x!0”, “x!1”, “x!2”].
By default it is set to None.
- Returns
The names of the inputs of the function.
- Return type
Sequence[str]
- get_indexed_name(index)¶
Return the name of function component.
- has_args()¶
Check if the inputs of the function have names.
- Returns
Whether the inputs of the function have names.
- Return type
- has_dim()¶
Check if the dimension of the output space of the function is defined.
- Returns
Whether the dimension of the output space of the function is defined.
- Return type
- has_expr()¶
Check if the function has an expression.
- Returns
Whether the function has an expression.
- Return type
- has_f_type()¶
Check if the function has a type.
- Returns
Whether the function has a type.
- Return type
- has_jac()¶
Check if the function has an implemented Jacobian function.
- Returns
Whether the function has an implemented Jacobian function.
- Return type
- has_outvars()¶
Check if the outputs of the function have names.
- Returns
Whether the outputs of the function have names.
- Return type
- static init_from_dict_repr(**kwargs)¶
Initialize a new function.
This is typically used for deserialization.
- Parameters
**kwargs – The attributes from
MDOFunction.DICT_REPR_ATTR.- Returns
A function initialized from the provided data.
- Raises
ValueError – If the name of an argument is not in
MDOFunction.DICT_REPR_ATTR.- Return type
- is_constraint()¶
Check if the function is a constraint.
The type of a constraint function is either ‘eq’ or ‘ineq’.
- Returns
Whether the function is a constraint.
- Return type
- linear_approximation(x_vect, name=None, f_type=None, args=None)¶
Compute a first-order Taylor polynomial of the function.
\(\newcommand{\xref}{\hat{x}}\newcommand{\dim}{d}\) The first-order Taylor polynomial of a (possibly vector-valued) function \(f\) at a point \(\xref\) is defined as
\[\newcommand{\partialder}{\frac{\partial f}{\partial x_i}(\xref)} f(x) \approx f(\xref) + \sum_{i = 1}^{\dim} \partialder \, (x_i - \xref_i).\]- Parameters
x_vect (ndarray) – The input vector at which to build the Taylor polynomial.
name (str | None) –
The name of the linear approximation function. If None, create a name from the name of the function.
By default it is set to None.
f_type (str | None) –
The type of the linear approximation function. If None, the function will have no type.
By default it is set to None.
args (Sequence[str] | None) –
The names of the inputs of the linear approximation function, or a name base. If None, use the names of the inputs of the function.
By default it is set to None.
- Returns
The first-order Taylor polynomial of the function at the input vector.
- Raises
AttributeError – If the function does not have a Jacobian function.
- Return type
- offset(value)¶
Add an offset value to the function.
- Parameters
value (ndarray | Number) – The offset value.
- Returns
The offset function as an MDOFunction object.
- Return type
- quadratic_approx(x_vect, hessian_approx, args=None)¶
Build a quadratic approximation of the function at a given point.
The function must be scalar-valued.
\(\newcommand{\xref}{\hat{x}}\newcommand{\dim}{d}\newcommand{ \hessapprox}{\hat{H}}\) For a given approximation \(\hessapprox\) of the Hessian matrix of a function \(f\) at a point \(\xref\), the quadratic approximation of \(f\) is defined as
\[\newcommand{\partialder}{\frac{\partial f}{\partial x_i}(\xref)} f(x) \approx f(\xref) + \sum_{i = 1}^{\dim} \partialder \, (x_i - \xref_i) + \frac{1}{2} \sum_{i = 1}^{\dim} \sum_{j = 1}^{\dim} \hessapprox_{ij} (x_i - \xref_i) (x_j - \xref_j).\]- Parameters
x_vect (ndarray) – The input vector at which to build the quadratic approximation.
hessian_approx (ndarray) – The approximation of the Hessian matrix at this input vector.
args (Sequence[str] | None) –
The names of the inputs of the quadratic approximation function, or a name base. If None, use the ones of the current function.
By default it is set to None.
- Returns
The second-order Taylor polynomial of the function at the given point.
- Raises
ValueError – Either if the approximated Hessian matrix is not square, or if it is not consistent with the dimension of the given point.
AttributeError – If the function does not have an implemented Jacobian function.
- Return type
- static rel_err(a_vect, b_vect, error_max)¶
Compute the 2-norm of the difference between two vectors.
Normalize it with the 2-norm of the reference vector if the latter is greater than the maximal error.
- Parameters
a_vect (numpy.ndarray) – A first vector.
b_vect (numpy.ndarray) – A second vector, used as a reference.
error_max (float) – The maximum value of the error.
- Returns
The difference between two vectors, normalized if required.
- Return type
- restrict(frozen_indexes, frozen_values, input_dim, name=None, f_type=None, expr=None, args=None)¶
Return a restriction of the function
\(\newcommand{\frozeninds}{I}\newcommand{\xfrozen}{\hat{x}}\newcommand{ \frestr}{\hat{f}}\) For a subset \(\approxinds\) of the variables indexes of a function \(f\) to remain frozen at values \(\xfrozen_{i \in \frozeninds}\) the restriction of \(f\) is given by
\[\frestr: x_{i \not\in \approxinds} \longmapsto f(\xref_{i \in \approxinds}, x_{i \not\in \approxinds}).\]- Parameters
frozen_indexes (ndarray) – The indexes of the inputs that will be frozen
frozen_values (ndarray) – The values of the inputs that will be frozen.
input_dim (int) – The dimension of input space of the function before restriction.
name (str | None) –
The name of the function after restriction. If None, create a default name based on the name of the current function and on the argument args.
By default it is set to None.
f_type (str | None) –
The type of the function after restriction. If None, the function will have no type.
By default it is set to None.
expr (str | None) –
The expression of the function after restriction. If None, the function will have no expression.
By default it is set to None.
args (Sequence[str] | None) –
The names of the inputs of the function after restriction. If None, the inputs of the function will have no names.
By default it is set to None.
- Returns
The restriction of the function.
- Return type
- serialize(file_path)¶
Serialize the function and store it in a file.
- Parameters
file_path (str | Path) – The path to the file to store the function.
- Return type
None
- set_pt_from_database(database, design_space, normalize=False, jac=True, x_tolerance=1e-10)¶
Set the original function and Jacobian function from a database.
For a given input vector, the method
MDOFunction.func()will return either the output vector stored in the database if the input vector is present or None. The same for the methodMDOFunction.jac().- Parameters
database (gemseo.algos.database.Database) – The database to read.
design_space (gemseo.algos.design_space.DesignSpace) – The design space used for normalization.
normalize (bool) –
If True, the values of the inputs are unnormalized before call.
By default it is set to False.
jac (bool) –
If True, a Jacobian pointer is also generated.
By default it is set to True.
x_tolerance (float) –
The tolerance on the distance between inputs.
By default it is set to 1e-10.
- Return type
None
- to_dict()¶
Create a dictionary representation of the function.
This is used for serialization. The pointers to the functions are removed.
- COEFF_FORMAT_ND: str = '{: .2e}'¶
The format to be applied to a number when represented in a matrix.
- DICT_REPR_ATTR: list[str] = ['name', 'f_type', 'expr', 'args', 'dim', 'special_repr']¶
The names of the attributes to be serialized.
- algo_distribution: MLRegressorDistribution¶
The distribution of a machine learning algorithm assessor.
- property dim: int¶
The dimension of the output space of the function.
- Raises
TypeError – If the dimension of the output space is not an integer.
- property expr: str¶
The expression of the function, e.g. “2*x”.
- Raises
TypeError – If the expression is not a string.
- property f_type: str¶
The type of the function, among
MDOFunction.AVAILABLE_TYPES.- Raises
ValueError – If the type of function is not available.
- property func: Callable[[numpy.ndarray], numpy.ndarray]¶
The function to be evaluated from a given input vector.
- property jac: Callable[[numpy.ndarray], numpy.ndarray]¶
The Jacobian function to be evaluated from a given input vector.
- Raises
TypeError – If the Jacobian function is not callable.
- last_eval: ndarray | None¶
The value of the function output at the last evaluation.
Noneif it has not yet been evaluated.
- property n_calls: int¶
The number of times the function has been evaluated.
This count is both multiprocess- and multithread-safe, thanks to the locking process used by
MDOFunction.evaluate().