bluemira.equilibria.coils._tools
================================

.. py:module:: bluemira.equilibria.coils._tools

.. autoapi-nested-parse::

   Tools for Coilgroups



Functions
---------

.. autoapisummary::

   bluemira.equilibria.coils._tools.make_mutual_inductance_matrix
   bluemira.equilibria.coils._tools._get_symmetric_coils
   bluemira.equilibria.coils._tools.check_coilset_symmetric
   bluemira.equilibria.coils._tools.get_max_current
   bluemira.equilibria.coils._tools.rename_coilset


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

.. py:function:: make_mutual_inductance_matrix(coilset: bluemira.equilibria.coils.CoilSet, *, square_coil: bool = False) -> numpy.ndarray

   Calculate the mutual inductance matrix of a coilset.

   :param coilset: Coilset for which to calculate the mutual inductance matrix
   :param square_coil: Whether or not to use a square coil approximation for the
                       self-inductance diagonal terms. Defaults to a elliptical
                       integral of a circular cross-section coil.

   :returns: The symmetric mutual inductance matrix [H]

   .. rubric:: Notes

   Multi-filament coil formulation. The mutual inductance between two coils is
   calculated based on the number of filaments in each coil (numerical
   discretisation, which is then normalised). The number of turns in each coil
   determine the actual multiplier of the mutual inductance.

   - **Off-diagonal terms** (:math:`i \neq j`):

       .. math::
           M_{ij} = n_i n_j \sum_{k=0, m=0}^{n_k, n_m} G(x_{i,n}, z_{i,n}, x_{j,m}, z_{j,m})

       where :math:`G` is the Green's function for mutual inductance.

   - **Diagonal terms** (:math:`i = j`):

       .. math::
           M_{ii} = n_i^2 L_i

       with :math:`L_i` as the self-inductance using elliptic integrals.


.. py:function:: _get_symmetric_coils(coilset: bluemira.equilibria.coils.CoilSet, rtol: float = 1e-05) -> tuple[list[numpy.typing.NDArray], numpy.typing.NDArray, list[list[int]]]

   Coilset symmetry utility

   :param coilset: CoilSet to get symmetric coils from
   :param rtol: Relative tolerance used when comparing coil values,
                rtol = 1.e-5 is the default value for np.allclose.
                The values for the secondary coil in the pair will be
                set to be equal to the primary coil values if they are
                within rtol.

   :returns: * Symmetric coilset data
             * Counts of number of coils in group
             * indexes from original coilset


.. py:function:: check_coilset_symmetric(coilset: bluemira.equilibria.coils.CoilSet, rtol: float | None = None) -> bool

   Check whether or not a CoilSet is purely symmetric about z=0.

   :param coilset: CoilSet to check for symmetry

   :rtype: Whether or not the CoilSet is symmetric about z=0


.. py:function:: get_max_current(dx: float | numpy.ndarray, dz: float | numpy.ndarray, j_max: float | numpy.ndarray) -> numpy.float64 | numpy.ndarray

   Get the maximum current in a rectangular coil cross-sectional area

   :param dx: Coil half-width [m]
   :param dz: Coil half-height [m]
   :param j_max: Coil current density [A/m^2]

   :rtype: Maximum current [A]

   .. rubric:: Notes

   .. math::
       I_{\text{max}} = j_{\text{max}} \cdot (4 \cdot dx \cdot dz)


.. py:function:: rename_coilset(coilset: bluemira.equilibria.coils.CoilSet)

   Rename the coils.

   :returns: The coilset containing the renamed coils
   :rtype: Coilset