secml.optim.function

CFunction

class secml.optim.function.c_function.CFunction(fun=None, gradient=None, n_dim=None)[source]

Bases: secml.core.c_creator.CCreator

Class that handles generic mathematical functions.

Either a function or its gradient can be passed in.

Number of expected space dimensions can be specified if applicable.

Parameters
funcallable or None

Any python callable. Required if gradient is None.

gradientcallable or None

Any python callable that returns the gradient of fun. Required if fun is None.

n_dimint or None, optional

Expected space dimensions.

Attributes
class_type‘generic’

Defines class type.

Methods

approx_fprime(self, x, epsilon, *args, **kwargs)

Finite-difference approximation of the gradient of a scalar function.

check_grad(self, x, epsilon, *args, **kwargs)

Check the correctness of a gradient function by comparing

copy(self)

Returns a shallow copy of current class.

create([class_item])

This method creates an instance of a class with given type.

deepcopy(self)

Returns a deep copy of current class.

fun(self, x, *args, **kwargs)

Evaluates function on x.

fun_ndarray(self, x, *args, **kwargs)

Evaluates function on x (ndarray).

get_class_from_type(class_type)

Return the class associated with input type.

get_params(self)

Returns the dictionary of class hyperparameters.

get_state(self, **kwargs)

Returns the object state dictionary.

get_subclasses()

Get all the subclasses of the calling class.

gradient(self, x, *args, **kwargs)

Evaluates gradient of function at point x.

gradient_ndarray(self, x, *args, **kwargs)

Evaluates gradient of function at point x (ndarray).

has_fun(self)

True if function has been set.

has_gradient(self)

True if gradient has been set.

is_equal(self, x, val[, tol])

Evaluates if function value is close to val within tol.

list_class_types()

This method lists all types of available subclasses of calling one.

load(path)

Loads object from file.

load_state(self, path)

Sets the object state from file.

reset_eval(self)

Reset the count of function and gradient of function evaluations.

save(self, path)

Save class object to file.

save_state(self, path, **kwargs)

Store the object state to file.

set(self, param_name, param_value[, copy])

Set a parameter of the class.

set_params(self, params_dict[, copy])

Set all parameters passed as a dictionary {key: value}.

set_state(self, state_dict[, copy])

Sets the object state using input dictionary.

timed([msg])

Timer decorator.

approx_fprime(self, x, epsilon, *args, **kwargs)[source]

Finite-difference approximation of the gradient of a scalar function.

Wrapper for scipy function scipy.optimize.approx_fprime.

Parameters
xCArray

The flat dense vector with the point at which to determine the gradient of fun.

epsilonscalar or CArray

Increment of x to use for determining the function gradient. If a scalar, uses the same finite difference delta for all partial derivatives. If an array, should contain one value per element of x.

args, kwargs

Any other arguments that are to be passed to fun.

Returns
gradCArray

The gradient of fun at x.

See also

check_grad

Check correctness of function gradient against approx_fprime.

Notes

The function gradient is determined by the forward finite difference formula:

          fun(xk[i] + epsilon[i]) - f(xk[i])
fun'[i] = -----------------------------------
                     epsilon[i]

The main use of approx_fprime is to determine numerically the Jacobian of a function.

Examples

>>> from secml.array import CArray
>>> from secml.optim.function import CFunction
>>> from secml.core.constants import eps
>>> def func(x, c0, c1):
...     "Coordinate vector `x` should be an array of size two."
...     return c0 * x[0]**2 + c1*x[1]**2
>>> c0, c1 = (1, 200)
>>> CFunction(func).approx_fprime(CArray.ones(2), [eps, (200 ** 0.5) * eps], c0, c1=c1)
CArray(2,)(dense: [  2.       400.000042])
check_grad(self, x, epsilon, *args, **kwargs)[source]
Check the correctness of a gradient function by comparing

it against a (forward) finite-difference approximation of the gradient.

Parameters
xCArray

Flat dense pattern to check function gradient against forward difference approximation of function gradient.

epsilonscalar or CArray

Increment of x to use for determining the function gradient. If a scalar, uses the same finite difference delta for all partial derivatives. If an array, should contain one value per element of x.

args, kwargs

Extra arguments passed to fun and fprime.

Returns
errfloat

The square root of the sum of squares (i.e. the l2-norm) of the difference between fprime(x, *args) and the finite difference approximation of fprime at the points x.

See also

approx_fprime

Finite-difference approximation of the gradient of a scalar function.

Notes

epsilon is the only keyword argument accepted by the function. Any other optional argument for fun and fprime should be passed as non-keyword.

Examples

>>> from secml.optim.function import CFunction
>>> from secml.array import CArray
>>> def func(x):
...     return x[0].item()**2 - 0.5 * x[1].item()**3
>>> def grad(x):
...     return CArray([2 * x[0].item(), -1.5 * x[1].item()**2])
>>> fun = CFunction(func, grad)
>>> fun.check_grad(CArray([1.5, -1.5]), epsilon=1e-8)
7.817837928307533e-08
fun(self, x, *args, **kwargs)[source]

Evaluates function on x.

Parameters
xCArray

Argument of fun.

args, kwargs

Other optional parameter of the function.

Returns
out_funscalar or CArray

Function output, scalar or CArray depending on the inner function.

fun_ndarray(self, x, *args, **kwargs)[source]

Evaluates function on x (ndarray).

Parameters
xnp.ndarray

Argument of fun as ndarray.

args, kwargs

Other optional parameter of the function.

Returns
out_funscalar or CArray

Function output, scalar or CArray depending on the inner function.

gradient(self, x, *args, **kwargs)[source]

Evaluates gradient of function at point x.

Parameters
xCArray

Argument of gradient. Single point.

args, kwargs

Other optional parameter of the function.

Returns
out_gradCArray

Array with gradient output.

gradient_ndarray(self, x, *args, **kwargs)[source]

Evaluates gradient of function at point x (ndarray).

Parameters
xndarray

Argument of gradient.

args, kwargs

Other optional parameter of the function.

Returns
out_gradndarray

Array with gradient output.

has_fun(self)[source]

True if function has been set.

has_gradient(self)[source]

True if gradient has been set.

is_equal(self, x, val, tol=1e-06)[source]

Evaluates if function value is close to val within tol.

property n_dim

Returns the expected function’s space dimensions.

property n_fun_eval

Returns the number of function evaluations.

property n_grad_eval

Returns the number of gradient evaluations.

reset_eval(self)[source]

Reset the count of function and gradient of function evaluations.

CFunctionLinear

class secml.optim.function.c_function_linear.CFunctionLinear(b, c)[source]

Bases: secml.optim.function.c_function.CFunction

Implements linear functions of the form:

b’ x + c = 0

Attributes
class_type‘linear’

Defines class type.

Methods

approx_fprime(self, x, epsilon, *args, **kwargs)

Finite-difference approximation of the gradient of a scalar function.

check_grad(self, x, epsilon, *args, **kwargs)

Check the correctness of a gradient function by comparing

copy(self)

Returns a shallow copy of current class.

create([class_item])

This method creates an instance of a class with given type.

deepcopy(self)

Returns a deep copy of current class.

fun(self, x, *args, **kwargs)

Evaluates function on x.

fun_ndarray(self, x, *args, **kwargs)

Evaluates function on x (ndarray).

get_class_from_type(class_type)

Return the class associated with input type.

get_params(self)

Returns the dictionary of class hyperparameters.

get_state(self, **kwargs)

Returns the object state dictionary.

get_subclasses()

Get all the subclasses of the calling class.

gradient(self, x, *args, **kwargs)

Evaluates gradient of function at point x.

gradient_ndarray(self, x, *args, **kwargs)

Evaluates gradient of function at point x (ndarray).

has_fun(self)

True if function has been set.

has_gradient(self)

True if gradient has been set.

is_equal(self, x, val[, tol])

Evaluates if function value is close to val within tol.

list_class_types()

This method lists all types of available subclasses of calling one.

load(path)

Loads object from file.

load_state(self, path)

Sets the object state from file.

reset_eval(self)

Reset the count of function and gradient of function evaluations.

save(self, path)

Save class object to file.

save_state(self, path, **kwargs)

Store the object state to file.

set(self, param_name, param_value[, copy])

Set a parameter of the class.

set_params(self, params_dict[, copy])

Set all parameters passed as a dictionary {key: value}.

set_state(self, state_dict[, copy])

Sets the object state using input dictionary.

timed([msg])

Timer decorator.

CFunctionQuadratic

class secml.optim.function.c_function_quadratic.CFunctionQuadratic(A, b, c)[source]

Bases: secml.optim.function.c_function.CFunction

Implements quadratic functions of the form:

x’ A x + b’ x + c = 0

Attributes
class_type‘quadratic’

Defines class type.

Methods

approx_fprime(self, x, epsilon, *args, **kwargs)

Finite-difference approximation of the gradient of a scalar function.

check_grad(self, x, epsilon, *args, **kwargs)

Check the correctness of a gradient function by comparing

copy(self)

Returns a shallow copy of current class.

create([class_item])

This method creates an instance of a class with given type.

deepcopy(self)

Returns a deep copy of current class.

fun(self, x, *args, **kwargs)

Evaluates function on x.

fun_ndarray(self, x, *args, **kwargs)

Evaluates function on x (ndarray).

get_class_from_type(class_type)

Return the class associated with input type.

get_params(self)

Returns the dictionary of class hyperparameters.

get_state(self, **kwargs)

Returns the object state dictionary.

get_subclasses()

Get all the subclasses of the calling class.

gradient(self, x, *args, **kwargs)

Evaluates gradient of function at point x.

gradient_ndarray(self, x, *args, **kwargs)

Evaluates gradient of function at point x (ndarray).

has_fun(self)

True if function has been set.

has_gradient(self)

True if gradient has been set.

is_equal(self, x, val[, tol])

Evaluates if function value is close to val within tol.

list_class_types()

This method lists all types of available subclasses of calling one.

load(path)

Loads object from file.

load_state(self, path)

Sets the object state from file.

reset_eval(self)

Reset the count of function and gradient of function evaluations.

save(self, path)

Save class object to file.

save_state(self, path, **kwargs)

Store the object state to file.

set(self, param_name, param_value[, copy])

Set a parameter of the class.

set_params(self, params_dict[, copy])

Set all parameters passed as a dictionary {key: value}.

set_state(self, state_dict[, copy])

Sets the object state using input dictionary.

timed([msg])

Timer decorator.

CFunctionRosenbrock

class secml.optim.function.c_function_rosenbrock.CFunctionRosenbrock[source]

Bases: secml.optim.function.c_function.CFunction

The Rosenbrock function.

Non-convex function introduced by Howard H. Rosenbrock in 1960. [1] Also known as Rosenbrock’s valley or Rosenbrock’s banana function.

Global minimum f(x) = 0 @ x = (1, 1, …., 1).

Given by: .. math:

f(x) = \sum^{n-1}_{i=1} [100 * {(x_{i+1} - x_i^2)}^2 + (x_i - 1)^2]

References

1

Rosenbrock, HoHo. “An automatic method for finding the greatest or least value of a function.” The Computer Journal 3.3 (1960): 175-184.

Attributes
class_type‘rosenbrock’

Defines class type.

Methods

approx_fprime(self, x, epsilon, *args, **kwargs)

Finite-difference approximation of the gradient of a scalar function.

check_grad(self, x, epsilon, *args, **kwargs)

Check the correctness of a gradient function by comparing

copy(self)

Returns a shallow copy of current class.

create([class_item])

This method creates an instance of a class with given type.

deepcopy(self)

Returns a deep copy of current class.

fun(self, x, *args, **kwargs)

Evaluates function on x.

fun_ndarray(self, x, *args, **kwargs)

Evaluates function on x (ndarray).

get_class_from_type(class_type)

Return the class associated with input type.

get_params(self)

Returns the dictionary of class hyperparameters.

get_state(self, **kwargs)

Returns the object state dictionary.

get_subclasses()

Get all the subclasses of the calling class.

global_min()

Value of the global minimum of the function.

global_min_x([ndim])

Global minimum point of the function.

gradient(self, x, *args, **kwargs)

Evaluates gradient of function at point x.

gradient_ndarray(self, x, *args, **kwargs)

Evaluates gradient of function at point x (ndarray).

has_fun(self)

True if function has been set.

has_gradient(self)

True if gradient has been set.

is_equal(self, x, val[, tol])

Evaluates if function value is close to val within tol.

list_class_types()

This method lists all types of available subclasses of calling one.

load(path)

Loads object from file.

load_state(self, path)

Sets the object state from file.

reset_eval(self)

Reset the count of function and gradient of function evaluations.

save(self, path)

Save class object to file.

save_state(self, path, **kwargs)

Store the object state to file.

set(self, param_name, param_value[, copy])

Set a parameter of the class.

set_params(self, params_dict[, copy])

Set all parameters passed as a dictionary {key: value}.

set_state(self, state_dict[, copy])

Sets the object state using input dictionary.

timed([msg])

Timer decorator.

static global_min()[source]

Value of the global minimum of the function.

Global minimum f(x) = 0 @ x = (1, 1, …., 1).

Returns
float

Value of the global minimum of the function.

static global_min_x(ndim=2)[source]

Global minimum point of the function.

Global minimum f(x) = 0 @ x = (1, 1, …., 1).

Parameters
ndimint, optional

Number of dimensions to consider, higher or equal to 2. Default 2.

Returns
CArray

The global minimum point of the function.

CFunctionThreeHumpCamel

class secml.optim.function.c_function_3hcamel.CFunctionThreeHumpCamel[source]

Bases: secml.optim.function.c_function.CFunction

The Three-Hump Camel function.

2-Dimensional function.

Global minimum f(x) = 0 @ x = (0, 0).

Given by: .. math:

f(x) = 2 * x_0 ** 2 - 1.05 * x_0 ** 4 +
 x_0 ** 6 / 6 + x_0 * x_1 + x_1 ^ 2
Attributes
class_type‘3h-camel’

Defines class type.

Methods

approx_fprime(self, x, epsilon, *args, **kwargs)

Finite-difference approximation of the gradient of a scalar function.

check_grad(self, x, epsilon, *args, **kwargs)

Check the correctness of a gradient function by comparing

copy(self)

Returns a shallow copy of current class.

create([class_item])

This method creates an instance of a class with given type.

deepcopy(self)

Returns a deep copy of current class.

fun(self, x, *args, **kwargs)

Evaluates function on x.

fun_ndarray(self, x, *args, **kwargs)

Evaluates function on x (ndarray).

get_class_from_type(class_type)

Return the class associated with input type.

get_params(self)

Returns the dictionary of class hyperparameters.

get_state(self, **kwargs)

Returns the object state dictionary.

get_subclasses()

Get all the subclasses of the calling class.

global_min()

Value of the global minimum of the function.

global_min_x()

Global minimum point of the function.

gradient(self, x, *args, **kwargs)

Evaluates gradient of function at point x.

gradient_ndarray(self, x, *args, **kwargs)

Evaluates gradient of function at point x (ndarray).

has_fun(self)

True if function has been set.

has_gradient(self)

True if gradient has been set.

is_equal(self, x, val[, tol])

Evaluates if function value is close to val within tol.

list_class_types()

This method lists all types of available subclasses of calling one.

load(path)

Loads object from file.

load_state(self, path)

Sets the object state from file.

reset_eval(self)

Reset the count of function and gradient of function evaluations.

save(self, path)

Save class object to file.

save_state(self, path, **kwargs)

Store the object state to file.

set(self, param_name, param_value[, copy])

Set a parameter of the class.

set_params(self, params_dict[, copy])

Set all parameters passed as a dictionary {key: value}.

set_state(self, state_dict[, copy])

Sets the object state using input dictionary.

timed([msg])

Timer decorator.

static global_min()[source]

Value of the global minimum of the function.

Global minimum f(x) = 0 @ x = (0, 0).

Returns
float

Value of the global minimum of the function.

static global_min_x()[source]

Global minimum point of the function.

Global minimum f(x) = 0 @ x = (0, 0).

Returns
CArray

The global minimum point of the function.

CFunctionBeale

class secml.optim.function.c_function_beale.CFunctionBeale[source]

Bases: secml.optim.function.c_function.CFunction

The Beale function.

2-Dimensional, multimodal, with sharp peaks at the corners of the input domain.

Global minimum f(x) = 0 @ x = (3, 0.5).

Given by: .. math:

f(x) = (1.5 - x_0 + x_0 * x_1)^2 + (2.25 - x_0 + x_0 * x_1^2)^2 +
 (2.625 - x_0 + x_0 * x_1^3)^2
Attributes
class_type‘beale’

Defines class type.

Methods

approx_fprime(self, x, epsilon, *args, **kwargs)

Finite-difference approximation of the gradient of a scalar function.

check_grad(self, x, epsilon, *args, **kwargs)

Check the correctness of a gradient function by comparing

copy(self)

Returns a shallow copy of current class.

create([class_item])

This method creates an instance of a class with given type.

deepcopy(self)

Returns a deep copy of current class.

fun(self, x, *args, **kwargs)

Evaluates function on x.

fun_ndarray(self, x, *args, **kwargs)

Evaluates function on x (ndarray).

get_class_from_type(class_type)

Return the class associated with input type.

get_params(self)

Returns the dictionary of class hyperparameters.

get_state(self, **kwargs)

Returns the object state dictionary.

get_subclasses()

Get all the subclasses of the calling class.

global_min()

Value of the global minimum of the function.

global_min_x()

Global minimum point of the function.

gradient(self, x, *args, **kwargs)

Evaluates gradient of function at point x.

gradient_ndarray(self, x, *args, **kwargs)

Evaluates gradient of function at point x (ndarray).

has_fun(self)

True if function has been set.

has_gradient(self)

True if gradient has been set.

is_equal(self, x, val[, tol])

Evaluates if function value is close to val within tol.

list_class_types()

This method lists all types of available subclasses of calling one.

load(path)

Loads object from file.

load_state(self, path)

Sets the object state from file.

reset_eval(self)

Reset the count of function and gradient of function evaluations.

save(self, path)

Save class object to file.

save_state(self, path, **kwargs)

Store the object state to file.

set(self, param_name, param_value[, copy])

Set a parameter of the class.

set_params(self, params_dict[, copy])

Set all parameters passed as a dictionary {key: value}.

set_state(self, state_dict[, copy])

Sets the object state using input dictionary.

timed([msg])

Timer decorator.

static global_min()[source]

Value of the global minimum of the function.

Global minimum f(x) = 0 @ x = (3, 0.5).

Returns
float

Value of the global minimum of the function.

static global_min_x()[source]

Global minimum point of the function.

Global minimum f(x) = 0 @ x = (3, 0.5).

Returns
CArray

The global minimum point of the function.

CFunctionMcCormick

class secml.optim.function.c_function_mccormick.CFunctionMcCormick[source]

Bases: secml.optim.function.c_function.CFunction

The McCormick function.

2-Dimensional function.

Global minimum f(x) = -1.9132 @ x = (-0.5472, -1.5472). This is on a compact domain (lb=[-1.5,-3], ub=[4,4])

Given by: .. math:

f(x) = sin(x_0 + x_1) + (x_0 - x_1)^2 - 1.5 * x_0 + 2.5 * x_1 + 1
Attributes
class_typemc-cormick’

Defines class type.

Methods

approx_fprime(self, x, epsilon, *args, **kwargs)

Finite-difference approximation of the gradient of a scalar function.

check_grad(self, x, epsilon, *args, **kwargs)

Check the correctness of a gradient function by comparing

copy(self)

Returns a shallow copy of current class.

create([class_item])

This method creates an instance of a class with given type.

deepcopy(self)

Returns a deep copy of current class.

fun(self, x, *args, **kwargs)

Evaluates function on x.

fun_ndarray(self, x, *args, **kwargs)

Evaluates function on x (ndarray).

get_class_from_type(class_type)

Return the class associated with input type.

get_params(self)

Returns the dictionary of class hyperparameters.

get_state(self, **kwargs)

Returns the object state dictionary.

get_subclasses()

Get all the subclasses of the calling class.

global_min()

Value of the global minimum of the function.

global_min_x()

Global minimum point of the function.

gradient(self, x, *args, **kwargs)

Evaluates gradient of function at point x.

gradient_ndarray(self, x, *args, **kwargs)

Evaluates gradient of function at point x (ndarray).

has_fun(self)

True if function has been set.

has_gradient(self)

True if gradient has been set.

is_equal(self, x, val[, tol])

Evaluates if function value is close to val within tol.

list_class_types()

This method lists all types of available subclasses of calling one.

load(path)

Loads object from file.

load_state(self, path)

Sets the object state from file.

reset_eval(self)

Reset the count of function and gradient of function evaluations.

save(self, path)

Save class object to file.

save_state(self, path, **kwargs)

Store the object state to file.

set(self, param_name, param_value[, copy])

Set a parameter of the class.

set_params(self, params_dict[, copy])

Set all parameters passed as a dictionary {key: value}.

set_state(self, state_dict[, copy])

Sets the object state using input dictionary.

timed([msg])

Timer decorator.

bounds

static bounds()[source]
static global_min()[source]

Value of the global minimum of the function.

Global minimum f(x) = -1.9132 @ x = (-0.5472, -1.5472).

Returns
float

Value of the global minimum of the function.

static global_min_x()[source]

Global minimum point of the function.

Global minimum f(x) = -1.9132 @ x = (-0.5472, -1.5472).

Returns
CArray

The global minimum point of the function.