bluemira.equilibria.optimisation.objectives
===========================================

.. py:module:: bluemira.equilibria.optimisation.objectives

.. autoapi-nested-parse::

   Equilibrium optimisation objective functions.

   Objective functions must be of the form:

   .. code-block:: python

       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:

   :math:`\nabla f = \bigg[\dfrac{\partial f}{\partial x_0}, \dfrac{\partial f}{\partial x_1}, ...\bigg]`



Classes
-------

.. autoapisummary::

   bluemira.equilibria.optimisation.objectives.ObjectiveFunction
   bluemira.equilibria.optimisation.objectives.RegularisedLsqObjective
   bluemira.equilibria.optimisation.objectives.CoilCurrentsObjective
   bluemira.equilibria.optimisation.objectives.MaximiseFluxObjective


Functions
---------

.. autoapisummary::

   bluemira.equilibria.optimisation.objectives.tikhonov
   bluemira.equilibria.optimisation.objectives.regularised_lsq_fom


Module Contents
---------------

.. py:class:: ObjectiveFunction

   Bases: :py:obj:`abc.ABC`

   .. autoapi-inheritance-diagram:: bluemira.equilibria.optimisation.objectives.ObjectiveFunction
      :parts: 1
      :private-bases:


   Base class for ObjectiveFunctions

   .. rubric:: 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.


   .. py:method:: f_objective(vector: numpy.typing.NDArray[numpy.float64]) -> float
      :abstractmethod:


      Objective function for an optimisation.



.. py:class:: 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: :py:obj:`ObjectiveFunction`

   .. autoapi-inheritance-diagram:: bluemira.equilibria.optimisation.objectives.RegularisedLsqObjective
      :parts: 1
      :private-bases:


   Least-squares objective with Tikhonov regularisation term.

   :param scale: Scaling factor for the vector
   :param a_mat: The 2-D a_mat control matrix A (n, m)
   :param b_vec: The 1-D b vector of target values (n)
   :param gamma: The Tikhonov regularisation parameter.


   .. py:attribute:: scale


   .. py:attribute:: a_mat


   .. py:attribute:: b_vec


   .. py:attribute:: gamma


   .. py:method:: 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



   .. py:method:: df_objective(vector: numpy.typing.NDArray[numpy.float64]) -> numpy.typing.NDArray[numpy.float64]

      Gradient of the objective function for an optimisation.



.. py:class:: CoilCurrentsObjective

   Bases: :py:obj:`ObjectiveFunction`

   .. autoapi-inheritance-diagram:: bluemira.equilibria.optimisation.objectives.CoilCurrentsObjective
      :parts: 1
      :private-bases:


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


   .. py:method:: f_objective(vector: numpy.typing.NDArray[numpy.float64]) -> float
      :staticmethod:


      Objective function for an optimisation.

      :returns: The figure of merit



   .. py:method:: df_objective(vector: numpy.typing.NDArray[numpy.float64]) -> numpy.typing.NDArray[numpy.float64]
      :staticmethod:


      Gradient of the objective function for an optimisation.



.. py:class:: MaximiseFluxObjective(c_psi_mat: numpy.typing.NDArray[numpy.float64], scale: float)

   Bases: :py:obj:`ObjectiveFunction`

   .. autoapi-inheritance-diagram:: bluemira.equilibria.optimisation.objectives.MaximiseFluxObjective
      :parts: 1
      :private-bases:


   Objective function to maximise flux

   :param c_psi_mat: Response matrix of the coil psi contributions to the point at which the flux
                     should be maximised
   :param scale: Scaling factor for the vector


   .. py:attribute:: c_psi_mat


   .. py:attribute:: scale


   .. py:method:: f_objective(vector: numpy.typing.NDArray[numpy.float64]) -> float

      Objective function for an optimisation.



   .. py:method:: df_objective(vector: numpy.typing.NDArray[numpy.float64]) -> numpy.typing.NDArray[numpy.float64]

      Gradient of the objective function for an optimisation.



.. py:function:: 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.

       :math:`\textrm{minimise} || Ax - b ||^2 + ||{\gamma} \cdot x ||^2`

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

   :param a_mat: The 2-D A matrix of responses
   :param b_vec: The 1-D b vector of values
   :param gamma: The Tikhonov regularisation parameter
   :type gamma: float

   :returns: The result vector
   :rtype: x


.. py:function:: 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||²

   :param x: The 1-D x state vector (m)
   :param a_mat: The 2-D a_mat control matrix A (n, m)
   :param b_vec: The 1-D b vector of target values (n)
   :param gamma: 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