bluemira.equilibria.coils._field
================================

.. py:module:: bluemira.equilibria.coils._field

.. autoapi-nested-parse::

   Coil and coil grouping objects



Classes
-------

.. autoapisummary::

   bluemira.equilibria.coils._field.CoilGroupFieldsMixin
   bluemira.equilibria.coils._field.CoilSetFieldsMixin
   bluemira.equilibria.coils._field.CoilFieldsMixin


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

.. py:class:: CoilGroupFieldsMixin(*, psi_analytic: bool = False, Bx_analytic: bool = True, Bz_analytic: bool = True)

   CoilGroup magnetic fields mixin.

   Add field calculation mechanics to coilgroups


   .. py:attribute:: __slots__
      :value: ('_Bx_analytic', '_Bz_analytic', '_einsum_str', '_psi_analytic', '_quad_dx', '_quad_dz',...



   .. py:attribute:: _psi_analytic
      :value: False



   .. py:attribute:: _Bx_analytic
      :value: True



   .. py:attribute:: _Bz_analytic
      :value: True



   .. py:method:: dB_d(x: float | numpy.ndarray, z: float | numpy.ndarray)

      dB_d of Coilset

      :param x: The x values at which to calculate the dB_d response
      :param z: The z values at which to calculate the dB_d response
      :param # TODO @je-cook:
      :type # TODO @je-cook: Check if these are things you want to implement for the function
      :param # sum_coils:
      :param #     sum over coils:
      :param # control:
      :param #     operations on control coils only:

      :returns: Differential of magnetic field



   .. py:method:: dB_d_response(x: float | numpy.ndarray, z: float | numpy.ndarray)

      Unit dB_d of Coilset

      :param x: The x values at which to calculate the dB_d response
      :param z: The z values at which to calculate the dB_d response
      :param # TODO @je-cook:
      :type # TODO @je-cook: Check if these are things you want to implement for the function
      :param # sum_coils:
      :param #     sum over coils:
      :param # control:
      :param #     operations on control coils only:

      :returns: Differential of magnetic field response



   .. py:method:: psi(x: float | numpy.ndarray, z: float | numpy.ndarray)

      Calculate poloidal flux at (x, z)



   .. py:method:: psi_response(x, z)


   .. py:method:: Bx(x: float | numpy.ndarray, z: float | numpy.ndarray)

      Calculate radial magnetic field Bx at (x, z)



   .. py:method:: Bx_response(x: float | numpy.ndarray, z: float | numpy.ndarray) -> float | numpy.ndarray

      Calculate the radial magnetic field response at (x, z) due to a unit
      current. Green's functions are used outside the coil, and a semianalytic
      method is used for the field inside the coil.

      :param x: The x values at which to calculate the Bx response
      :param z: The z values at which to calculate the Bx response

      :returns: The radial magnetic field response at the x, z coordinates.



   .. py:method:: Bz(x: float | numpy.ndarray, z: float | numpy.ndarray) -> float | numpy.ndarray

      Calculate vertical magnetic field Bz at (x, z)



   .. py:method:: Bz_response(x: float | numpy.ndarray, z: float | numpy.ndarray) -> float | numpy.ndarray

      Calculate the vertical magnetic field response at (x, z) due to a unit
      current. Green's functions are used outside the coil, and a semianalytic
      method is used for the field inside the coil.

      :param x: The x values at which to calculate the Bz response
      :param z: The z values at which to calculate the Bz response

      :returns: The vertical magnetic field response at the x, z coordinates.



   .. py:method:: Bp(x: float | numpy.ndarray, z: float | numpy.ndarray)

      Calculate poloidal magnetic field Bp at (x, z)

      .. rubric:: Notes

      .. math::
          B_p = \sqrt{B_x^2 + B_z^2}

      where `B_x` and `B_z` are the x and z components of the
      magnetic field.



   .. py:method:: F(eqcoil: bluemira.equilibria.coils._grouping.CoilGroup) -> numpy.ndarray

      Calculate the force response at the coil centre including the coil
      self-force.

      .. math::

           \mathbf{F} = \mathbf{j}\times \mathbf{B}
          F_x = IB_z+\dfrac{\mu_0I^2}{4\pi X}\textrm{ln}\bigg(\dfrac{8X}{r_c}-1+\xi/2\bigg)
          F_z = -IBx

      :returns: The force response



   .. py:method:: control_F(coil_grp: bluemira.equilibria.coils._grouping.CoilGroup) -> numpy.ndarray

      Calculates the coil mutual force

              :math:`Fz_{i,j}=-2\pi X_i\mathcal{G}(X_j,Z_j,X_i,Z_i)`

      :returns: The Green's matrix element for the coil mutual force.



   .. py:method:: _stored_greens(green: float | numpy.ndarray)

      Quickly calculate plasma psi, Bx or Bz from Greens functions and current



   .. py:method:: _mix_control_method(x: float | numpy.ndarray, z: float | numpy.ndarray, greens_func: collections.abc.Callable, semianalytic_func: collections.abc.Callable, *, disable_analytic: bool = False) -> float | numpy.ndarray

      Boiler-plate helper function to mixed the Green's function responses
      with the semi-analytic function responses, as a function of position
      outside/inside the coil boundary.

      :param x: The x values at which to calculate the response at
      :param z: The z values at which to calculate the response at
      :param greens_func: greens function
      :param semianalytic_func: semianalytic function

      :returns: Mixed control response



   .. py:method:: _combined_control(inside: numpy.ndarray, x: float | numpy.ndarray, z: float | numpy.ndarray, greens_func: collections.abc.Callable, semianalytic_func: collections.abc.Callable) -> float | numpy.ndarray

      Combine semianalytic and greens function calculation of [psi, Bx, Bz]

      Used for situation where there are calculation points both inside and
      outside the coil boundaries.

      :param inside: array of if the point is inside a coil
      :param x: The x values at which to calculate the response at
      :param z: The z values at which to calculate the response at
      :param greens_func: greens function
      :param semianalytic_func: semianalytic function

      :returns: Combined control response



   .. py:method:: _points_inside_coil(x: float | numpy.array, z: float | numpy.array, *, atol: float = X_TOLERANCE) -> numpy.ndarray

      Determine which points lie inside or on the coil boundary.

      :param x: The x coordinates to check
      :param z: The z coordinates to check
      :param atol: Add an offset, to ensure points very near the edge are counted as
                   being on the edge of a coil

      :returns: The Boolean array of point indices inside/outside the coil boundary



   .. py:method:: _response_greens(greens: collections.abc.Callable, x: numpy.ndarray, z: numpy.ndarray, *, split: bool = False, _quad_x: numpy.ndarray | None = None, _quad_z: numpy.ndarray | None = None, _quad_weight: numpy.ndarray | None = None) -> float | numpy.ndarray

      Calculate [psi, Bx, Bz] response at (x, z) due to a unit
      current using Green's functions.

      :param greens: greens function
      :param x: The x values at which to calculate the response at
      :param z: The z values at which to calculate the response at
      :param split: Flag for if :meth:_combined_control is used
      :param _quad_x: :meth:_combined_control x positions
      :param _quad_z: :meth:_combined_control z positions
      :param _quad_weight: :meth:_combined_control weighting

      :returns: Greens response



   .. py:method:: _response_analytical(semianalytic: collections.abc.Callable, x: numpy.ndarray, z: numpy.ndarray, *, split: bool = False, coil_x: numpy.ndarray | None = None, coil_z: numpy.ndarray | None = None, coil_dx: numpy.ndarray | None = None, coil_dz: numpy.ndarray | None = None) -> numpy.ndarray

      Calculate [psi, Bx, Bz] response at (x, z) due to a unit
      current using semi-analytic method.

      :param semianalytic: semianalytic function
      :param x: The x values at which to calculate the response at
      :param z: The z values at which to calculate the response at
      :param split: Flag for if :meth:_combined_control is used
      :param coil_x: :meth:_combined_control x positions
      :param coil_z: :meth:_combined_control z positions
      :param coil_dx: :meth:_combined_control x positions
      :param coil_dz: :meth:_combined_control z positions

      :returns: Analytical response



.. py:class:: CoilSetFieldsMixin(*, psi_analytic: bool = False, Bx_analytic: bool = True, Bz_analytic: bool = True)

   Bases: :py:obj:`CoilGroupFieldsMixin`

   .. autoapi-inheritance-diagram:: bluemira.equilibria.coils._field.CoilSetFieldsMixin
      :parts: 1
      :private-bases:


   CoilSet magnetic fields mixin.

   Adjust output of coilgroup field calculations dealing with control coils
   or summing over coils


   .. py:attribute:: __slots__
      :value: ()



   .. py:method:: psi(x: numpy.ndarray, z: numpy.ndarray, *, sum_coils: bool = True, control: bool = False) -> numpy.ndarray

      Psi of Coilset

      :param x: The x values at which to calculate the psi response
      :param z: The z values at which to calculate the psi response
      :param sum_coils: sum over coils
      :param control: operations on control coils only

      :returns: Poloidal magnetic flux density



   .. py:method:: Bx(x: numpy.ndarray, z: numpy.ndarray, *, sum_coils: bool = True, control: bool = False) -> numpy.ndarray

      Bx of Coilset

      :param x: The x values at which to calculate the Bx response
      :param z: The z values at which to calculate the Bx response
      :param sum_coils: sum over coils
      :param control: operations on control coils only

      :returns: Radial magnetic field



   .. py:method:: Bz(x: numpy.ndarray, z: numpy.ndarray, *, sum_coils: bool = True, control: bool = False) -> numpy.ndarray

      Bz of Coilset

      :param x: The x values at which to calculate the Bz response
      :param z: The z values at which to calculate the Bz response
      :param sum_coils: sum over coils
      :param control: operations on control coils only

      :returns: Vertical magnetic field



   .. py:method:: dB_d(x: numpy.ndarray, z: numpy.ndarray, *, sum_coils: bool = True, control: bool = False) -> numpy.ndarray

      dB_d of Coilset

      :param x: The x values at which to calculate the dB_d response
      :param z: The z values at which to calculate the dB_d response
      :param sum_coils: sum over coils
      :param control: operations on control coils only

      :rtype: Differential of magnetic field



   .. py:method:: psi_response(x: numpy.ndarray, z: numpy.ndarray, *, sum_coils: bool = False, control: bool = False) -> numpy.ndarray

      Unit psi of Coilset

      :param x: The x values at which to calculate the psi response
      :param z: The z values at which to calculate the psi response
      :param sum_coils: sum over coils
      :param control: operations on control coils only

      :returns: Psi response



   .. py:method:: Bx_response(x: numpy.ndarray, z: numpy.ndarray, *, sum_coils: bool = False, control: bool = False) -> numpy.ndarray

      Unit Bx of Coilset

      :param x: The x values at which to calculate the Bx response
      :param z: The z values at which to calculate the Bx response
      :param sum_coils: sum over coils
      :param control: operations on control coils only

      :returns: Bx response



   .. py:method:: Bz_response(x: numpy.ndarray, z: numpy.ndarray, *, sum_coils: bool = False, control: bool = False) -> numpy.ndarray

      Unit Bz of Coilset

      :param x: The x values at which to calculate the Bz response
      :param z: The z values at which to calculate the Bz response
      :param sum_coils: sum over coils
      :param control: operations on control coils only

      :returns: Bz response



   .. py:method:: dB_d_response(x: numpy.ndarray, z: numpy.ndarray, *, sum_coils: bool = False, control: bool = False) -> numpy.ndarray

      Unit dB_d of Coilset

      :param x: The x values at which to calculate the dB_d response
      :param z: The z values at which to calculate the dB_d response
      :param sum_coils: sum over coils
      :param control: operations on control coils only

      :returns: Differential of magnetic field response



   .. py:method:: control_F(coil_grp: bluemira.equilibria.coils._grouping.CoilGroup, *, control: bool = False) -> numpy.ndarray

      Calculate the coil mutual force

              :math:`Fz_{i,j}=-2\pi X_i\mathcal{G}(X_j,Z_j,X_i,Z_i)`

      :param coil_grp`: the coil group to calculate against
      :param control: operations on control coils only

      :returns: the Green's matrix element for the coil mutual force.



   .. py:method:: _stored_greens(bgreen: numpy.ndarray, *, sum_coils: bool = True, control: bool = False) -> numpy.ndarray

      Uses the Greens mapped dict to quickly compute the Bx,Bz or psi

      :param bgreen: The unit Bx response
      :param sum_coils: sum over coils
      :param control: operations on control coils only

      :returns: Cached Greens response



.. py:class:: CoilFieldsMixin(*, psi_analytic: bool = False, Bx_analytic: bool = True, Bz_analytic: bool = True)

   Bases: :py:obj:`CoilGroupFieldsMixin`

   .. autoapi-inheritance-diagram:: bluemira.equilibria.coils._field.CoilFieldsMixin
      :parts: 1
      :private-bases:


   Coil magnetic fields mixin.

   Add field calculation mechanics to Coils


   .. py:attribute:: __slots__
      :value: ()



   .. py:method:: _points_inside_coil(x: float | numpy.array, z: float | numpy.array, *, atol: float = X_TOLERANCE) -> numpy.ndarray

      Determine which points lie inside or on the coil boundary.

      :param x: The x values to check
      :param z: The z values to check
      :param atol: Add an offset, to ensure points very near the edge are counted as
                   being on the edge of a coil

      :returns: The Boolean array of point indices inside/outside the coil boundary



   .. py:method:: _combined_control(inside: numpy.ndarray, x: numpy.ndarray, z: numpy.ndarray, greens_func: collections.abc.Callable, semianalytic_func: collections.abc.Callable)

      Combine semianalytic and greens function calculation of magnetic field

      Used for situation where there are calculation points both inside and
      outside the coil boundaries.

      :param inside: array of if the point is inside a coil
      :param x: The x values at which to calculate the response at
      :param z: The z values at which to calculate the response at
      :param greens_func: greens function
      :param semianalytic_func: semianalytic function

      :returns: Combined response



   .. py:method:: _response_analytical(semianalytic: collections.abc.Callable, x: numpy.ndarray, z: numpy.ndarray, *_args, **_kwargs) -> numpy.ndarray

      Calculate [psi, Bx, Bz] response at (x, z) due to a unit
      current using semi-analytic method.

      :param semianalytic: semianalytic function
      :param x: The x values at which to calculate the response at
      :param z: The z values at which to calculate the response at

      :returns: Analytical response