function module¶
Functions, f(x), from disciplines execution¶
Classes:
|
A container object to represent a function in an MDO process. |
|
The link between MDODisciplines and objective functions and constraints is made with MDOFunctionGenerator, which generates MDOFunctions from the disciplines. |
|
Linear multivariate function defined by |
|
Scalar-valued quadratic multivariate function defined by |
A not implemented callable object. |
- class gemseo.core.function.MDOFunction(func, name, f_type=None, jac=None, expr=None, args=None, dim=None, outvars=None, force_real=False, special_repr=None)[source]¶
Bases:
object
A container object to represent a function in an MDO process.
Initializes the function attributes.
- Parameters
func (callable) – the pointer to the function to be actually called
name (str) – the name of the function as a string
f_type (str, optional) – the type of function among (obj, eq, ineq, obs)
jac (callable, optional) – the jacobian
expr (str, optional) – the function expression
args (list(str), optional) – the function arguments
dim (int, optional) – the output dimension
outvars (list(str), optional) – the array of variable names used as inputs of the function
force_real (bool, optional) – if True, cast the results to real value
Attributes:
Accessor to the arguments list.
Accessor to the dimension.
Accessor to the expression.
Accessor to the function type.
Accessor to the func property.
Accessor to the jacobian.
Returns the number of calls to execute() which triggered the _run() multiprocessing safe.
Accessor to the name of the function.
Accessor to the array of input variable names used by the function.
Methods:
apply_operator
(other_f, operator, operator_repr)Defines addition/substraction for MDOFunction Supports automatic differentiation if other_f and self have a Jacobian.
check_grad
(x_vect[, method, step, error_max])Checks the gradient of self.
concatenate
(functions, name[, f_type])Concatenate functions.
convex_linear_approx
(x_vect[, …])Return the convex linearization of the function at a given point
evaluate
(x_vect[, force_real])Evaluate the function.
generate_args
(input_dim[, args])Generate the strings for a function arguments.
Returns a dict representation of self for serialization Pointers to functions are removed.
has_args
()Check if MDOFunction has an args.
has_dim
()Check if MDOFunction has a dimension.
has_expr
()Check if MDOFunction has an expression.
Check if MDOFunction has an type.
has_jac
()Check if MDOFunction has a jacobian.
Check if MDOFunction has an array of input variables.
init_from_dict_repr
(**kwargs)Initalizes a new Function from a data dict typically used for deserialization.
Returns True if self.f_type is eq or ineq.
linear_approximation
(x_vect[, name, f_type, …])Return the first-order Taylor polynomial of the function at a given point
offset
(value)Adds an offset value to the function.
quadratic_approx
(x_vect, hessian_approx[, args])Return a quadratic appproximation of the (scalar-valued) function at a given point
restrict
(frozen_indexes, frozen_values, …)Return a restriction of the function
set_pt_from_database
(database, design_space)self.__call__(x) returns f(x) if x is in the database and self.name in the database keys Idem for jac.
- AVAILABLE_TYPES = ['obj', 'eq', 'ineq', 'obs']¶
- COEFF_FORMAT_1D = '{:.2e}'¶
- COEFF_FORMAT_ND = '{: .2e}'¶
- DEFAULT_ARGS_BASE = 'x'¶
- DICT_REPR_ATTR = ['name', 'f_type', 'expr', 'args', 'dim', 'special_repr']¶
- INDEX_PREFIX = '!'¶
- TYPE_EQ = 'eq'¶
- TYPE_INEQ = 'ineq'¶
- TYPE_OBJ = 'obj'¶
- TYPE_OBS = 'obs'¶
- apply_operator(other_f, operator, operator_repr)[source]¶
Defines addition/substraction for MDOFunction Supports automatic differentiation if other_f and self have a Jacobian.
- Parameters
other_f – param operator:
operator_repr – the representation as a string
operator – the operator as a function pointer
- property args¶
Accessor to the arguments list.
- check_grad(x_vect, method='FirstOrderFD', step=1e-06, error_max=1e-08)[source]¶
Checks the gradient of self.
- Parameters
x_vect (ndarray) – the vector at which the function is checked
method (str, optional) – FirstOrderFD or ComplexStep (Default value = “FirstOrderFD”)
step (float, optional) – the step for approximation (Default value = 1e-6)
error_max (float, optional) – Default value = 1e-8)
- static concatenate(functions, name, f_type=None)[source]¶
Concatenate functions.
- Parameters
functions (list(MDOFunction)) – functions to be concatenated
name (str) – name of the concatenation
f_type (str, optional) – type of the concatenation function
- Returns
concatenation of the functions
- Return type
- convex_linear_approx(x_vect, approx_indexes=None, sign_threshold=1e-09)[source]¶
Return the convex linearization of the function at a given point
\(\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 \(x_{i \in \approxinds} \subset \{x_1, \dots, x_{\dim}\}\) of its variables 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) – point defining the convex linearization
approx_indexes (ndarray, optional) – array of booleans specifying w.r.t. which variables the function should be approximated (by default, all of them)
sign_threshold (float, optional) – threshold for the sign of the derivatives
- Returns
convex linearization of the function at the given point
- Return type
- property default_repr¶
- property dim¶
Accessor to the dimension.
- evaluate(x_vect, force_real=False)[source]¶
Evaluate the function.
- Parameters
x_vect (ndarray) – the function argument
force_real (bool, optional) – if True, cast the results to real value
- Returns
the function value
- Return type
Number or ndarray
- property expr¶
Accessor to the expression.
- property f_type¶
Accessor to the function type.
- property func¶
Accessor to the func property.
- static generate_args(input_dim, args=None)[source]¶
Generate the strings for a function arguments.
- Parameters
input_dim (int) – number of scalar input arguments
args (list(str), optional) – the initial function arguments strings
- Returns
the arguments strings
- Return type
list(str)
- get_data_dict_repr()[source]¶
Returns a dict representation of self for serialization Pointers to functions are removed.
- Returns
a dict with attributes names as keys
- Return type
dict
- has_args()[source]¶
Check if MDOFunction has an args.
- Returns
True if self has an args
- Return type
bool
- has_dim()[source]¶
Check if MDOFunction has a dimension.
- Returns
True if self has a dimension
- Return type
bool
- has_expr()[source]¶
Check if MDOFunction has an expression.
- Returns
True if self has an expression
- Return type
bool
- has_f_type()[source]¶
Check if MDOFunction has an type.
- Returns
True if self has a type
- Return type
bool
- has_jac()[source]¶
Check if MDOFunction has a jacobian.
- Returns
True if self has a jacobian
- Return type
bool
- has_outvars()[source]¶
Check if MDOFunction has an array of input variables.
- Returns
True if self has a dimension
- Return type
bool
- static init_from_dict_repr(**kwargs)[source]¶
Initalizes a new Function from a data dict typically used for deserialization.
- Parameters
kwargs – key value pairs from DICT_REPR_ATTR
- is_constraint()[source]¶
Returns True if self.f_type is eq or ineq.
- Returns
True if and only if the function is a contraint
- Return type
bool
- property jac¶
Accessor to the jacobian.
- linear_approximation(x_vect, name=None, f_type=None, args=None)[source]¶
Return the first-order Taylor polynomial of the function at a given point
\(\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) – point defining the Taylor polynomial
name (str, optional) – name of the linear approximation
f_type (str, optional) – the function type of the linear approximation
args (list(str), optional) – names for each scalar variable, or a name base
- Returns
first-order Taylor polynomial of the function at the given point
- Return type
- property n_calls¶
Returns the number of calls to execute() which triggered the _run() multiprocessing safe.
- property name¶
Accessor to the name of the function.
- offset(value)[source]¶
Adds an offset value to the function.
- Parameters
value (Number or ndarray) – the offset value
- Returns
the offset function as an MDOFunction
- Return type
- property outvars¶
Accessor to the array of input variable names used by the function.
- quadratic_approx(x_vect, hessian_approx, args=None)[source]¶
Return a quadratic appproximation of the (scalar-valued) function at a given point
\(\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) – point defining the Taylor polynomial
hessian_approx (ndarray) – approximation of the Hessian matrix at x_vect
args (list(str), optional) – names for each scalar variable, or a name base
- Returns
second-order Taylor polynomial of the function at the given point
- Return type
- restrict(frozen_indexes, frozen_values, input_dim, name=None, f_type=None, expr=None, args=None)[source]¶
Return a restriction of the function
\(\newcommand{\frozeninds}{I}\newcommand{\xfrozen}{\hat{x}}\newcommand{ \frestr}{\hat{f}}\) For a subset \(\approxinds\) of the variables indexes of a function \(f\) to remain frozen at values \(\xfrozen_{i \in \frozeninds}\) the restriction of \(f\) is given by
\[\frestr: x_{i \not\in \approxinds} \longmapsto f(\xref_{i \in \approxinds}, x_{i \not\in \approxinds}).\]- Parameters
frozen_indexes (ndarray) – indexes of the variables that will be frozen
frozen_values (ndarray) – values of the variables that will be frozen
input_dim (int) – dimension of the function input (before restriction)
name (str, optional) – name of the restriction
f_type (str, optional) – type of the restriction
expr (str, optional) – the expression of the restriction
args (list(str), optional) – arguments names of the restriction
- Returns
restriction of the function
- Return type
- set_pt_from_database(database, design_space, normalize=False, jac=True, x_tolerance=1e-10)[source]¶
self.__call__(x) returns f(x) if x is in the database and self.name in the database keys Idem for jac.
- Parameters
database (Database) – the database to read
design_space (DesignSpace) – the design space used for normalization
normalize (bool, optional) – if True, x_n is unnormalized before call
jac (bool, optional) – if True, a jacobian pointer is also generated
x_tolerance (float, optional) – tolerance on the distance between inputs
- class gemseo.core.function.MDOFunctionGenerator(discipline)[source]¶
Bases:
object
The link between MDODisciplines and objective functions and constraints is made with MDOFunctionGenerator, which generates MDOFunctions from the disciplines.
It uses closures to generate functions instances from a discipline execution.
Constructor.
- Parameters
discipline (MDODiscipline) – the discipline from which the generator builds functions
Methods:
get_function
(input_names_list, output_names_list)Builds a function from a discipline input and output lists.
- get_function(input_names_list, output_names_list, default_inputs=None, differentiable=True)[source]¶
Builds a function from a discipline input and output lists.
- Parameters
input_names_list (list(str)) – names of inputs of the disciplines to be inputs of the function
output_names_list (list(str)) – names of outputs of the disciplines to be returned by the function
default_inputs (dict, optional) – a default inputs dict to eventually overload the discipline’s default inputs when evaluating the discipline
differentiable (bool, optional) – if True then inputs and outputs are added to the list of variables to be differentiated
- Returns
the function
- Return type
- class gemseo.core.function.MDOLinearFunction(coefficients, name, f_type=None, args=None, value_at_zero=0.0)[source]¶
Bases:
gemseo.core.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}\]Initialize the function attributes.
- Parameters
coefficients (ndarray or Number) – coefficients of the linear function
name (str) – the name of the function
f_type (str, optional) – the type of function among (obj, eq, ineq)
args (list(str), optional) – the function arguments
value_at_zero (ndarray or Number, optional) – function value at zero
Attributes:
Accessor to the arguments list.
Get the function coefficients.
Accessor to the dimension.
Accessor to the expression.
Accessor to the function type.
Accessor to the func property.
Accessor to the jacobian.
Returns the number of calls to execute() which triggered the _run() multiprocessing safe.
Accessor to the name of the function.
Accessor to the array of input variable names used by the function.
Get the function value at zero.
Methods:
apply_operator
(other_f, operator, operator_repr)Defines addition/substraction for MDOFunction Supports automatic differentiation if other_f and self have a Jacobian.
check_grad
(x_vect[, method, step, error_max])Checks the gradient of self.
concatenate
(functions, name[, f_type])Concatenate functions.
convex_linear_approx
(x_vect[, …])Return the convex linearization of the function at a given point
evaluate
(x_vect[, force_real])Evaluate the function.
generate_args
(input_dim[, args])Generate the strings for a function arguments.
Returns a dict representation of self for serialization Pointers to functions are removed.
has_args
()Check if MDOFunction has an args.
has_dim
()Check if MDOFunction has a dimension.
has_expr
()Check if MDOFunction has an expression.
Check if MDOFunction has an type.
has_jac
()Check if MDOFunction has a jacobian.
Check if MDOFunction has an array of input variables.
init_from_dict_repr
(**kwargs)Initalizes a new Function from a data dict typically used for deserialization.
Returns True if self.f_type is eq or ineq.
linear_approximation
(x_vect[, name, f_type, …])Return the first-order Taylor polynomial of the function at a given point
offset
(value)Add an offset value to the linear function.
quadratic_approx
(x_vect, hessian_approx[, args])Return a quadratic appproximation of the (scalar-valued) function at a given point
restrict
(frozen_indexes, frozen_values)Build a restriction of the linear function.
set_pt_from_database
(database, design_space)self.__call__(x) returns f(x) if x is in the database and self.name in the database keys Idem for jac.
- AVAILABLE_TYPES = ['obj', 'eq', 'ineq', 'obs']¶
- COEFF_FORMAT_1D = '{:.2e}'¶
- COEFF_FORMAT_ND = '{: .2e}'¶
- DEFAULT_ARGS_BASE = 'x'¶
- DICT_REPR_ATTR = ['name', 'f_type', 'expr', 'args', 'dim', 'special_repr']¶
- INDEX_PREFIX = '!'¶
- TYPE_EQ = 'eq'¶
- TYPE_INEQ = 'ineq'¶
- TYPE_OBJ = 'obj'¶
- TYPE_OBS = 'obs'¶
- apply_operator(other_f, operator, operator_repr)¶
Defines addition/substraction for MDOFunction Supports automatic differentiation if other_f and self have a Jacobian.
- Parameters
other_f – param operator:
operator_repr – the representation as a string
operator – the operator as a function pointer
- property args¶
Accessor to the arguments list.
- check_grad(x_vect, method='FirstOrderFD', step=1e-06, error_max=1e-08)¶
Checks the gradient of self.
- Parameters
x_vect (ndarray) – the vector at which the function is checked
method (str, optional) – FirstOrderFD or ComplexStep (Default value = “FirstOrderFD”)
step (float, optional) – the step for approximation (Default value = 1e-6)
error_max (float, optional) – Default value = 1e-8)
- property coefficients¶
Get the function coefficients. N.B. shall return a 2-dimensional ndarray.
- Returns
function coefficients
- Return type
ndarray
- static concatenate(functions, name, f_type=None)¶
Concatenate functions.
- Parameters
functions (list(MDOFunction)) – functions to be concatenated
name (str) – name of the concatenation
f_type (str, optional) – type of the concatenation function
- Returns
concatenation of the functions
- Return type
- convex_linear_approx(x_vect, approx_indexes=None, sign_threshold=1e-09)¶
Return the convex linearization of the function at a given point
\(\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 \(x_{i \in \approxinds} \subset \{x_1, \dots, x_{\dim}\}\) of its variables 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) – point defining the convex linearization
approx_indexes (ndarray, optional) – array of booleans specifying w.r.t. which variables the function should be approximated (by default, all of them)
sign_threshold (float, optional) – threshold for the sign of the derivatives
- Returns
convex linearization of the function at the given point
- Return type
- property default_repr¶
- property dim¶
Accessor to the dimension.
- evaluate(x_vect, force_real=False)¶
Evaluate the function.
- Parameters
x_vect (ndarray) – the function argument
force_real (bool, optional) – if True, cast the results to real value
- Returns
the function value
- Return type
Number or ndarray
- property expr¶
Accessor to the expression.
- property f_type¶
Accessor to the function type.
- property func¶
Accessor to the func property.
- static generate_args(input_dim, args=None)¶
Generate the strings for a function arguments.
- Parameters
input_dim (int) – number of scalar input arguments
args (list(str), optional) – the initial function arguments strings
- Returns
the arguments strings
- Return type
list(str)
- get_data_dict_repr()¶
Returns a dict representation of self for serialization Pointers to functions are removed.
- Returns
a dict with attributes names as keys
- Return type
dict
- has_args()¶
Check if MDOFunction has an args.
- Returns
True if self has an args
- Return type
bool
- has_dim()¶
Check if MDOFunction has a dimension.
- Returns
True if self has a dimension
- Return type
bool
- has_expr()¶
Check if MDOFunction has an expression.
- Returns
True if self has an expression
- Return type
bool
- has_f_type()¶
Check if MDOFunction has an type.
- Returns
True if self has a type
- Return type
bool
- has_jac()¶
Check if MDOFunction has a jacobian.
- Returns
True if self has a jacobian
- Return type
bool
- has_outvars()¶
Check if MDOFunction has an array of input variables.
- Returns
True if self has a dimension
- Return type
bool
- static init_from_dict_repr(**kwargs)¶
Initalizes a new Function from a data dict typically used for deserialization.
- Parameters
kwargs – key value pairs from DICT_REPR_ATTR
- is_constraint()¶
Returns True if self.f_type is eq or ineq.
- Returns
True if and only if the function is a contraint
- Return type
bool
- property jac¶
Accessor to the jacobian.
- linear_approximation(x_vect, name=None, f_type=None, args=None)¶
Return the first-order Taylor polynomial of the function at a given point
\(\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) – point defining the Taylor polynomial
name (str, optional) – name of the linear approximation
f_type (str, optional) – the function type of the linear approximation
args (list(str), optional) – names for each scalar variable, or a name base
- Returns
first-order Taylor polynomial of the function at the given point
- Return type
- property n_calls¶
Returns the number of calls to execute() which triggered the _run() multiprocessing safe.
- property name¶
Accessor to the name of the function.
- offset(value)[source]¶
Add an offset value to the linear function.
- Parameters
value (Number or ndarray) – the offset value
- Returns
the offset function
- Return type
- property outvars¶
Accessor to the array of input variable names used by the function.
- quadratic_approx(x_vect, hessian_approx, args=None)¶
Return a quadratic appproximation of the (scalar-valued) function at a given point
\(\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) – point defining the Taylor polynomial
hessian_approx (ndarray) – approximation of the Hessian matrix at x_vect
args (list(str), optional) – names for each scalar variable, or a name base
- Returns
second-order Taylor polynomial of the function at the given point
- Return type
- restrict(frozen_indexes, frozen_values)[source]¶
Build a restriction of the linear function.
- Parameters
frozen_indexes (ndarray) – indexes of the variables that will be frozen
frozen_values (ndarray) – values of the variables that will be frozen
- Returns
the restriction of the linear function
- Return type
- set_pt_from_database(database, design_space, normalize=False, jac=True, x_tolerance=1e-10)¶
self.__call__(x) returns f(x) if x is in the database and self.name in the database keys Idem for jac.
- Parameters
database (Database) – the database to read
design_space (DesignSpace) – the design space used for normalization
normalize (bool, optional) – if True, x_n is unnormalized before call
jac (bool, optional) – if True, a jacobian pointer is also generated
x_tolerance (float, optional) – tolerance on the distance between inputs
- property value_at_zero¶
Get the function value at zero. N.B. shall return a 1-dimensional ndarray.
- Returns
function value at zero
- Return type
ndarray
- class gemseo.core.function.MDOQuadraticFunction(quad_coeffs, name, f_type=None, args=None, linear_coeffs=None, value_at_zero=None)[source]¶
Bases:
gemseo.core.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.\]Initialize a quadratic function.
- Parameters
quad_coeffs (ndarray) – second-order coefficients
name (str) – name of the function
f_type (str, optional) – type of the function
args (list(str), optional) – arguments names of the function
linear_coeffs (ndarray, optional) – first-order coefficients
value_at_zero (float, optional) – zero-order coefficient
Attributes:
Accessor to the arguments list.
Accessor to the dimension.
Accessor to the expression.
Accessor to the function type.
Accessor to the func property.
Accessor to the jacobian.
Get the function first-order coefficients N.B.
Returns the number of calls to execute() which triggered the _run() multiprocessing safe.
Accessor to the name of the function.
Accessor to the array of input variable names used by the function.
Get the function second-order coefficients N.B.
Methods:
apply_operator
(other_f, operator, operator_repr)Defines addition/substraction for MDOFunction Supports automatic differentiation if other_f and self have a Jacobian.
build_expression
(quad_coeffs, args[, …])Return the expression of the quadratic function.
check_grad
(x_vect[, method, step, error_max])Checks the gradient of self.
concatenate
(functions, name[, f_type])Concatenate functions.
convex_linear_approx
(x_vect[, …])Return the convex linearization of the function at a given point
evaluate
(x_vect[, force_real])Evaluate the function.
generate_args
(input_dim[, args])Generate the strings for a function arguments.
Returns a dict representation of self for serialization Pointers to functions are removed.
has_args
()Check if MDOFunction has an args.
has_dim
()Check if MDOFunction has a dimension.
has_expr
()Check if MDOFunction has an expression.
Check if MDOFunction has an type.
has_jac
()Check if MDOFunction has a jacobian.
Check if MDOFunction has an array of input variables.
init_from_dict_repr
(**kwargs)Initalizes a new Function from a data dict typically used for deserialization.
Returns True if self.f_type is eq or ineq.
linear_approximation
(x_vect[, name, f_type, …])Return the first-order Taylor polynomial of the function at a given point
offset
(value)Adds an offset value to the function.
quadratic_approx
(x_vect, hessian_approx[, args])Return a quadratic appproximation of the (scalar-valued) function at a given point
restrict
(frozen_indexes, frozen_values, …)Return a restriction of the function
set_pt_from_database
(database, design_space)self.__call__(x) returns f(x) if x is in the database and self.name in the database keys Idem for jac.
- AVAILABLE_TYPES = ['obj', 'eq', 'ineq', 'obs']¶
- COEFF_FORMAT_1D = '{:.2e}'¶
- COEFF_FORMAT_ND = '{: .2e}'¶
- DEFAULT_ARGS_BASE = 'x'¶
- DICT_REPR_ATTR = ['name', 'f_type', 'expr', 'args', 'dim', 'special_repr']¶
- INDEX_PREFIX = '!'¶
- TYPE_EQ = 'eq'¶
- TYPE_INEQ = 'ineq'¶
- TYPE_OBJ = 'obj'¶
- TYPE_OBS = 'obs'¶
- apply_operator(other_f, operator, operator_repr)¶
Defines addition/substraction for MDOFunction Supports automatic differentiation if other_f and self have a Jacobian.
- Parameters
other_f – param operator:
operator_repr – the representation as a string
operator – the operator as a function pointer
- property args¶
Accessor to the arguments list.
- static build_expression(quad_coeffs, args, linear_coeffs=None, value_at_zero=None)[source]¶
Return the expression of the quadratic function.
- Parameters
quad_coeffs (ndarray) – second-order coefficients
args (list(str)) – arguments names of the function
linear_coeffs (ndarray, optional) – first-order coefficients
value_at_zero (float, optional) – zero-order coefficient
- check_grad(x_vect, method='FirstOrderFD', step=1e-06, error_max=1e-08)¶
Checks the gradient of self.
- Parameters
x_vect (ndarray) – the vector at which the function is checked
method (str, optional) – FirstOrderFD or ComplexStep (Default value = “FirstOrderFD”)
step (float, optional) – the step for approximation (Default value = 1e-6)
error_max (float, optional) – Default value = 1e-8)
- static concatenate(functions, name, f_type=None)¶
Concatenate functions.
- Parameters
functions (list(MDOFunction)) – functions to be concatenated
name (str) – name of the concatenation
f_type (str, optional) – type of the concatenation function
- Returns
concatenation of the functions
- Return type
- convex_linear_approx(x_vect, approx_indexes=None, sign_threshold=1e-09)¶
Return the convex linearization of the function at a given point
\(\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 \(x_{i \in \approxinds} \subset \{x_1, \dots, x_{\dim}\}\) of its variables 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) – point defining the convex linearization
approx_indexes (ndarray, optional) – array of booleans specifying w.r.t. which variables the function should be approximated (by default, all of them)
sign_threshold (float, optional) – threshold for the sign of the derivatives
- Returns
convex linearization of the function at the given point
- Return type
- property default_repr¶
- property dim¶
Accessor to the dimension.
- evaluate(x_vect, force_real=False)¶
Evaluate the function.
- Parameters
x_vect (ndarray) – the function argument
force_real (bool, optional) – if True, cast the results to real value
- Returns
the function value
- Return type
Number or ndarray
- property expr¶
Accessor to the expression.
- property f_type¶
Accessor to the function type.
- property func¶
Accessor to the func property.
- static generate_args(input_dim, args=None)¶
Generate the strings for a function arguments.
- Parameters
input_dim (int) – number of scalar input arguments
args (list(str), optional) – the initial function arguments strings
- Returns
the arguments strings
- Return type
list(str)
- get_data_dict_repr()¶
Returns a dict representation of self for serialization Pointers to functions are removed.
- Returns
a dict with attributes names as keys
- Return type
dict
- has_args()¶
Check if MDOFunction has an args.
- Returns
True if self has an args
- Return type
bool
- has_dim()¶
Check if MDOFunction has a dimension.
- Returns
True if self has a dimension
- Return type
bool
- has_expr()¶
Check if MDOFunction has an expression.
- Returns
True if self has an expression
- Return type
bool
- has_f_type()¶
Check if MDOFunction has an type.
- Returns
True if self has a type
- Return type
bool
- has_jac()¶
Check if MDOFunction has a jacobian.
- Returns
True if self has a jacobian
- Return type
bool
- has_outvars()¶
Check if MDOFunction has an array of input variables.
- Returns
True if self has a dimension
- Return type
bool
- static init_from_dict_repr(**kwargs)¶
Initalizes a new Function from a data dict typically used for deserialization.
- Parameters
kwargs – key value pairs from DICT_REPR_ATTR
- is_constraint()¶
Returns True if self.f_type is eq or ineq.
- Returns
True if and only if the function is a contraint
- Return type
bool
- property jac¶
Accessor to the jacobian.
- linear_approximation(x_vect, name=None, f_type=None, args=None)¶
Return the first-order Taylor polynomial of the function at a given point
\(\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) – point defining the Taylor polynomial
name (str, optional) – name of the linear approximation
f_type (str, optional) – the function type of the linear approximation
args (list(str), optional) – names for each scalar variable, or a name base
- Returns
first-order Taylor polynomial of the function at the given point
- Return type
- property linear_coeffs¶
Get the function first-order coefficients N.B. shall return a 1-dimensional ndarray.
- Returns
function first-order coefficients
- Return type
ndarray
- property n_calls¶
Returns the number of calls to execute() which triggered the _run() multiprocessing safe.
- property name¶
Accessor to the name of the function.
- offset(value)¶
Adds an offset value to the function.
- Parameters
value (Number or ndarray) – the offset value
- Returns
the offset function as an MDOFunction
- Return type
- property outvars¶
Accessor to the array of input variable names used by the function.
- property quad_coeffs¶
Get the function second-order coefficients N.B. shall return a 2-dimensional ndarray.
- Returns
function second-order coefficients
- Return type
ndarray
- quadratic_approx(x_vect, hessian_approx, args=None)¶
Return a quadratic appproximation of the (scalar-valued) function at a given point
\(\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) – point defining the Taylor polynomial
hessian_approx (ndarray) – approximation of the Hessian matrix at x_vect
args (list(str), optional) – names for each scalar variable, or a name base
- Returns
second-order Taylor polynomial of the function at the given point
- Return type
- restrict(frozen_indexes, frozen_values, input_dim, name=None, f_type=None, expr=None, args=None)¶
Return a restriction of the function
\(\newcommand{\frozeninds}{I}\newcommand{\xfrozen}{\hat{x}}\newcommand{ \frestr}{\hat{f}}\) For a subset \(\approxinds\) of the variables indexes of a function \(f\) to remain frozen at values \(\xfrozen_{i \in \frozeninds}\) the restriction of \(f\) is given by
\[\frestr: x_{i \not\in \approxinds} \longmapsto f(\xref_{i \in \approxinds}, x_{i \not\in \approxinds}).\]- Parameters
frozen_indexes (ndarray) – indexes of the variables that will be frozen
frozen_values (ndarray) – values of the variables that will be frozen
input_dim (int) – dimension of the function input (before restriction)
name (str, optional) – name of the restriction
f_type (str, optional) – type of the restriction
expr (str, optional) – the expression of the restriction
args (list(str), optional) – arguments names of the restriction
- Returns
restriction of the function
- Return type
- set_pt_from_database(database, design_space, normalize=False, jac=True, x_tolerance=1e-10)¶
self.__call__(x) returns f(x) if x is in the database and self.name in the database keys Idem for jac.
- Parameters
database (Database) – the database to read
design_space (DesignSpace) – the design space used for normalization
normalize (bool, optional) – if True, x_n is unnormalized before call
jac (bool, optional) – if True, a jacobian pointer is also generated
x_tolerance (float, optional) – tolerance on the distance between inputs