bluemira.equilibria.optimisation.problem.base
=============================================

.. py:module:: bluemira.equilibria.optimisation.problem.base

.. autoapi-nested-parse::

   Equilibria Optimisation base module



Classes
-------

.. autoapisummary::

   bluemira.equilibria.optimisation.problem.base.CoilsetOptimiserResult
   bluemira.equilibria.optimisation.problem.base.CoilsetOptimisationProblem
   bluemira.equilibria.optimisation.problem.base.EqCoilsetOptimisationProblem


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

.. py:class:: CoilsetOptimiserResult

   Coilset optimisation result object


   .. py:attribute:: coilset
      :type:  bluemira.equilibria.coils.CoilSet

      The optimised coilset.


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

      The evaluation of 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:: 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:method:: from_opt_result(coilset: bluemira.equilibria.coils.CoilSet, opt_result: bluemira.optimisation._optimiser.OptimiserResult) -> CoilsetOptimiserResult
      :classmethod:


      Make a coilset optimisation result from a normal optimisation result.



.. py:class:: CoilsetOptimisationProblem(coilset: bluemira.equilibria.coils.CoilSet, opt_algorithm: bluemira.optimisation._algorithm.AlgorithmType, *, max_currents: numpy.typing.ArrayLike | None = None, targets: bluemira.equilibria.optimisation.constraints.MagneticConstraintSet | None = None, constraints: list[bluemira.equilibria.optimisation.constraints.UpdateableConstraint] | None = None, opt_conditions: dict[str, float | int] | None = None, opt_parameters: dict[str, float] | None = None)

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

   .. autoapi-inheritance-diagram:: bluemira.equilibria.optimisation.problem.base.CoilsetOptimisationProblem
      :parts: 1
      :private-bases:


   Abstract base class for coilset optimisation problems.

   Subclasses should provide an optimise() method that
   returns an optimised coilset object, optimised according
   to a specific objective function for that subclass.


   .. py:attribute:: _coilset


   .. py:attribute:: max_currents
      :value: None



   .. py:attribute:: bounds


   .. py:attribute:: targets


   .. py:attribute:: constraints
      :value: []



   .. py:attribute:: opt_algorithm


   .. py:attribute:: opt_conditions


   .. py:attribute:: opt_parameters


   .. py:property:: coilset
      :type: bluemira.equilibria.coils.CoilSet


      The optimisation problem coilset


   .. py:property:: scale
      :type: float


      Problem scaling value


   .. py:method:: _opt_condition_defaults(default_cond: dict[str, float | int]) -> dict[str, float | int]


   .. py:method:: optimise(**kwargs) -> CoilsetOptimiserResult
      :abstractmethod:


      Run the coilset optimisation.



   .. py:method:: get_current_bounds(max_currents: numpy.typing.ArrayLike | None, current_scale: float) -> tuple[numpy.ndarray, numpy.ndarray]

      Gets the scaled current vector bounds. Must be called prior to optimise.

      :param max_currents: Maximum magnitude of currents in each coil [A] permitted during optimisation.
                           If max_current is supplied as a float, the float will be set as the
                           maximum allowed current magnitude for all coils.
                           If the coils have current density limits that are more restrictive than these
                           coil currents, the smaller current limit of the two will be used for each
                           coil.
      :param current_scale: Factor to scale coilset currents down when returning scaled current limits.

      :returns: **current_bounds** -- Tuple of arrays containing lower and upper bounds for currents
                permitted in each control coil.
      :rtype: (np.narray, np.narray)

      :raises EquilibriaError: Number of max currents not equal to number of optimisable currents



   .. py:method:: set_current_bounds(max_currents: numpy.typing.NDArray[numpy.float64])

      Set the current bounds on this instance.

      :param max_currents: Vector of maximum currents [A]

      :raises ValueError: Length of max current vector must be equal to controls



   .. py:method:: _make_numerical_constraints() -> tuple[list[bluemira.optimisation.typed.ConstraintT], list[bluemira.optimisation.typed.ConstraintT]]

      Build the numerical equality and inequality constraint dictionaries.

      :returns: * equality constraints
                * inequality constriants



.. py:class:: EqCoilsetOptimisationProblem(eq: bluemira.equilibria.equilibrium.Equilibrium, opt_algorithm: bluemira.optimisation._algorithm.AlgorithmType, *, max_currents: numpy.typing.ArrayLike | None = None, targets: bluemira.equilibria.optimisation.constraints.MagneticConstraintSet | None = None, constraints: list[bluemira.equilibria.optimisation.constraints.UpdateableConstraint] | None = None, opt_conditions: dict[str, float | int] | None = None, opt_parameters: dict[str, float] | None = None)

   Bases: :py:obj:`CoilsetOptimisationProblem`

   .. autoapi-inheritance-diagram:: bluemira.equilibria.optimisation.problem.base.EqCoilsetOptimisationProblem
      :parts: 1
      :private-bases:


   Initialise the optimisation problem for a CoilSetMHDState.

   :raises ValueError: If the equilibrium does not have a coilset to optimise.


   .. py:attribute:: eq


   .. py:method:: update_magnetic_constraints(*, I_not_dI: bool = True, fixed_coils: bool = True)

      Update the magnetic optimisation constraints with the state of the Equilibrium