bluemira.equilibria.optimisation.problem._nested_position
=========================================================

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

.. autoapi-nested-parse::

   OptimisationProblems for coilset design.

   New optimisation schemes for the coilset can be provided by subclassing
   from CoilsetOP, which is an abstract base class for OptimisationProblems
   that use a coilset as their parameterisation object.

   Subclasses must provide an optimise() method that returns an optimised
   coilset according to a given optimisation objective function.
   As the exact form of the state vector that is optimised is often
   specific to each objective function, each subclass of CoilsetOP is
   generally also specific to a given objective function, since
   the method used to map the coilset object to the state vector
   (and additional required arguments) will generally differ in each case.



Classes
-------

.. autoapisummary::

   bluemira.equilibria.optimisation.problem._nested_position.NestedCoilsetPositionCOP
   bluemira.equilibria.optimisation.problem._nested_position.PulsedNestedPositionCOP


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

.. py:class:: NestedCoilsetPositionCOP(sub_opt: bluemira.equilibria.optimisation.problem.base.EqCoilsetOptimisationProblem, position_mapper: bluemira.utilities.positioning.PositionMapper, opt_algorithm: bluemira.optimisation.AlgorithmType = Algorithm.SBPLX, opt_conditions: dict[str, float] | None = None, opt_parameters: dict[str, float] | None = None, constraints: list[bluemira.equilibria.optimisation.constraints.UpdateableConstraint] | None = None)

   Bases: :py:obj:`bluemira.equilibria.optimisation.problem.base.EqCoilsetOptimisationProblem`

   .. autoapi-inheritance-diagram:: bluemira.equilibria.optimisation.problem._nested_position.NestedCoilsetPositionCOP
      :parts: 1
      :private-bases:


   Coilset OptimisationProblem for coil currents and positions
   subject to maximum current bounds and positions bounded within
   a provided region. Performs a nested optimisation for coil
   currents within each position optimisation function call.

   :param sub_opt: Coilset OptimisationProblem to use for the optimisation of
                   coil currents at each trial set of coil positions.
                   sub_opt.coilset will be modified
                   during the optimisation.
   :param eq: Equilibrium object used to update magnetic field targets.
   :param position_mapper: position mapper object of the regions to optimise the coil positions within
   :param opt_algorithm: The optimisation algorithm to use (e.g. SLSQP)
   :param opt_conditions: The stopping conditions for the optimiser.
                          for defaults see
                          :class:`~bluemira.optimisation._algorithm.AlgorithDefaultTolerances`
                          along with `max_eval=100`
   :param opt_parameters: Optimiser specific parameters,
                          see https://nlopt.readthedocs.io/en/latest/NLopt_Reference/#algorithm-specific-parameters
                          Otherwise, the parameters can be founded by digging through the source code.
   :param constraints: List of optimisation constraints to apply to the optimisation problem

   .. rubric:: Notes

   Setting stopval and maxeval is the most reliable way to stop optimisation
   at the desired figure of merit and number of iterations respectively.
   Some NLOpt optimisers display unexpected behaviour when setting xtol and
   ftol, and may not terminate as expected when those criteria are reached.


   .. py:attribute:: position_mapper


   .. py:attribute:: bounds


   .. py:attribute:: sub_opt


   .. py:method:: _get_initial_vector() -> numpy.typing.NDArray

      :returns: A vector representation of the initial coilset state from the PositionMapper.



   .. py:method:: optimise(x0: numpy.typing.NDArray | None = None, *, keep_history: bool = False, check_constraints: bool = False)

      Run the optimisation.

      :rtype: Optimised CoilSet object.



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

      Objective function to minimise.



.. py:class:: PulsedNestedPositionCOP(coilset: bluemira.equilibria.coils.CoilSet, position_mapper: bluemira.utilities.positioning.PositionMapper, sub_opt_problems: list[bluemira.equilibria.optimisation.problem.base.EqCoilsetOptimisationProblem], opt_algorithm: bluemira.optimisation.AlgorithmType = Algorithm.COBYLA, opt_conditions: dict[str, float] | None = None, opt_parameters: dict[str, float] | None = None, constraints=None, initial_currents=None, current_bounder: bluemira.equilibria.run.MovingCurrentBoundStrategy | None = None, *, debug: bool = False, keep_history: bool = True, check_constraints: bool = True)

   Bases: :py:obj:`bluemira.equilibria.optimisation.problem.base.CoilsetOptimisationProblem`

   .. autoapi-inheritance-diagram:: bluemira.equilibria.optimisation.problem._nested_position.PulsedNestedPositionCOP
      :parts: 1
      :private-bases:


   Coilset position optimisation problem for multiple sub-optimisation problems.

   :param coilset: Coilset for which to optimise positions
   :param position_mapper: Position mapper tool to parameterise coil positions
   :param sub_opt_problems: The list of sub-optimisation problems to solve
   :param opt_algorithm: The optimisation algorithm to use (e.g. SLSQP)
   :param opt_conditions: The stopping conditions for the optimiser.
                          for defaults see
                          :class:`~bluemira.optimisation._algorithm.AlgorithDefaultTolerances`
                          along with `max_eval=100`
   :param constraints: Constraints to use. Note these should be applicable to the parametric position
                       vector
   :param initial_currents: Initial currents to use when solving the current sub-optimisation problems
   :param debug: Whether or not to run in debug mode (will affect run-time noticeably)


   .. py:attribute:: position_mapper


   .. py:attribute:: sub_opt_problems


   .. py:attribute:: debug


   .. py:attribute:: iter


   .. py:attribute:: bounds


   .. py:attribute:: current_bounder
      :value: None



   .. py:attribute:: keep_history
      :value: True



   .. py:attribute:: check_constraints
      :value: True



   .. py:method:: _run_reporting(itern, max_fom, verbose)
      :staticmethod:


      Keep track of objective function value over iterations.



   .. py:method:: _run_diagnostics(debug, sub_opt_prob: bluemira.equilibria.optimisation.problem.base.EqCoilsetOptimisationProblem, opt_result: bluemira.equilibria.optimisation.problem.base.CoilsetOptimiserResult)
      :staticmethod:


      In debug mode, store the LCFS at each iteration for each of the sub-optimisation
      problems.

      .. rubric:: Notes

      This can significantly impact run-time.



   .. py:method:: sub_opt_objective(vector: numpy.typing.NDArray[numpy.float64], *, verbose: bool = False) -> float

      Run the sub-optimisations

      :returns: The largest figure of merit.



   .. py:method:: objective(vector: numpy.typing.NDArray[numpy.float64], *, verbose: bool = False) -> float

      The objective function of the parent optimisation.

      :returns: Results of the sub-optimisations.



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

      :returns: A vector representation of the initial coilset state from the PositionMapper.



   .. py:method:: optimise(x0: numpy.typing.NDArray | None = None, *, verbose: bool = False, keep_history: bool = False, check_constraints: bool = False) -> bluemira.equilibria.optimisation.problem.base.CoilsetOptimiserResult

      Run the PulsedNestedPositionCOP

      :param x0: Initial solution vector (parameterised positions)
      :param verbose: Whether or not to print progress information

      :returns: Optimised CoilSet
      :rtype: coilset