mdo_function module¶
Base class to describe a function.
- class gemseo.core.mdofunctions.mdo_function.MDOFunction(func, name, f_type='', jac=None, expr='', args=None, dim=0, outvars=None, force_real=False, special_repr='')[source]¶
Bases:
objectThe standard definition of an array-based function with algebraic operations.
MDOFunctionis the key class to define the objective function, the constraints and the observables of anOptimizationProblem.A
MDOFunctionis initialized from an optional callable and a name, e.g.func = MDOFunction(lambda x: 2*x, "my_function").Note
The callable can be set to
Nonewhen the user does not want to use a callable but a database to browse for the output vector corresponding to an input vector (seeMDOFunction.set_pt_from_database()).The following information can also be provided at initialization:
the type of the function, e.g.
f_type="obj"if the function will be used as an objective (seeMDOFunction.AVAILABLE_TYPESfor the available types),the function computing the Jacobian matrix, e.g.
jac=lambda x: array([2.]),the literal expression to be used for the string representation of the object, e.g.
expr="2*x",the names of the inputs and outputs of the function, e.g.
args=["x"]andoutvars=["y"].
Warning
For the literal expression, do not use “f(x) = 2*x” nor “f = 2*x” but “2*x”. The other elements will be added automatically in the string representation of the function based on the name of the function and the names of its inputs.
After the initialization, all of these arguments can be overloaded with setters, e.g.
MDOFunction.args.The original function and Jacobian function can be accessed with the properties
MDOFunction.funcandMDOFunction.jac.A
MDOFunctionis callable:output = func(array([3.])) # expected: array([6.]).Elementary operations can be performed with
MDOFunctioninstances: addition (func = func1 + func2orfunc = func1 + offset), subtraction (func = func1 - func2orfunc = func1 - offset), multiplication (func = func1 * func2orfunc = func1 * factor) and opposite (func = -func1). It is also possible to build aMDOFunctionas a concatenation ofMDOFunctionobjects:func = MDOFunction.concatenate([func1, func2, func3], "my_func_123").Moreover, a
MDOFunctioncan be approximated with either a first-order or second-order Taylor polynomial at a given input vector, using respectivelyMDOFunction.linear_approximation()andquadratic_approx(); such an approximation is also aMDOFunction.Lastly, the user can check the Jacobian function by means of approximation methods (see
MDOFunction.check_grad()).- Parameters:
func (WrappedFunctionType | None) – The original function to be actually called. If
None, the function will not have an original function.name (str) – The name of the function.
f_type (str) –
The type of the function among
MDOFunction.AVAILABLE_TYPESif any.By default it is set to “”.
jac (WrappedJacobianType | None) – The original Jacobian function to be actually called. If
None, the function will not have an original Jacobian function.expr (str) –
The expression of the function, e.g. “2*x”, if any.
By default it is set to “”.
args (Sequence[str] | None) – The names of the inputs of the function. If
None, the inputs of the function will have no names.dim (int) –
The dimension of the output space of the function. If 0, the dimension of the output space of the function will be deduced from the evaluation of the function.
By default it is set to 0.
outvars (Sequence[str] | None) – The names of the outputs of the function. If
None, the outputs of the function will have no names.force_real (bool) –
Whether to cast the output values to real.
By default it is set to False.
special_repr (str) –
The string representation of the function. If empty, use
default_repr().By default it is set to “”.
- check_grad(x_vect, method='FirstOrderFD', step=1e-06, error_max=1e-08)[source]¶
Check the gradients of the function.
- Parameters:
x_vect (ndarray[Any, dtype[Number]]) – 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)[source]¶
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.
- Returns:
The concatenation of the functions.
- Return type:
- convex_linear_approx(x_vect, approx_indexes=None, sign_threshold=1e-09)[source]¶
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 (ArrayType) – The input vector at which to build the convex linearization.
approx_indexes (ndarray[bool] | None) – A boolean mask specifying w.r.t. which inputs the function should be approximated. If
None, consider all the inputs.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)[source]¶
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:
- static filt_0(arr, floor_value=1e-06)[source]¶
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.
- classmethod generate_args(input_dim, args=None)[source]¶
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. IfNone, use"x"as a base name and generate the names of the inputs, i.e.["x!0", "x!1", "x!2"].
- Returns:
The names of the inputs of the function.
- Return type:
Sequence[str]
- has_args()[source]¶
Check if the inputs of the function have names.
- Returns:
Whether the inputs of the function have names.
- Return type:
- has_dim()[source]¶
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()[source]¶
Check if the function has an expression.
- Returns:
Whether the function has an expression.
- Return type:
- has_f_type()[source]¶
Check if the function has a type.
- Returns:
Whether the function has a type.
- Return type:
- has_jac()[source]¶
Check if the function has an implemented Jacobian function.
- Returns:
Whether the function has an implemented Jacobian function.
- Return type:
- has_outvars()[source]¶
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(**attributes)[source]¶
Initialize a new function.
This is typically used for deserialization.
- Parameters:
**attributes – The values of the serializable attributes listed in
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()[source]¶
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)[source]¶
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 (ArrayType) – 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.f_type (str | None) – The type of the linear approximation function. If
None, the function will have no type.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.
- Returns:
The first-order Taylor polynomial of the function at the input vector.
- Return type:
- quadratic_approx(x_vect, hessian_approx, args=None)[source]¶
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 (ArrayType) – The input vector at which to build the quadratic approximation.
hessian_approx (ArrayType) – 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.
- 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)[source]¶
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.
- restrict(frozen_indexes, frozen_values, input_dim, name=None, f_type=None, expr=None, args=None)[source]¶
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[int]) – The indexes of the inputs that will be frozen
frozen_values (ArrayType) – 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.f_type (str | None) – The type of the function after restriction. If
None, the function will have no type.expr (str | None) – The expression of the function after restriction. If
None, the function will have no expression.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.
- Returns:
The restriction of the function.
- Return type:
- serialize(file_path)[source]¶
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)[source]¶
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 orNone. The same for the methodMDOFunction.jac().- Parameters:
database (Database) – The database to read.
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()[source]¶
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.
- property args: list[str]¶
The names of the inputs of the function.
Use a copy of the original names.
- property f_type: str¶
The type of the function, among
MDOFunction.AVAILABLE_TYPES.
- property func: Callable[[ndarray[Any, dtype[Number]]], Union[ndarray[Any, dtype[Number]], Number]]¶
The function to be evaluated from a given input vector.
- property jac: Callable[[ndarray[Any, dtype[Number]]], ndarray[Any, dtype[Number]]]¶
The Jacobian function to be evaluated from a given input vector.
- last_eval: OutputType | 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().
