bluemira.optimisation._optimiser
================================

.. py:module:: bluemira.optimisation._optimiser

.. autoapi-nested-parse::

   Defines the interface for an Optimiser.



Classes
-------

.. autoapisummary::

   bluemira.optimisation._optimiser.OptimiserResult
   bluemira.optimisation._optimiser.Optimiser


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

.. py:class:: OptimiserResult

   Container for optimiser results.


   .. py:attribute:: f_x
      :type:  float

      The evaluation of the optimised parameterisation.


   .. py:attribute:: x
      :type:  numpy.ndarray

      The optimised parameterisation.


   .. py:attribute:: n_evals
      :type:  int

      The number of evaluations of the objective function in the optimisation.


   .. py:attribute:: history
      :type:  list[tuple[numpy.ndarray, float]]

      The history of the parameterisation at each iteration.

      The first element of each tuple is the parameterisation (x), the
      second is the evaluation of the objective function at x (f(x)).


   .. py:attribute:: constraint_history
      :type:  list[tuple[numpy.ndarray, Ellipsis]]

      Constraint history


   .. py:attribute:: constraints_satisfied
      :type:  bool | None
      :value: None


      Whether all constraints have been satisfied to within the required tolerance.

      Is ``None`` if constraints have not been checked.


.. py:class:: Optimiser

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

   .. autoapi-inheritance-diagram:: bluemira.optimisation._optimiser.Optimiser
      :parts: 1
      :private-bases:


   Interface for an optimiser supporting bounds and constraints.


   .. py:method:: add_eq_constraint(f_constraint: bluemira.optimisation.typed.OptimiserCallable, tolerance: numpy.ndarray, df_constraint: bluemira.optimisation.typed.OptimiserCallable | None = None) -> None
      :abstractmethod:


      Add an equality constraint to the optimiser.

      The constraint is a vector-valued, non-linear, equality
      constraint of the form :math:`f_{c}(x) = 0`.

      The constraint function should have the form
      :math:`f(x) \rightarrow y`, where:

          * :math:`x` is a numpy array of the optimisation parameters.
          * :math:`y` is a numpy array containing the values of the
            constraint at :math:`x`, with size :math:`m`, where
            :math:`m` is the dimensionality of the constraint.

      :param f_constraint: The constraint function, with form as described above.
      :param tolerance: The tolerances for each optimisation parameter.
      :param df_constraint: The gradient of the constraint function. This should have
                            the same form as the constraint function, however its output
                            array should have dimensions :math:`m \times n` where
                            :math`m` is the dimensionality of the constraint, and
                            :math:`n` is the number of optimisation parameters.

      .. rubric:: Notes

      Inequality constraints are only supported by algorithms:

          * SLSQP
          * COBYLA
          * ISRES



   .. py:method:: add_ineq_constraint(f_constraint: bluemira.optimisation.typed.OptimiserCallable, tolerance: numpy.ndarray, df_constraint: bluemira.optimisation.typed.OptimiserCallable | None = None) -> None
      :abstractmethod:


      Add an inequality constrain to the optimiser.

      The constraint is a vector-valued, non-linear, inequality
      constraint of the form :math:`f_{c}(x) \le 0`.

      The constraint function should have the form
      :math:`f(x) \rightarrow y`, where:

          * :math:`x` is a numpy array of the optimisation parameters.
          * :math:`y` is a numpy array containing the values of the
            constraint at :math:`x`, with size :math:`m`, where
            :math:`m` is the dimensionality of the constraint.

      :param f_constraint: The constraint function, with form as described above.
      :param tolerance: The tolerances for each optimisation parameter.
      :param df_constraint: The gradient of the constraint function. This should have
                            the same form as the constraint function, however its output
                            array should have dimensions :math:`m \times n` where
                            :math`m` is the dimensionality of the constraint, and
                            :math:`n` is the number of optimisation parameters.

      .. rubric:: Notes

      Inequality constraints are only supported by algorithms:

          * SLSQP
          * COBYLA
          * ISRES



   .. py:method:: optimise(x0: numpy.ndarray | None = None) -> OptimiserResult
      :abstractmethod:


      Run the optimiser.

      :param x0: The initial guess for each of the optimisation parameters.
                 If not given, each parameter is set to the average of its
                 lower and upper bound. If no bounds exist, the initial guess
                 will be all zeros.

      :returns: The result of the optimisation, containing the optimised
                parameters ``x``, as well as other information about the
                optimisation.



   .. py:method:: set_lower_bounds(bounds: numpy.ndarray) -> None
      :abstractmethod:


      Set the lower bound for each optimisation parameter.

      Set to `-np.inf` to unbound the parameter's minimum.



   .. py:method:: set_upper_bounds(bounds: numpy.ndarray) -> None
      :abstractmethod:


      Set the upper bound for each optimisation parameter.

      Set to `np.inf` to unbound the parameter's minimum.