gemseo / core

func_operations module

Functional operations

Classes:

LinearComposition(orig_function, interp_operator)	Compose a function with a linear operator defined by a matrix.
RestrictedFunction(orig_function, ...)	Restrict an MDOFunction to a subset of its input vector.

class gemseo.core.func_operations.LinearComposition(orig_function, interp_operator)

Bases: gemseo.core.mdofunctions.mdo_function.MDOFunction

Compose a function with a linear operator defined by a matrix.

Compute orig_f(Mat.dot(x)).

Constructor.

Parameters

• orig_function – The original function to be restricted.

• interp_operator – The operator matrix, the output of the function will be f(interp_operator.dot(x)).

Attributes:

AVAILABLE_TYPES	The available types of function.
COEFF_FORMAT_1D	The format to be applied to a number when represented in a vector.
COEFF_FORMAT_ND	The format to be applied to a number when represented in a matrix.
DEFAULT_ARGS_BASE	The default name base for the inputs.
DICT_REPR_ATTR	The names of the attributes to be serialized.
INDEX_PREFIX	The character used to separate a name base and a prefix, e.g.
TYPE_EQ	The type of function for equality constraint.
TYPE_INEQ	The type of function for inequality constraint.
TYPE_OBJ	The type of function for objective.
TYPE_OBS	The type of function for observable.
args	The names of the inputs of the function.
default_repr	The default string representation of the function.
dim	The dimension of the output space of the function.
expr	The expression of the function, e.g.
f_type	The type of the function, among AVAILABLE_TYPES.
func	The function to be evaluated from a given input vector.
jac	The Jacobian function to be evaluated from a given input vector.
n_calls	The number of times the function has been evaluated.
name	The name of the function.
outvars	The names of the outputs of the function.

Methods:

check_grad(x_vect[, method, step, error_max])	Check the gradients of the function.
concatenate(functions, name[, f_type])	Concatenate functions.
convex_linear_approx(x_vect[, ...])	Compute a convex linearization of the function.
evaluate(x_vect[, force_real])	Evaluate the function and store the dimension of the output space.
filt_0(arr[, floor_value])	Set the non-significant components of a vector to zero.
generate_args(input_dim[, args])	Generate the names of the inputs of the function.
get_data_dict_repr()	Create a dictionary representation of the function.
has_args()	Check if the inputs of the function have names.
has_dim()	Check if the dimension of the output space of the function is defined.
has_expr()	Check if the function has an expression.
has_f_type()	Check if the function has a type.
has_jac()	Check if the function has an implemented Jacobian function.
has_outvars()	Check if the outputs of the function have names.
init_from_dict_repr(**kwargs)	Initialize a new function.
is_constraint()	Check if the function is a constraint.
linear_approximation(x_vect[, name, f_type, ...])	Compute a first-order Taylor polynomial of the function.
offset(value)	Add an offset value to the function.
quadratic_approx(x_vect, hessian_approx[, args])	Build a quadratic approximation of the function at a given point.
rel_err(a_vect, b_vect, error_max)	Compute the 2-norm of the difference between two vectors.
restrict(frozen_indexes, frozen_values, ...)	Return a restriction of the function
set_pt_from_database(database, design_space)	Set the original function and Jacobian function from a database.

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.

property args

The names of the inputs of the 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[gemseo.core.mdofunctions.mdo_function.MDOFunction]) – The functions to be concatenated.

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

• f_type (Optional[str]) –

  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

gemseo.core.mdofunctions.mdo_function.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 (numpy.ndarray) – The input vector at which to build the convex linearization.

• approx_indexes (Optional[numpy.ndarray]) –

  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

gemseo.core.mdofunctions.mdo_function.MDOFunction

property default_repr

The default string representation of the function.

property dim

The dimension of the output space of the function.

Raises

TypeError – If the dimension of the output space is not an integer.

evaluate(x_vect, force_real=False)

Evaluate the function and store the dimension of the output space.

Parameters

• x_vect (numpy.ndarray) – The value of the inputs of the function.

• force_real (bool) –

  If True, cast the result to real value.

  By default it is set to False.

Returns

The value of the output of the function.

Return type

numpy.ndarray

property expr

The expression of the function, e.g. “2*x”.

Raises

TypeError – If the expression is not a string.

property f_type

The type of the function, among AVAILABLE_TYPES.

Raises

ValueError – If the type of function is not available.

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

property func

The function to be evaluated from a given input vector.

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 (Optional[Sequence[str]]) –

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

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 DICT_REPR_ATTR

Return type

Dict[str, Union[str, int, List[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 DICT_REPR_ATTR.

Returns

A function initialized from the provided data.

Raises

ValueError – If the name of an argument is not in 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

property jac

The Jacobian function to be evaluated from a given input vector.

Raises

TypeError – If the Jacobian function is not callable.

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 (numpy.ndarray) – The input vector at which to build the Taylor polynomial.

• name (Optional[str]) –

  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 (Optional[str]) –

  The type of the linear approximation function. If None, the function will have no type.

  By default it is set to None.

• args (Optional[Sequence[str]]) –

  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

gemseo.core.mdofunctions.mdo_function.MDOLinearFunction

property n_calls

The number of times the function has been evaluated.

This count is both multiprocess- and multithread-safe, thanks to the locking process used by evaluate().

property name

The name of the function.

Raises

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

offset(value)

Add an offset value to the function.

Parameters

value (Union[numpy.ndarray, numbers.Number]) – The offset value.

Returns

The offset function as an MDOFunction object.

Return type

gemseo.core.mdofunctions.mdo_function.MDOFunction

property outvars

The names of the outputs of the function.

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 (numpy.ndarray) – The input vector at which to build the quadratic approximation.

• hessian_approx (numpy.ndarray) – The approximation of the Hessian matrix at this input vector.

• args (Optional[Sequence[str]]) –

  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

gemseo.core.mdofunctions.mdo_function.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 (numpy.ndarray) – The indexes of the inputs that will be frozen

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

• input_dim (int) – The dimension of input space of the function before restriction.

• name (Optional[str]) –

  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 (Optional[str]) –

  The type of the function after restriction. If None, the function will have no type.

  By default it is set to None.

• expr (Optional[str]) –

  The expression of the function after restriction. If None, the function will have no expression.

  By default it is set to None.

• args (Optional[Sequence[str]]) –

  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

gemseo.core.mdofunctions.mdo_function.MDOFunction

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 func() will return either the output vector stored in the database if the input vector is present or None. The same for the method 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

class gemseo.core.func_operations.RestrictedFunction(orig_function, restriction_indices, restriction_values)

Bases: gemseo.core.mdofunctions.mdo_function.MDOFunction

Restrict an MDOFunction to a subset of its input vector.

Fixes the rest of the indices.

Parameters

• orig_function (MDOFunction) – The original function to restrict.

• restriction_indices (ndarray) – The indices array of the input vector to fix.

• restriction_values (ndarray) – The values of the input vector at the indices, ‘restriction_indices’ are set to ‘restriction_values’.

Raises

ValueError – If the shape of the restriction values is not consistent with the shape of the restriction indices.

Return type

None

Attributes:

AVAILABLE_TYPES	The available types of function.
COEFF_FORMAT_1D	The format to be applied to a number when represented in a vector.
COEFF_FORMAT_ND	The format to be applied to a number when represented in a matrix.
DEFAULT_ARGS_BASE	The default name base for the inputs.
DICT_REPR_ATTR	The names of the attributes to be serialized.
INDEX_PREFIX	The character used to separate a name base and a prefix, e.g.
TYPE_EQ	The type of function for equality constraint.
TYPE_INEQ	The type of function for inequality constraint.
TYPE_OBJ	The type of function for objective.
TYPE_OBS	The type of function for observable.
args	The names of the inputs of the function.
default_repr	The default string representation of the function.
dim	The dimension of the output space of the function.
expr	The expression of the function, e.g.
f_type	The type of the function, among AVAILABLE_TYPES.
func	The function to be evaluated from a given input vector.
jac	The Jacobian function to be evaluated from a given input vector.
n_calls	The number of times the function has been evaluated.
name	The name of the function.
outvars	The names of the outputs of the function.

Methods:

check_grad(x_vect[, method, step, error_max])	Check the gradients of the function.
concatenate(functions, name[, f_type])	Concatenate functions.
convex_linear_approx(x_vect[, ...])	Compute a convex linearization of the function.
evaluate(x_vect[, force_real])	Evaluate the function and store the dimension of the output space.
filt_0(arr[, floor_value])	Set the non-significant components of a vector to zero.
generate_args(input_dim[, args])	Generate the names of the inputs of the function.
get_data_dict_repr()	Create a dictionary representation of the function.
has_args()	Check if the inputs of the function have names.
has_dim()	Check if the dimension of the output space of the function is defined.
has_expr()	Check if the function has an expression.
has_f_type()	Check if the function has a type.
has_jac()	Check if the function has an implemented Jacobian function.
has_outvars()	Check if the outputs of the function have names.
init_from_dict_repr(**kwargs)	Initialize a new function.
is_constraint()	Check if the function is a constraint.
linear_approximation(x_vect[, name, f_type, ...])	Compute a first-order Taylor polynomial of the function.
offset(value)	Add an offset value to the function.
quadratic_approx(x_vect, hessian_approx[, args])	Build a quadratic approximation of the function at a given point.
rel_err(a_vect, b_vect, error_max)	Compute the 2-norm of the difference between two vectors.
restrict(frozen_indexes, frozen_values, ...)	Return a restriction of the function
set_pt_from_database(database, design_space)	Set the original function and Jacobian function from a database.

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.

property args

The names of the inputs of the 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[gemseo.core.mdofunctions.mdo_function.MDOFunction]) – The functions to be concatenated.

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

• f_type (Optional[str]) –

  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

gemseo.core.mdofunctions.mdo_function.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 (numpy.ndarray) – The input vector at which to build the convex linearization.

• approx_indexes (Optional[numpy.ndarray]) –

  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

gemseo.core.mdofunctions.mdo_function.MDOFunction

property default_repr

The default string representation of the function.

property dim

The dimension of the output space of the function.

Raises

TypeError – If the dimension of the output space is not an integer.

evaluate(x_vect, force_real=False)

Evaluate the function and store the dimension of the output space.

Parameters

• x_vect (numpy.ndarray) – The value of the inputs of the function.

• force_real (bool) –

  If True, cast the result to real value.

  By default it is set to False.

Returns

The value of the output of the function.

Return type

numpy.ndarray

property expr

The expression of the function, e.g. “2*x”.

Raises

TypeError – If the expression is not a string.

property f_type

The type of the function, among AVAILABLE_TYPES.

Raises

ValueError – If the type of function is not available.

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

property func

The function to be evaluated from a given input vector.

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 (Optional[Sequence[str]]) –

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

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 DICT_REPR_ATTR

Return type

Dict[str, Union[str, int, List[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 DICT_REPR_ATTR.

Returns

A function initialized from the provided data.

Raises

ValueError – If the name of an argument is not in 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

property jac

The Jacobian function to be evaluated from a given input vector.

Raises

TypeError – If the Jacobian function is not callable.

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 (numpy.ndarray) – The input vector at which to build the Taylor polynomial.

• name (Optional[str]) –

  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 (Optional[str]) –

  The type of the linear approximation function. If None, the function will have no type.

  By default it is set to None.

• args (Optional[Sequence[str]]) –

  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

gemseo.core.mdofunctions.mdo_function.MDOLinearFunction

property n_calls

The number of times the function has been evaluated.

This count is both multiprocess- and multithread-safe, thanks to the locking process used by evaluate().

property name

The name of the function.

Raises

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

offset(value)

Add an offset value to the function.

Parameters

value (Union[numpy.ndarray, numbers.Number]) – The offset value.

Returns

The offset function as an MDOFunction object.

Return type

gemseo.core.mdofunctions.mdo_function.MDOFunction

property outvars

The names of the outputs of the function.

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 (numpy.ndarray) – The input vector at which to build the quadratic approximation.

• hessian_approx (numpy.ndarray) – The approximation of the Hessian matrix at this input vector.

• args (Optional[Sequence[str]]) –

  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

gemseo.core.mdofunctions.mdo_function.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 (numpy.ndarray) – The indexes of the inputs that will be frozen

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

• input_dim (int) – The dimension of input space of the function before restriction.

• name (Optional[str]) –

  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 (Optional[str]) –

  The type of the function after restriction. If None, the function will have no type.

  By default it is set to None.

• expr (Optional[str]) –

  The expression of the function after restriction. If None, the function will have no expression.

  By default it is set to None.

• args (Optional[Sequence[str]]) –

  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

gemseo.core.mdofunctions.mdo_function.MDOFunction

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 func() will return either the output vector stored in the database if the input vector is present or None. The same for the method 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