bluemira.equilibria.optimisation.objectives

Equilibrium optimisation objective functions.

Objective functions must be of the form:

class Objective(ObjectiveFunction):

    def f_objective(self, vector: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]:
        return objective_calc(vector)

    def df_objective(self, vector: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]:
        return gradient_calc(vector)

The objective function is minimised, so lower values are “better”.

Note that the gradient of the objective function is of the form:

\(\nabla f = \bigg[\dfrac{\partial f}{\partial x_0}, \dfrac{\partial f}{\partial x_1}, ...\bigg]\)

Classes

`ObjectiveFunction`	Base class for ObjectiveFunctions
`RegularisedLsqObjective`	Least-squares objective with Tikhonov regularisation term.
`CoilCurrentsObjective`	Objective function for the minimisation of the sum of coil currents squared.
`MaximiseFluxObjective`	Objective function to maximise flux

Functions

`tikhonov`(→ numpy.ndarray)	Tikhonov regularisation of Ax-b problem.
`regularised_lsq_fom`(→ tuple[float, numpy.ndarray])	Figure of merit for the least squares problem Ax = b, with

Module Contents

class bluemira.equilibria.optimisation.objectives.ObjectiveFunction

Bases: abc.ABC

Base class for ObjectiveFunctions

Notes

Optionally the function ‘df_objective’ can be implemented on any child classes to calculate the gradient of the objective function. The function should take an npt.NDArray as its only argument and return only an npt.NDArray. If the df_objective function is not provided and the optimisation algorithm is gradient based the approximate derivate is calculated.

abstract f_objective(vector: numpy.typing.NDArray[numpy.float64]) → float

Objective function for an optimisation.

Parameters:: vector (numpy.typing.NDArray[numpy.float64])
Return type:: float

class bluemira.equilibria.optimisation.objectives.RegularisedLsqObjective(scale: float, a_mat: numpy.typing.NDArray[numpy.float64], b_vec: numpy.typing.NDArray[numpy.float64], gamma: float, currents_expand_mat: numpy.typing.NDArray | None = None)

Bases: ObjectiveFunction

Least-squares objective with Tikhonov regularisation term.

Parameters:

scale (float) – Scaling factor for the vector
a_mat (numpy.typing.NDArray[numpy.float64]) – The 2-D a_mat control matrix A (n, m)
b_vec (numpy.typing.NDArray[numpy.float64]) – The 1-D b vector of target values (n)
gamma (float) – The Tikhonov regularisation parameter.
currents_expand_mat (numpy.typing.NDArray | None)

scale

a_mat

b_vec

gamma

f_objective(vector: numpy.typing.NDArray[numpy.float64]) → float

Objective function for an optimisation.

Returns:: The figure of merit
Raises:: EquilibriaError – Least squares result < 0 or NaN
Parameters:: vector (numpy.typing.NDArray[numpy.float64])
Return type:: float

df_objective(vector: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

Gradient of the objective function for an optimisation.

Parameters:: vector (numpy.typing.NDArray[numpy.float64])
Return type:: numpy.typing.NDArray[numpy.float64]

class bluemira.equilibria.optimisation.objectives.CoilCurrentsObjective

Bases: ObjectiveFunction

Objective function for the minimisation of the sum of coil currents squared.

static f_objective(vector: numpy.typing.NDArray[numpy.float64]) → float

Objective function for an optimisation.

Returns:: The figure of merit
Parameters:: vector (numpy.typing.NDArray[numpy.float64])
Return type:: float

static df_objective(vector: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

Gradient of the objective function for an optimisation.

Parameters:: vector (numpy.typing.NDArray[numpy.float64])
Return type:: numpy.typing.NDArray[numpy.float64]

class bluemira.equilibria.optimisation.objectives.MaximiseFluxObjective(c_psi_mat: numpy.typing.NDArray[numpy.float64], scale: float)

Bases: ObjectiveFunction

Objective function to maximise flux

Parameters:

c_psi_mat (numpy.typing.NDArray[numpy.float64]) – Response matrix of the coil psi contributions to the point at which the flux should be maximised
scale (float) – Scaling factor for the vector

c_psi_mat

scale

f_objective(vector: numpy.typing.NDArray[numpy.float64]) → float

Objective function for an optimisation.

Parameters:: vector (numpy.typing.NDArray[numpy.float64])
Return type:: float

df_objective(vector: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

Gradient of the objective function for an optimisation.

Parameters:: vector (numpy.typing.NDArray[numpy.float64])
Return type:: numpy.typing.NDArray[numpy.float64]

bluemira.equilibria.optimisation.objectives.tikhonov(a_mat: numpy.ndarray, b_vec: numpy.ndarray, gamma: float, currents_expand_mat: numpy.ndarray | None = None) → numpy.ndarray

Tikhonov regularisation of Ax-b problem.

\(\textrm{minimise} || Ax - b ||^2 + ||{\gamma} \cdot x ||^2\)

\(x = (A^T A + {\gamma}^2 I)^{-1}A^T b\)

Parameters:

a_mat (numpy.ndarray) – The 2-D A matrix of responses
b_vec (numpy.ndarray) – The 1-D b vector of values
gamma (float) – The Tikhonov regularisation parameter
currents_expand_mat (numpy.ndarray | None)

Returns:

The result vector

Return type:

x

bluemira.equilibria.optimisation.objectives.regularised_lsq_fom(x: numpy.ndarray, a_mat: numpy.ndarray, b_vec: numpy.ndarray, gamma: float) → tuple[float, numpy.ndarray]

Figure of merit for the least squares problem Ax = b, with Tikhonov regularisation term. Normalised for the number of targets.

||(Ax - b)||²/ len(b)] + ||Γx||²

Parameters:

x (numpy.ndarray) – The 1-D x state vector (m)
a_mat (numpy.ndarray) – The 2-D a_mat control matrix A (n, m)
b_vec (numpy.ndarray) – The 1-D b vector of target values (n)
gamma (float) – The Tikhonov regularisation parameter.

Returns:

fom – Figure of merit, explicitly given by ||(Ax - b)||²/ len(b)] + ||Γx||²
residual – Residual vector (Ax - b)

Raises:

EquilibriaError – Least squares result < 0 or NaN

Return type:

tuple[float, numpy.ndarray]