bluemira.equilibria.vertical_stability
======================================

.. py:module:: bluemira.equilibria.vertical_stability

.. autoapi-nested-parse::

   Vertical stability calculations



Classes
-------

.. autoapisummary::

   bluemira.equilibria.vertical_stability.RZIp


Functions
---------

.. autoapisummary::

   bluemira.equilibria.vertical_stability.calculate_rzip_stability_criterion
   bluemira.equilibria.vertical_stability.stab_destab
   bluemira.equilibria.vertical_stability._length_step
   bluemira.equilibria.vertical_stability._get_coil_points_along_wire
   bluemira.equilibria.vertical_stability.make_coils_along_wire


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

.. py:function:: calculate_rzip_stability_criterion(eq: bluemira.equilibria.equilibrium.Equilibrium) -> float

   Calculate the rzip stability criterion for a given equilibrium and coilset

   :param eq: The equilibrium object

   :returns: Stability criterion

   .. rubric:: Notes

   See ~:class:`~bluemira.equilibria.vertical_stability.RZIp` for details


.. py:class:: RZIp(coilset)

   RZIp model

   :param coilset: The full coilset

   .. rubric:: Notes

   A value ~ 1.5 considered optimal and controllable.
   See https://doi.org/10.13182/FST89-A39747 for further explanation

       < 1 plasma mass becomes a factor
       = 1 massless plasma solution not valid (said to represent MHD effects)
       > 1 displacement growth dominated by L/R of passive system

   .. math::

       f = -\frac{F_s}{F_d}
         = \frac{I_p^T M^{\prime}_p|_s [M_s|_s]^{-1} M^{\prime}_s|_p I_p}
                 {I_p^T M^{\prime\prime}_p|_c I_c}


   .. py:property:: coilset

      Coilset used for calculation


   .. py:method:: __call__(eq: bluemira.equilibria.equilibrium.Equilibrium) -> float

      :param eq: The equilibrium object to analyse

      :returns: The stability criterion



.. py:function:: stab_destab(cc_current: numpy.typing.NDArray, ind_mat: numpy.typing.NDArray, control_ind: list[int], uncontrolled_ind: list[int], r_struct: numpy.typing.NDArray, i_plasma: numpy.typing.NDArray, br_struct_grid: numpy.typing.NDArray, dbrdz_struct_grid: numpy.typing.NDArray) -> float

   Calculate the stabilising / destabilising effect of the equilibria and structures

   :param cc_current: array of control coil currents
   :param ind_mat: Inductance matrix of passive and active structures
   :param control_ind: indicies of active structures
   :param uncontrolled_ind: indicies of passive structures
   :param r_struct: flattened array of eq R points duplicated by number of coils
   :param i_plasma: the plasma jtor x grid step
   :param br_struct_grid: Bx field
   :param dbrdz_struct_grid: dBxdz field

   :returns: The stability criterion


.. py:function:: _length_step(p1, p2, delta) -> float

   Calculates the tangent angle for two points and uses this to determine
   the wire length to use as the difference for a square with thickness
   delta.

   :returns: Length value for a wire discretisation step.
   :rtype: float


.. py:function:: _get_coil_points_along_wire(wire: bluemira.geometry.wire.BluemiraWire, thickness: float) -> numpy.ndarray

   Discretises input wire in such a way that squares centred on
   those points will not overlap whilst minimising gaps.

   Achieves by calculating tangent angle at given point and using
   this to determine how far along the wire to put the next point.

   Paramters
   ---------
   wire:
       The wire that the coilset will be centred on.
   thickness:
       The thickness of the coils, will also impact the number of coils.

   :returns: An array containing the discretised points of the input wire in 3D.
   :rtype: np.ndarray


.. py:function:: make_coils_along_wire(wire: bluemira.geometry.wire.BluemiraWire, thickness: float, simple: bool = True, name_prefix: str = 'Passive', ctype: bluemira.base.constants.CoilType = CoilType.DUM, resistivity: float = 0.0) -> bluemira.equilibria.coils._grouping.CoilGroup

   Function to create a coilset from a wire, where the coils making up the coilset
   will have a dx and dz equal to half the given thickness, with coils separated by
   the full thickness value. Additionally the coils will be make of the provided
   material.

   The created coils will follow the wire by treating it as a centreline with coils
   centred on the line.

   :param wire: The wire that the coilset will be centred on.
   :param thickness: The thickness of the coils, will also impact the number of coils.
   :param simple: Method of discretising the input wire.
   :param name_prefix: Coil name prefix
   :param ctype: Coil type
   :param resistivity: Resistivity of the coil material [Ohm . m]

   :returns: A group of coils following the input wire.
   :rtype: CoilGroup