Quick Links

11.3. da.p7core.blackbox

pSeven Core blackbox module.

>>> from da.p7core import blackbox
class da.p7core.blackbox.Blackbox(*iargs, **ikwargs)

Base blackbox class.

To create your own blackbox, inherit from this class and implement two methods: prepare_blackbox() and evaluate(). Then specify an instance of your class as an argument for the blackbox-based method.

See the GTDF vs GTApprox example for a guide on Blackbox class usage.

add_response(name=None)

Initialize a new blackbox response (output component).

Parameters:name (str) – response name (optional)

This method should be called from prepare_blackbox().

Adds an output component to the blackbox. All responses initialized with add_response() are scalar. To create a blackbox with vector output, call add_response() several times.

add_variable(bounds, name=None)

Initialize a new blackbox variable (input component).

Parameters:
  • bounds (tuple(float, float)) – variable bounds (lower, upper)
  • name (str) – variable name (optional)

This method should be called from prepare_blackbox().

Adds an input component to the blackbox. All variables initialized with add_variable() are scalar. To create a blackbox with vector input, call add_variable() several times.

The bounds parameter may be understood (roughly) as specifying the blackbox domain. This is more like a recommendation for the methods using this blackbox: evaluations will not be restricted to the domain, but the blackbox will return the domain bounds from variables_bounds(). To clarify, allowing evaluations outside the domain is needed to support the numerical differentiation on the blackbox bounds.

clear_history()

Clear history.

New in version 4.0.

Removes all evaluations currently stored in the memory history, but does not disable it. For disabling, see disable_history() or set_history().

disable_gradients()

Disable using analytical gradients.

New in version 2.0 Release Candidate 1.

Disables analytical gradients for the blackbox and switches back to using numerical differentiation (see enable_gradients()).

This method should be called from prepare_blackbox(). It is intended to cancel analytical gradients in a new blackbox class inherited from a blackbox with enabled analytical gradients.

disable_history()

Disable saving blackbox evaluations completely.

New in version 2.0 Release Candidate 1.

Disables both memory and file history. Evaluation results will no longer be stored in history or the configured history file (see file in set_history()).

Disabling does not clear current contents of history (see clear_history()).

enable_gradients(order=GTIBB_GRADIENT_F_ORDER)

Enable using analytical gradients.

Parameters:order (GTIBB_GRADIENT_F_ORDER, GTIBB_GRADIENT_X_ORDER) – gradient enumeration order
Returns:None

New in version 1.11.0.

By default, numerical differentiation is used automatically to provide blackbox gradient values. Alternatively, you may provide gradients in evaluate() — see its description for more details. Before that, the blackbox has to be switched to the analytical gradients mode by calling enable_gradients() once upon initialization.

Optional order argument sets the order in which gradient values are included into output; default is F-major.

This method should be called from prepare_blackbox().

enable_history(inmemory=True, file_arg=None, header=True)

Enable saving blackbox evaluations.

Parameters:
  • file_arg (str or file) – write history to file
  • header (bool) – add header with the names of variables and responses to the history file
  • inmemory (bool) – store history in memory (default on)

New in version 1.11.0.

Deprecated since version 4.0: use set_history() instead.

Since version 4.0, replaced by a more convenient set_history() method. See also clear_history() and disable_history().

evaluate(points)

The evaluation method, has to be implemented by user.

Parameters:points (ndarray, 2D) – points to evaluate
Returns:evaluation results
Return type:array-like, 2D

New in version 1.11.0: gradients support.

Changed in version 3.0 Release Candidate 1: points argument is ndarray.

When a blackbox-based method requests values from the blackbox, it sends a small sample to evaluate (a 2D ndarray). The shape of this array is (n, m) where n is the number of points to evaluate and m is the input dimension. The blackbox has to initialize a correct number of input components — see add_variable().

Entire points array is passed to evaluate() which has to process it and return function values (and gradients, if they were enabled in prepare_blackbox()).

Return type has to be a 2D array-like, ndarray is preferred. The shape of the return array depends on the selected gradient calculation method.

If analytical gradients are not enabled (default), numerical differentiation is used automatically. In this case, for a function with m input and k output components, and n points to evaluate, the input and response structures are:

  • input: \([ [x_1, ..., x_m]_1, ..., [x_1, ..., x_m]_n ]\)
  • output: \([ [f_1(\overline{x}_1), ..., f_k(\overline{x}_1)], ..., [f_1(\overline{x}_n), ..., f_k(\overline{x}_n)] ]\)

The blackbox has to initialize a correct number of output components — see add_response(). The return array shape is (n, k), and k is checked against size_f().

If analytical gradients are enabled (see enable_gradients()), gradient values should be appended to each evaluation result, in the selected order, which by default is F-major. Hence the output structure becomes (for the default F-major order):

\[\begin{split}\begin{array}{c} \biggl [ \bigl [f_1(\overline{x}_1), ..., f_k(\overline{x}_1), \frac{\partial{f_1}}{\partial{x_1}}(\overline{x}_1), ..., \frac{\partial{f_1}}{\partial{x_m}}(\overline{x}_1), ..., \frac{\partial{f_k}}{\partial{x_1}}(\overline{x}_1), ..., \frac{\partial{f_k}}{\partial{x_m}}(\overline{x}_1) \bigr], \\ ..., \\ \bigl [f_1(\overline{x}_n), ..., f_k(\overline{x}_n), \frac{\partial{f_1}}{\partial{x_1}}(\overline{x}_n), ..., \frac{\partial{f_1}}{\partial{x_m}}(\overline{x}_n), ..., \frac{\partial{f_k}}{\partial{x_1}}(\overline{x}_n), ..., \frac{\partial{f_k}}{\partial{x_m}}(\overline{x}_n) \bigr ] \biggr] \end{array}\end{split}\]

In this case, the return array shape is (n, s), where s = k + mk, and s is checked against size_full(). If it is not possible to calculate a gradient value, a NaN value should be added instead to preserve the output structure. When a NaN gradient value is encountered in output, gradient calculation falls back to numerical for the current input sample.

Note that the return array is always 2D, even if there is only one response (scalar output) and gradients are not enabled. Never return a 1D array-like (such as a flat list[float]) from evaluate().

gradients_enabled

Check if analytical gradients are enabled for the blackbox.

Type:bool

New in version 1.11.0.

This attribute is True if analytical gradients are enabled for the blackbox.

gradients_order

Check gradient values order.

Type:constant

New in version 1.11.0.

By default, the gradients are in F-major order, and this attribute is GTIBB_GRADIENT_F_ORDER. To set the X-major order, use enable_gradients() with argument GTIBB_GRADIENT_X_ORDER.

history

History of blackbox evaluations stored in memory.

Type:list[list[float]]

New in version 1.11.0.

Stores values of variables and evaluation results. Each element of the top-level list is one evaluated point. Nested list structure is [variables, responses gradients]. Gradients are added only if analytical gradients are enabled, see enable_gradients()).

Note

Memory history is enabled by default, which increases memory consumption. If you implement your own way to save the history of evaluations, always use disable_history(). If there are a lot of evaluations in your problem, consider reconfiguring history to only write it to a file (see set_history()).

numerical_gradient_step

Numerical differentiation step.

Type:float

New in version 1.11.0.

Numerical differentiation step value, default is \(10^{-7}\). To set a different step, use set_numerical_gradient_step().

objectives_names()

Get names of responses.

Returns:list of names
Return type:list[str]

Returns a list containing names of responses. All responses are named; if you do not set a name when adding a response, a unique name is generated automatically (f1, f2 and so on).

prepare_blackbox()

The blackbox initialization method, has to be implemented by user.

Returns:None

This method is called automatically when creating an instance of the Blackbox class, and should never be called directly. It is used to initialize blackbox variables and responses (see add_variable() and add_response()), enable analytical gradients (see enable_gradients()) and configure saving the history of evaluations (see set_history()).

set_history(**kwargs)

Configure saving blackbox evaluations.

Parameters:
  • add_header (bool) – add a header to the history file
  • file (str, file or None) – write history to file
  • memory (bool) – store history in memory

New in version 4.0.

Return values of evaluate() can be saved to memory or to a file on disk. History saving modes are independent: both can be enabled simultaneously so history is saved in memory while also writing to a file. Default configuration is to save history to memory only.

Note

Default configuration increases memory consumption. If you implement your own way to save the history of evaluations, always use disable_history(). If there are a lot of evaluations in your problem, consider reconfiguring history to only write it to a file.

If memory is True, evaluations are saved to history. If False, disables updating history but does not clear it. Re-enabling in case history is not empty appends to existing history; if it is not wanted, call clear_history() first.

The file argument can be a path string or a file-like object (enables writing history to file). Note that the file is opened in append mode. To disable the file history, set file to None. Values in a history file are comma-separated.

If add_header is True, the first line appended to file is a header containing the names of blackbox variables and responses set by add_variable() and add_response(). The header is enabled by default, and can be disabled by setting add_header to False.

set_numerical_gradient_step(value)

Set the numerical differentiation step.

Parameters:value (float) – step value
Returns:None

New in version 1.11.0.

This method should be called from prepare_blackbox().

size_f()

Check the number of blackbox responses initialized by add_response().

Returns:number of responses
Return type:int
size_full()

Check what the evaluation result length should be.

Returns:total number of responses and gradients
Return type:int

New in version 1.11.0.

This method returns the required length of a single evaluation result. It equals the number of responses plus the number of gradients — that is, for a function with m input and k output components, length is k + mk if gradients are enabled (see enable_gradients()); otherwise, size_full() is equal to size_f().

size_x()

Check the number of blackbox variables initialized by add_variable().

Returns:number of variables
Return type:int
variables_bounds()

Check the blackbox bounds.

Returns:blackbox bounds (lower, upper)
Return type:tuple(list[float], list[float])

Returns the bounds for all variables initialized by add_variable(). Returned tuple contains two lists, the first is all lower bounds, the second is upper bounds. Bounds are listed in the same order in which the variables were initialized.

Hint: if you want a per-variable output, use

>>> zip(my_blackbox.variables_bounds())

to get a list of tuples (lower, upper).

variables_names()

Get names of variables.

Returns:list of names
Return type:list[str]

Returns a list containing names of variables. All variables are named; if you do not set a name when adding a variable, a unique name is generated automatically (x1, x2 and so on).

da.p7core.blackbox.GTIBB_GRADIENT_F_ORDER

The constant for F-major gradient matrix order. See enable_gradients() and gradients_order().

da.p7core.blackbox.GTIBB_GRADIENT_X_ORDER

The constant for X-major gradient matrix order. See enable_gradients() and gradients_order().

da.p7core.blackbox.blackbox_callback(*args, **kwds)