gemseo / core / mdofunctions

mdo_function module

Base class to describe a function.

class gemseo.core.mdofunctions.mdo_function.ApplyOperator(other, operator, operator_repr, mdo_function)

Bases: gemseo.core.mdofunctions.mdo_function.MDOFunction

Define addition/subtraction for an MDOFunction.

Supports automatic differentiation if other_f and self have a Jacobian.

Apply an operator to the function and another function.

This operator supports automatic differentiation if both functions have an implemented Jacobian function.

Parameters

• other (MDOFunction | Number) – The other function or number.

• operator (MDOFunction) – The operator as a function pointer.

• operator_repr (str) – The representation of the operator.

• mdo_function (MDOFunction) – The original function.

Raises

TypeError – If other is not an MDOFunction or a Number.

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

MDOFunction

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

MDOFunction

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

MDOFunction

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

numpy.ndarray

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

numpy.ndarray

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.

Parameters

index (int) – The index of the function component.

Returns

The name of the function component.

Return type

str

has_args()

Check if the inputs of the function have names.

Returns

Whether the inputs of the function have names.

Return type

bool

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

bool

has_expr()

Check if the function has an expression.

Returns

Whether the function has an expression.

Return type

bool

has_f_type()

Check if the function has a type.

Returns

Whether the function has a type.

Return type

bool

has_jac()

Check if the function has an implemented Jacobian function.

Returns

Whether the function has an implemented Jacobian function.

Return type

bool

has_outvars()

Check if the outputs of the function have names.

Returns

Whether the outputs of the function have names.

Return type

bool

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

gemseo.core.mdofunctions.mdo_function.MDOFunction

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

bool

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

MDOLinearFunction

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

MDOFunction

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

MDOQuadraticFunction

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

float

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

MDOFunction

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 method MDOFunction.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.

Returns

Some attributes of the function indexed by their names. See MDOFunction.DICT_REPR_ATTR.

Return type

dict[str, str | int | list[str]]

AVAILABLE_TYPES: list[str] = ['obj', 'eq', 'ineq', 'obs']

The available types of function.

COEFF_FORMAT_1D: str = '{:.2e}'

The format to be applied to a number when represented in a vector.

COEFF_FORMAT_ND: str = '{: .2e}'

The format to be applied to a number when represented in a matrix.

DEFAULT_ARGS_BASE: str = 'x'

The default name base for the inputs.

DICT_REPR_ATTR: list[str] = ['name', 'f_type', 'expr', 'args', 'dim', 'special_repr']

The names of the attributes to be serialized.

INDEX_PREFIX: str = '!'

The character used to separate a name base and a prefix, e.g. "x!1.

TYPE_EQ: str = 'eq'

The type of function for equality constraint.

TYPE_INEQ: str = 'ineq'

The type of function for inequality constraint.

TYPE_OBJ: str = 'obj'

The type of function for objective.

TYPE_OBS: str = 'obs'

The type of function for observable.

activate_counters: ClassVar[bool] = True

Whether to count the number of function evaluations.

property args: Sequence[str]

The names of the inputs of the function.

property default_repr: str

The default string representation of the function.

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 expects_normalized_inputs: bool

Whether the functions expect normalized inputs or not.

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.

force_real: bool

Whether to cast the results to real value.

property func: Callable[[numpy.ndarray], numpy.ndarray]

The function to be evaluated from a given input vector.

has_default_name: bool

Whether the name has been set with a default value.

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.

None if 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().

property name: str

The name of the function.

Raises

TypeError – If the name of the function is not a string.

property outvars: Sequence[str]

The names of the outputs of the function.

special_repr: str | None

The string representation of the function overloading its default string ones.

If None, the default string representation is used.

class gemseo.core.mdofunctions.mdo_function.Concatenate(functions, name, f_type=None)

Bases: gemseo.core.mdofunctions.mdo_function.MDOFunction

Wrap the concatenation of a set of 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.

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

MDOFunction

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

MDOFunction

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

MDOFunction

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

numpy.ndarray

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

numpy.ndarray

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.

Parameters

index (int) – The index of the function component.

Returns

The name of the function component.

Return type

str

has_args()

Check if the inputs of the function have names.

Returns

Whether the inputs of the function have names.

Return type

bool

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

bool

has_expr()

Check if the function has an expression.

Returns

Whether the function has an expression.

Return type

bool

has_f_type()

Check if the function has a type.

Returns

Whether the function has a type.

Return type

bool

has_jac()

Check if the function has an implemented Jacobian function.

Returns

Whether the function has an implemented Jacobian function.

Return type

bool

has_outvars()

Check if the outputs of the function have names.

Returns

Whether the outputs of the function have names.

Return type

bool

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

gemseo.core.mdofunctions.mdo_function.MDOFunction

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

bool

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

MDOLinearFunction

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

MDOFunction

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

MDOQuadraticFunction

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

float

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

MDOFunction

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 method MDOFunction.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.

Returns

Some attributes of the function indexed by their names. See MDOFunction.DICT_REPR_ATTR.

Return type

dict[str, str | int | list[str]]

AVAILABLE_TYPES: list[str] = ['obj', 'eq', 'ineq', 'obs']

The available types of function.

COEFF_FORMAT_1D: str = '{:.2e}'

The format to be applied to a number when represented in a vector.

COEFF_FORMAT_ND: str = '{: .2e}'

The format to be applied to a number when represented in a matrix.

DEFAULT_ARGS_BASE: str = 'x'

The default name base for the inputs.

DICT_REPR_ATTR: list[str] = ['name', 'f_type', 'expr', 'args', 'dim', 'special_repr']

The names of the attributes to be serialized.

INDEX_PREFIX: str = '!'

The character used to separate a name base and a prefix, e.g. "x!1.

TYPE_EQ: str = 'eq'

The type of function for equality constraint.

TYPE_INEQ: str = 'ineq'

The type of function for inequality constraint.

TYPE_OBJ: str = 'obj'

The type of function for objective.

TYPE_OBS: str = 'obs'

The type of function for observable.

activate_counters: ClassVar[bool] = True

Whether to count the number of function evaluations.

property args: Sequence[str]

The names of the inputs of the function.

property default_repr: str

The default string representation of the function.

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 expects_normalized_inputs: bool

Whether the functions expect normalized inputs or not.

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.

force_real: bool

Whether to cast the results to real value.

property func: Callable[[numpy.ndarray], numpy.ndarray]

The function to be evaluated from a given input vector.

has_default_name: bool

Whether the name has been set with a default value.

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.

None if 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().

property name: str

The name of the function.

Raises

TypeError – If the name of the function is not a string.

property outvars: Sequence[str]

The names of the outputs of the function.

special_repr: str | None

The string representation of the function overloading its default string ones.

If None, the default string representation is used.

class gemseo.core.mdofunctions.mdo_function.ConvexLinearApprox(x_vect, mdo_function, approx_indexes=None, sign_threshold=1e-09)

Bases: gemseo.core.mdofunctions.mdo_function.MDOFunction

Wrap a convex linearization of the function.

Parameters

• x_vect (ndarray) – The input vector at which to build the convex linearization.

• mdo_function (MDOFunction) – The function to approximate.

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

Raises

• ValueError – If the length of boolean array and the number of inputs of the functions are inconsistent.

• AttributeError – If the function does not have a Jacobian function.

Return type

MDOFunction

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

MDOFunction

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

MDOFunction

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

MDOFunction

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

numpy.ndarray

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

numpy.ndarray

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.

Parameters

index (int) – The index of the function component.

Returns

The name of the function component.

Return type

str

has_args()

Check if the inputs of the function have names.

Returns

Whether the inputs of the function have names.

Return type

bool

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

bool

has_expr()

Check if the function has an expression.

Returns

Whether the function has an expression.

Return type

bool

has_f_type()

Check if the function has a type.

Returns

Whether the function has a type.

Return type

bool

has_jac()

Check if the function has an implemented Jacobian function.

Returns

Whether the function has an implemented Jacobian function.

Return type

bool

has_outvars()

Check if the outputs of the function have names.

Returns

Whether the outputs of the function have names.

Return type

bool

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

gemseo.core.mdofunctions.mdo_function.MDOFunction

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

bool

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

MDOLinearFunction

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

MDOFunction

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

MDOQuadraticFunction

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

float

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

MDOFunction

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 method MDOFunction.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.

Returns

Some attributes of the function indexed by their names. See MDOFunction.DICT_REPR_ATTR.

Return type

dict[str, str | int | list[str]]

AVAILABLE_TYPES: list[str] = ['obj', 'eq', 'ineq', 'obs']

The available types of function.

COEFF_FORMAT_1D: str = '{:.2e}'

The format to be applied to a number when represented in a vector.

COEFF_FORMAT_ND: str = '{: .2e}'

The format to be applied to a number when represented in a matrix.

DEFAULT_ARGS_BASE: str = 'x'

The default name base for the inputs.

DICT_REPR_ATTR: list[str] = ['name', 'f_type', 'expr', 'args', 'dim', 'special_repr']

The names of the attributes to be serialized.

INDEX_PREFIX: str = '!'

The character used to separate a name base and a prefix, e.g. "x!1.

TYPE_EQ: str = 'eq'

The type of function for equality constraint.

TYPE_INEQ: str = 'ineq'

The type of function for inequality constraint.

TYPE_OBJ: str = 'obj'

The type of function for objective.

TYPE_OBS: str = 'obs'

The type of function for observable.

activate_counters: ClassVar[bool] = True

Whether to count the number of function evaluations.

property args: Sequence[str]

The names of the inputs of the function.

property default_repr: str

The default string representation of the function.

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 expects_normalized_inputs: bool

Whether the functions expect normalized inputs or not.

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.

force_real: bool

Whether to cast the results to real value.

property func: Callable[[numpy.ndarray], numpy.ndarray]

The function to be evaluated from a given input vector.

has_default_name: bool

Whether the name has been set with a default value.

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.

None if 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().

property name: str

The name of the function.

Raises

TypeError – If the name of the function is not a string.

property outvars: Sequence[str]

The names of the outputs of the function.

special_repr: str | None

The string representation of the function overloading its default string ones.

If None, the default string representation is used.

class gemseo.core.mdofunctions.mdo_function.FunctionRestriction(frozen_indexes, frozen_values, input_dim, mdo_function, name=None, f_type=None, expr=None, args=None)

Bases: gemseo.core.mdofunctions.mdo_function.MDOFunction

Take an MDOFunction and apply a given restriction to its inputs.

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.

• mdo_function (MDOFunction) – The function to restrict.

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

Raises

ValueError – If the frozen_indexes and the frozen_values arrays do not have the same shape.

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

MDOFunction

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

MDOFunction

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

MDOFunction

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

numpy.ndarray

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

numpy.ndarray

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.

Parameters

index (int) – The index of the function component.

Returns

The name of the function component.

Return type

str

has_args()

Check if the inputs of the function have names.

Returns

Whether the inputs of the function have names.

Return type

bool

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

bool

has_expr()

Check if the function has an expression.

Returns

Whether the function has an expression.

Return type

bool

has_f_type()

Check if the function has a type.

Returns

Whether the function has a type.

Return type

bool

has_jac()

Check if the function has an implemented Jacobian function.

Returns

Whether the function has an implemented Jacobian function.

Return type

bool

has_outvars()

Check if the outputs of the function have names.

Returns

Whether the outputs of the function have names.

Return type

bool

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

gemseo.core.mdofunctions.mdo_function.MDOFunction

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

bool

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

MDOLinearFunction

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

MDOFunction

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

MDOQuadraticFunction

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

float

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

MDOFunction

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 method MDOFunction.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.

Returns

Some attributes of the function indexed by their names. See MDOFunction.DICT_REPR_ATTR.

Return type

dict[str, str | int | list[str]]

AVAILABLE_TYPES: list[str] = ['obj', 'eq', 'ineq', 'obs']

The available types of function.

COEFF_FORMAT_1D: str = '{:.2e}'

The format to be applied to a number when represented in a vector.

COEFF_FORMAT_ND: str = '{: .2e}'

The format to be applied to a number when represented in a matrix.

DEFAULT_ARGS_BASE: str = 'x'

The default name base for the inputs.

DICT_REPR_ATTR: list[str] = ['name', 'f_type', 'expr', 'args', 'dim', 'special_repr']

The names of the attributes to be serialized.

INDEX_PREFIX: str = '!'

The character used to separate a name base and a prefix, e.g. "x!1.

TYPE_EQ: str = 'eq'

The type of function for equality constraint.

TYPE_INEQ: str = 'ineq'

The type of function for inequality constraint.

TYPE_OBJ: str = 'obj'

The type of function for objective.

TYPE_OBS: str = 'obs'

The type of function for observable.

activate_counters: ClassVar[bool] = True

Whether to count the number of function evaluations.

property args: Sequence[str]

The names of the inputs of the function.

property default_repr: str

The default string representation of the function.

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 expects_normalized_inputs: bool

Whether the functions expect normalized inputs or not.

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.

force_real: bool

Whether to cast the results to real value.

property func: Callable[[numpy.ndarray], numpy.ndarray]

The function to be evaluated from a given input vector.

has_default_name: bool

Whether the name has been set with a default value.

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.

None if 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().

property name: str

The name of the function.

Raises

TypeError – If the name of the function is not a string.

property outvars: Sequence[str]

The names of the outputs of the function.

special_repr: str | None

The string representation of the function overloading its default string ones.

If None, the default string representation is used.

class gemseo.core.mdofunctions.mdo_function.MDOFunction(func, name, f_type=None, jac=None, expr=None, args=None, dim=None, outvars=None, force_real=False, special_repr=None)

Bases: object

The standard definition of an array-based function with algebraic operations.

MDOFunction is the key class to define the objective function, the constraints and the observables of an OptimizationProblem.

A MDOFunction is 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 None when the user does not want to use a callable but a database to browse for the output vector corresponding to an input vector (see MDOFunction.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 (see MDOFunction.AVAILABLE_TYPES for 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"] and outvars=["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.func and MDOFunction.jac.

A MDOFunction is callable: output = func(array([3.])) # expected: array([6.]).

Elementary operations can be performed with MDOFunction instances: addition (func = func1 + func2 or func = func1 + offset), subtraction (func = func1 - func2 or func = func1 - offset), multiplication (func = func1 * func2 or func = func1 * factor) and opposite (func = -func1). It is also possible to build a MDOFunction as a concatenation of MDOFunction objects: func = MDOFunction.concatenate([func1, func2, func3], "my_func_123").

Moreover, a MDOFunction can be approximated with either a first-order or second-order Taylor polynomial at a given input vector, using respectively MDOFunction.linear_approximation() and quadratic_approx(); such an approximation is also a MDOFunction.

Lastly, the user can check the Jacobian function by means of approximation methods (see MDOFunction.check_grad()).

Parameters

• func (Callable[[ndarray], ndarray] | 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 | None) –

  The type of the function among MDOFunction.AVAILABLE_TYPES. If None, the function will have no type.

  By default it is set to None.

• jac (Callable[[ndarray], ndarray] | None) –

  The original Jacobian function to be actually called. If None, the function will not have an original Jacobian function.

  By default it is set to None.

• expr (str | None) –

  The expression of the function, e.g. “2*x”. 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. If None, the inputs of the function will have no names.

  By default it is set to None.

• dim (int | None) –

  The dimension of the output space of the function. If None, the dimension of the output space of the function will be deduced from the evaluation of the function.

  By default it is set to None.

• outvars (Sequence[str] | None) –

  The names of the outputs of the function. If None, the outputs of the function will have no names.

  By default it is set to None.

• force_real (bool) –

  If True, cast the results to real value.

  By default it is set to False.

• special_repr (str | None) –

  Overload the default string representation of the function. If None, use the default string representation.

  By default it is set to None.

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

MDOFunction

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

MDOFunction

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

MDOFunction

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

numpy.ndarray

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

numpy.ndarray

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.

Parameters

index (int) – The index of the function component.

Returns

The name of the function component.

Return type

str

has_args()

Check if the inputs of the function have names.

Returns

Whether the inputs of the function have names.

Return type

bool

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

bool

has_expr()

Check if the function has an expression.

Returns

Whether the function has an expression.

Return type

bool

has_f_type()

Check if the function has a type.

Returns

Whether the function has a type.

Return type

bool

has_jac()

Check if the function has an implemented Jacobian function.

Returns

Whether the function has an implemented Jacobian function.

Return type

bool

has_outvars()

Check if the outputs of the function have names.

Returns

Whether the outputs of the function have names.

Return type

bool

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

gemseo.core.mdofunctions.mdo_function.MDOFunction

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

bool

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

MDOLinearFunction

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

MDOFunction

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

MDOQuadraticFunction

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

float

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

MDOFunction

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 method MDOFunction.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.

Returns

Some attributes of the function indexed by their names. See MDOFunction.DICT_REPR_ATTR.

Return type

dict[str, str | int | list[str]]

AVAILABLE_TYPES: list[str] = ['obj', 'eq', 'ineq', 'obs']

The available types of function.

COEFF_FORMAT_1D: str = '{:.2e}'

The format to be applied to a number when represented in a vector.

COEFF_FORMAT_ND: str = '{: .2e}'

The format to be applied to a number when represented in a matrix.

DEFAULT_ARGS_BASE: str = 'x'

The default name base for the inputs.

DICT_REPR_ATTR: list[str] = ['name', 'f_type', 'expr', 'args', 'dim', 'special_repr']

The names of the attributes to be serialized.

INDEX_PREFIX: str = '!'

The character used to separate a name base and a prefix, e.g. "x!1.

TYPE_EQ: str = 'eq'

The type of function for equality constraint.

TYPE_INEQ: str = 'ineq'

The type of function for inequality constraint.

TYPE_OBJ: str = 'obj'

The type of function for objective.

TYPE_OBS: str = 'obs'

The type of function for observable.

activate_counters: ClassVar[bool] = True

Whether to count the number of function evaluations.

property args: Sequence[str]

The names of the inputs of the function.

property default_repr: str

The default string representation of the function.

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 expects_normalized_inputs: bool

Whether the functions expect normalized inputs or not.

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.

force_real: bool

Whether to cast the results to real value.

property func: Callable[[numpy.ndarray], numpy.ndarray]

The function to be evaluated from a given input vector.

has_default_name: bool

Whether the name has been set with a default value.

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.

None if 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().

property name: str

The name of the function.

Raises

TypeError – If the name of the function is not a string.

property outvars: Sequence[str]

The names of the outputs of the function.

special_repr: str | None

The string representation of the function overloading its default string ones.

If None, the default string representation is used.

class gemseo.core.mdofunctions.mdo_function.MDOLinearFunction(coefficients, name, f_type=None, args=None, value_at_zero=0.0)

Bases: gemseo.core.mdofunctions.mdo_function.MDOFunction

Linear multivariate function defined by

• a matrix \(A\) of first-order coefficients \((a_{ij})_{\substack{i = 1, \dots m \\ j = 1, \dots n}}\)

• and a vector \(b\) of zero-order coefficients \((b_i)_{i = 1, \dots m}\)

\[\begin{split}F(x) = Ax + b = \begin{bmatrix} a_{11} & \cdots & a_{1n} \\ \vdots & \ddots & \vdots \\ a_{m1} & \cdots & a_{mn} \end{bmatrix} \begin{bmatrix} x_1 \\ \vdots \\ x_n \end{bmatrix} + \begin{bmatrix} b_1 \\ \vdots \\ b_m \end{bmatrix}.\end{split}\]

Parameters

• coefficients (ndarray) – The coefficients \(A\) of the linear function.

• name (str) – The name of the linear function.

• f_type (str | None) –

  The type of the linear function among MDOFunction.AVAILABLE_TYPES. If None, the linear function will have no type.

  By default it is set to None.

• args (Sequence[str] | None) –

  The names of the inputs of the linear function. If None, the inputs of the linear function will have no names.

  By default it is set to None.

• value_at_zero (ndarray | Number) –

  The value \(b\) of the linear function output at zero.

  By default it is set to 0.0.

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

MDOFunction

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

MDOFunction

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

MDOFunction

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

numpy.ndarray

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

numpy.ndarray

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.

Parameters

index (int) – The index of the function component.

Returns

The name of the function component.

Return type

str

has_args()

Check if the inputs of the function have names.

Returns

Whether the inputs of the function have names.

Return type

bool

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

bool

has_expr()

Check if the function has an expression.

Returns

Whether the function has an expression.

Return type

bool

has_f_type()

Check if the function has a type.

Returns

Whether the function has a type.

Return type

bool

has_jac()

Check if the function has an implemented Jacobian function.

Returns

Whether the function has an implemented Jacobian function.

Return type

bool

has_outvars()

Check if the outputs of the function have names.

Returns

Whether the outputs of the function have names.

Return type

bool

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

gemseo.core.mdofunctions.mdo_function.MDOFunction

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

bool

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

MDOLinearFunction

offset(value)

Add an offset value to the function.

Parameters

value (Number | ndarray) – The offset value.

Returns

The offset function as an MDOFunction object.

Return type

MDOLinearFunction

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

MDOQuadraticFunction

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

float

restrict(frozen_indexes, frozen_values)

Build a restriction of the linear function.

Parameters

• frozen_indexes (numpy.ndarray) – The indexes of the inputs that will be frozen.

• frozen_values (numpy.ndarray) – The values of the inputs that will be frozen.

Returns

The restriction of the linear function.

Raises

ValueError – If the frozen indexes and values have different shapes.

Return type

gemseo.core.mdofunctions.mdo_function.MDOLinearFunction

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 method MDOFunction.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.

Returns

Some attributes of the function indexed by their names. See MDOFunction.DICT_REPR_ATTR.

Return type

dict[str, str | int | list[str]]

AVAILABLE_TYPES: list[str] = ['obj', 'eq', 'ineq', 'obs']

The available types of function.

COEFF_FORMAT_1D: str = '{:.2e}'

The format to be applied to a number when represented in a vector.

COEFF_FORMAT_ND: str = '{: .2e}'

The format to be applied to a number when represented in a matrix.

DEFAULT_ARGS_BASE: str = 'x'

The default name base for the inputs.

DICT_REPR_ATTR: list[str] = ['name', 'f_type', 'expr', 'args', 'dim', 'special_repr']

The names of the attributes to be serialized.

INDEX_PREFIX: str = '!'

The character used to separate a name base and a prefix, e.g. "x!1.

TYPE_EQ: str = 'eq'

The type of function for equality constraint.

TYPE_INEQ: str = 'ineq'

The type of function for inequality constraint.

TYPE_OBJ: str = 'obj'

The type of function for objective.

TYPE_OBS: str = 'obs'

The type of function for observable.

activate_counters: ClassVar[bool] = True

Whether to count the number of function evaluations.

property args: Sequence[str]

The names of the inputs of the function.

property coefficients: numpy.ndarray

The coefficients of the linear function.

This is the matrix \(A\) in the expression \(y=Ax+b\).

Raises

ValueError – If the coefficients are not passed as a 1-dimensional or 2-dimensional ndarray.

property default_repr: str

The default string representation of the function.

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 expects_normalized_inputs: bool

Whether the functions expect normalized inputs or not.

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.

force_real: bool

Whether to cast the results to real value.

property func: Callable[[numpy.ndarray], numpy.ndarray]

The function to be evaluated from a given input vector.

has_default_name: bool

Whether the name has been set with a default value.

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.

None if 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().

property name: str

The name of the function.

Raises

TypeError – If the name of the function is not a string.

property outvars: Sequence[str]

The names of the outputs of the function.

special_repr: str | None

The string representation of the function overloading its default string ones.

If None, the default string representation is used.

property value_at_zero: numpy.ndarray

The value of the function at zero.

This is the vector \(b\) in the expression \(y=Ax+b\).

Raises

ValueError – If the value at zero is neither an ndarray nor a number.

class gemseo.core.mdofunctions.mdo_function.MDOQuadraticFunction(quad_coeffs, name, f_type=None, args=None, linear_coeffs=None, value_at_zero=None)

Bases: gemseo.core.mdofunctions.mdo_function.MDOFunction

Scalar-valued quadratic multivariate function defined by

• a square matrix \(A\) of second-order coefficients \((a_{ij})_{\substack{i = 1, \dots n \\ j = 1, \dots n}}\)

• a vector \(b\) of first-order coefficients \((b_i)_{i = 1, \dots n}\)

• and a scalar zero-order coefficient \(c\)

\[f(x) = c + \sum_{i = 1}^n b_i \, x_i + \sum_{i = 1}^n \sum_{j = 1}^n a_{ij} \, x_i \, x_j.\]

Parameters

• quad_coeffs (ndarray) – The second-order coefficients.

• name (str) – The name of the function.

• f_type (str | None) –

  The type of the linear function among MDOFunction.AVAILABLE_TYPES. If None, the linear function will have no type.

  By default it is set to None.

• args (Sequence[str]) –

  The names of the inputs of the linear function. If None, the inputs of the linear function will have no names.

  By default it is set to None.

• linear_coeffs (ndarray | None) –

  The first-order coefficients. If None, the first-order coefficients will be zero.

  By default it is set to None.

• value_at_zero (float | None) –

  The zero-order coefficient. If None, the value at zero will be zero.

  By default it is set to None.

static build_expression(quad_coeffs, args, linear_coeffs=None, value_at_zero=None)

Build the expression of the quadratic function.

Parameters

• quad_coeffs (ndarray) – The second-order coefficients.

• args (Sequence[str]) – The names of the inputs of the function.

• linear_coeffs (linear_coeffs | None) –

  The first-order coefficients. If None, the first-order coefficients will be zero.

  By default it is set to None.

• value_at_zero (float | None) –

  The zero-order coefficient. If None, the value at zero will be zero.

  By default it is set to None.

Returns

The expression of the quadratic function.

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

MDOFunction

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

MDOFunction

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

MDOFunction

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

numpy.ndarray

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

numpy.ndarray

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.

Parameters

index (int) – The index of the function component.

Returns

The name of the function component.

Return type

str

has_args()

Check if the inputs of the function have names.

Returns

Whether the inputs of the function have names.

Return type

bool

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

bool

has_expr()

Check if the function has an expression.

Returns

Whether the function has an expression.

Return type

bool

has_f_type()

Check if the function has a type.

Returns

Whether the function has a type.

Return type

bool

has_jac()

Check if the function has an implemented Jacobian function.

Returns

Whether the function has an implemented Jacobian function.

Return type

bool

has_outvars()

Check if the outputs of the function have names.

Returns

Whether the outputs of the function have names.

Return type

bool

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

gemseo.core.mdofunctions.mdo_function.MDOFunction

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

bool

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

MDOLinearFunction

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

MDOFunction

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

MDOQuadraticFunction

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

float

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

MDOFunction

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 method MDOFunction.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.

Returns

Some attributes of the function indexed by their names. See MDOFunction.DICT_REPR_ATTR.

Return type

dict[str, str | int | list[str]]

AVAILABLE_TYPES: list[str] = ['obj', 'eq', 'ineq', 'obs']

The available types of function.

COEFF_FORMAT_1D: str = '{:.2e}'

The format to be applied to a number when represented in a vector.

COEFF_FORMAT_ND: str = '{: .2e}'

The format to be applied to a number when represented in a matrix.

DEFAULT_ARGS_BASE: str = 'x'

The default name base for the inputs.

DICT_REPR_ATTR: list[str] = ['name', 'f_type', 'expr', 'args', 'dim', 'special_repr']

The names of the attributes to be serialized.

INDEX_PREFIX: str = '!'

The character used to separate a name base and a prefix, e.g. "x!1.

TYPE_EQ: str = 'eq'

The type of function for equality constraint.

TYPE_INEQ: str = 'ineq'

The type of function for inequality constraint.

TYPE_OBJ: str = 'obj'

The type of function for objective.

TYPE_OBS: str = 'obs'

The type of function for observable.

activate_counters: ClassVar[bool] = True

Whether to count the number of function evaluations.

property args: Sequence[str]

The names of the inputs of the function.

property default_repr: str

The default string representation of the function.

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 expects_normalized_inputs: bool

Whether the functions expect normalized inputs or not.

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.

force_real: bool

Whether to cast the results to real value.

property func: Callable[[numpy.ndarray], numpy.ndarray]

The function to be evaluated from a given input vector.

has_default_name: bool

Whether the name has been set with a default value.

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.

None if it has not yet been evaluated.

property linear_coeffs: numpy.ndarray

The first-order coefficients of the function.

Raises

ValueError – If the number of first-order coefficients is not consistent with the dimension of the input space.

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().

property name: str

The name of the function.

Raises

TypeError – If the name of the function is not a string.

property outvars: Sequence[str]

The names of the outputs of the function.

property quad_coeffs: numpy.ndarray

The second-order coefficients of the function.

Raises

ValueError – If the coefficients are not passed as a 2-dimensional square ndarray.

special_repr: str | None

The string representation of the function overloading its default string ones.

If None, the default string representation is used.

class gemseo.core.mdofunctions.mdo_function.MultiplyOperator(other, mdo_function, inverse=False)

Bases: gemseo.core.mdofunctions.mdo_function.MDOFunction

Wrap the multiplication of an MDOFunction.

Supports automatic differentiation if other_f and self have a Jacobian.

Operator defining the multiplication of the function and another operand.

This operator supports automatic differentiation if the different functions have an implemented Jacobian function.

Parameters

• other (MDOFunction | Number) – The other operand.

• mdo_function (MDOFunction) – The original function.

• inverse (bool) –

  Whether to multiply mdo_function by the inverse of other.

  By default it is set to False.

Raises

TypeError – If the other operand is neither a number nor a MDOFunction.

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

MDOFunction

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

MDOFunction

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

MDOFunction

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

numpy.ndarray

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

numpy.ndarray

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.

Parameters

index (int) – The index of the function component.

Returns

The name of the function component.

Return type

str

has_args()

Check if the inputs of the function have names.

Returns

Whether the inputs of the function have names.

Return type

bool

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

bool

has_expr()

Check if the function has an expression.

Returns

Whether the function has an expression.

Return type

bool

has_f_type()

Check if the function has a type.

Returns

Whether the function has a type.

Return type

bool

has_jac()

Check if the function has an implemented Jacobian function.

Returns

Whether the function has an implemented Jacobian function.

Return type

bool

has_outvars()

Check if the outputs of the function have names.

Returns

Whether the outputs of the function have names.

Return type

bool

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

gemseo.core.mdofunctions.mdo_function.MDOFunction

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

bool

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

MDOLinearFunction

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

MDOFunction

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

MDOQuadraticFunction

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

float

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

MDOFunction

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 method MDOFunction.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.

Returns

Some attributes of the function indexed by their names. See MDOFunction.DICT_REPR_ATTR.

Return type

dict[str, str | int | list[str]]

AVAILABLE_TYPES: list[str] = ['obj', 'eq', 'ineq', 'obs']

The available types of function.

COEFF_FORMAT_1D: str = '{:.2e}'

The format to be applied to a number when represented in a vector.

COEFF_FORMAT_ND: str = '{: .2e}'

The format to be applied to a number when represented in a matrix.

DEFAULT_ARGS_BASE: str = 'x'

The default name base for the inputs.

DICT_REPR_ATTR: list[str] = ['name', 'f_type', 'expr', 'args', 'dim', 'special_repr']

The names of the attributes to be serialized.

INDEX_PREFIX: str = '!'

The character used to separate a name base and a prefix, e.g. "x!1.

TYPE_EQ: str = 'eq'

The type of function for equality constraint.

TYPE_INEQ: str = 'ineq'

The type of function for inequality constraint.

TYPE_OBJ: str = 'obj'

The type of function for objective.

TYPE_OBS: str = 'obs'

The type of function for observable.

activate_counters: ClassVar[bool] = True

Whether to count the number of function evaluations.

property args: Sequence[str]

The names of the inputs of the function.

property default_repr: str

The default string representation of the function.

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 expects_normalized_inputs: bool

Whether the functions expect normalized inputs or not.

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.

force_real: bool

Whether to cast the results to real value.

property func: Callable[[numpy.ndarray], numpy.ndarray]

The function to be evaluated from a given input vector.

has_default_name: bool

Whether the name has been set with a default value.

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.

None if 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().

property name: str

The name of the function.

Raises

TypeError – If the name of the function is not a string.

property outvars: Sequence[str]

The names of the outputs of the function.

special_repr: str | None

The string representation of the function overloading its default string ones.

If None, the default string representation is used.

class gemseo.core.mdofunctions.mdo_function.NotImplementedCallable

Bases: object

A not implemented callable object.

class gemseo.core.mdofunctions.mdo_function.Offset(value, mdo_function)

Bases: gemseo.core.mdofunctions.mdo_function.MDOFunction

Wrap an MDOFunction plus an offset value.

Parameters

• value (ndarray | Number) – The offset value.

• mdo_function (MDOFunction) – The original MDOFunction object.

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

MDOFunction

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

MDOFunction

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

MDOFunction

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

numpy.ndarray

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

numpy.ndarray

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.

Parameters

index (int) – The index of the function component.

Returns

The name of the function component.

Return type

str

has_args()

Check if the inputs of the function have names.

Returns

Whether the inputs of the function have names.

Return type

bool

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

bool

has_expr()

Check if the function has an expression.

Returns

Whether the function has an expression.

Return type

bool

has_f_type()

Check if the function has a type.

Returns

Whether the function has a type.

Return type

bool

has_jac()

Check if the function has an implemented Jacobian function.

Returns

Whether the function has an implemented Jacobian function.

Return type

bool

has_outvars()

Check if the outputs of the function have names.

Returns

Whether the outputs of the function have names.

Return type

bool

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

gemseo.core.mdofunctions.mdo_function.MDOFunction

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

bool

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

MDOLinearFunction

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

MDOFunction

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

MDOQuadraticFunction

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

float

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

MDOFunction

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 method MDOFunction.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.

Returns

Some attributes of the function indexed by their names. See MDOFunction.DICT_REPR_ATTR.

Return type

dict[str, str | int | list[str]]

AVAILABLE_TYPES: list[str] = ['obj', 'eq', 'ineq', 'obs']

The available types of function.

COEFF_FORMAT_1D: str = '{:.2e}'

The format to be applied to a number when represented in a vector.

COEFF_FORMAT_ND: str = '{: .2e}'

The format to be applied to a number when represented in a matrix.

DEFAULT_ARGS_BASE: str = 'x'

The default name base for the inputs.

DICT_REPR_ATTR: list[str] = ['name', 'f_type', 'expr', 'args', 'dim', 'special_repr']

The names of the attributes to be serialized.

INDEX_PREFIX: str = '!'

The character used to separate a name base and a prefix, e.g. "x!1.

TYPE_EQ: str = 'eq'

The type of function for equality constraint.

TYPE_INEQ: str = 'ineq'

The type of function for inequality constraint.

TYPE_OBJ: str = 'obj'

The type of function for objective.

TYPE_OBS: str = 'obs'

The type of function for observable.

activate_counters: ClassVar[bool] = True

Whether to count the number of function evaluations.

property args: Sequence[str]

The names of the inputs of the function.

property default_repr: str

The default string representation of the function.

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 expects_normalized_inputs: bool

Whether the functions expect normalized inputs or not.

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.

force_real: bool

Whether to cast the results to real value.

property func: Callable[[numpy.ndarray], numpy.ndarray]

The function to be evaluated from a given input vector.

has_default_name: bool

Whether the name has been set with a default value.

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.

None if 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().

property name: str

The name of the function.

Raises

TypeError – If the name of the function is not a string.

property outvars: Sequence[str]

The names of the outputs of the function.

special_repr: str | None

The string representation of the function overloading its default string ones.

If None, the default string representation is used.

class gemseo.core.mdofunctions.mdo_function.SetPtFromDatabase(database, design_space, mdo_function, normalize=False, jac=True, x_tolerance=1e-10)

Bases: gemseo.core.mdofunctions.mdo_function.MDOFunction

Set a function and Jacobian from a database.

Parameters

• database (gemseo.algos.database.Database) – The database to read.

• design_space (gemseo.algos.design_space.DesignSpace) – The design space used for normalization.

• mdo_function (gemseo.core.mdofunctions.mdo_function.MDOFunction) – The function where the data from the database will be set.

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

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

MDOFunction

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

MDOFunction

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

MDOFunction

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

numpy.ndarray

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

numpy.ndarray

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.

Parameters

index (int) – The index of the function component.

Returns

The name of the function component.

Return type

str

has_args()

Check if the inputs of the function have names.

Returns

Whether the inputs of the function have names.

Return type

bool

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

bool

has_expr()

Check if the function has an expression.

Returns

Whether the function has an expression.

Return type

bool

has_f_type()

Check if the function has a type.

Returns

Whether the function has a type.

Return type

bool

has_jac()

Check if the function has an implemented Jacobian function.

Returns

Whether the function has an implemented Jacobian function.

Return type

bool

has_outvars()

Check if the outputs of the function have names.

Returns

Whether the outputs of the function have names.

Return type

bool

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

gemseo.core.mdofunctions.mdo_function.MDOFunction

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

bool

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

MDOLinearFunction

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

MDOFunction

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

MDOQuadraticFunction

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

float

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

MDOFunction

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 method MDOFunction.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.

Returns

Some attributes of the function indexed by their names. See MDOFunction.DICT_REPR_ATTR.

Return type

dict[str, str | int | list[str]]

AVAILABLE_TYPES: list[str] = ['obj', 'eq', 'ineq', 'obs']

The available types of function.

COEFF_FORMAT_1D: str = '{:.2e}'

The format to be applied to a number when represented in a vector.

COEFF_FORMAT_ND: str = '{: .2e}'

The format to be applied to a number when represented in a matrix.

DEFAULT_ARGS_BASE: str = 'x'

The default name base for the inputs.

DICT_REPR_ATTR: list[str] = ['name', 'f_type', 'expr', 'args', 'dim', 'special_repr']

The names of the attributes to be serialized.

INDEX_PREFIX: str = '!'

The character used to separate a name base and a prefix, e.g. "x!1.

TYPE_EQ: str = 'eq'

The type of function for equality constraint.

TYPE_INEQ: str = 'ineq'

The type of function for inequality constraint.

TYPE_OBJ: str = 'obj'

The type of function for objective.

TYPE_OBS: str = 'obs'

The type of function for observable.

activate_counters: ClassVar[bool] = True

Whether to count the number of function evaluations.

property args: Sequence[str]

The names of the inputs of the function.

property default_repr: str

The default string representation of the function.

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 expects_normalized_inputs: bool

Whether the functions expect normalized inputs or not.

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.

force_real: bool

Whether to cast the results to real value.

property func: Callable[[numpy.ndarray], numpy.ndarray]

The function to be evaluated from a given input vector.

has_default_name: bool

Whether the name has been set with a default value.

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.

None if 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().

property name: str

The name of the function.

Raises

TypeError – If the name of the function is not a string.

property outvars: Sequence[str]

The names of the outputs of the function.

special_repr: str | None

The string representation of the function overloading its default string ones.

If None, the default string representation is used.