bluemira.magnetostatics.greens
==============================

.. py:module:: bluemira.magnetostatics.greens

.. autoapi-nested-parse::

   Green's functions mappings for psi, Bx, and Bz



Functions
---------

.. autoapisummary::

   bluemira.magnetostatics.greens.greens_psi
   bluemira.magnetostatics.greens.greens_dpsi_dx
   bluemira.magnetostatics.greens.greens_dbz_dx
   bluemira.magnetostatics.greens.greens_dpsi_dz
   bluemira.magnetostatics.greens.greens_Bx
   bluemira.magnetostatics.greens.greens_Bz
   bluemira.magnetostatics.greens.greens_all


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

.. py:function:: greens_psi(xc: float | numpy.ndarray, zc: float | numpy.ndarray, x: float | numpy.ndarray, z: float | numpy.ndarray, d_xc: float = 0, d_zc: float = 0) -> float | numpy.ndarray

   Calculate poloidal flux at (x, z) due to a unit current at (xc, zc)
   using a Greens function.

   :param xc: Coil x coordinates [m]
   :param zc: Coil z coordinates [m]
   :param x: Calculation x locations
   :param z: Calculation z locations
   :param d_xc: The coil half-width (overload argument)
   :param d_zc: The coil half-height (overload argument)

   :returns: Poloidal magnetic flux per radian response at (x, z)

   :raises ZeroDivisionError: if xc <= 0

   .. rubric:: Notes

   :math:`G_{\psi}(x_{c}, z_{c}; x, z) = \dfrac{{\mu}_{0}}{2{\pi}}`
   :math:`\dfrac{\sqrt{xx_{c}}}{k}`
   :math:`[(2-\mathbf{K}(k^2)-2\mathbf{E}(k^2)]`

   Where:
       :math:`k^{2}\equiv\dfrac{4xx_{c}}{(x+x_{c})^{2}+(z-z_{c})^{2}}`

       :math:`\mathbf{K} \equiv` complete elliptic integral of the first kind

       :math:`\mathbf{E} \equiv` complete elliptic integral of the second kind


.. py:function:: greens_dpsi_dx(xc: float | numpy.ndarray, zc: float | numpy.ndarray, x: float | numpy.ndarray, z: float | numpy.ndarray, d_xc: float = 0, d_zc: float = 0) -> float | numpy.ndarray

   Calculate the radial derivative of the poloidal flux at (x, z)
   due to a unit current at (xc, zc) using a Greens function.

   :param xc: Coil x coordinates [m]
   :param zc: Coil z coordinates [m]
   :param x: Calculation x locations
   :param z: Calculation z locations
   :param d_xc: The coil half-width (overload argument)
   :param d_zc: The coil half-height (overload argument)

   :returns: Radial derivative of the poloidal flux response at (x, z)

   .. rubric:: Notes

   :math:`G_{\dfrac{\partial \psi}{\partial x}}(x_{c}, z_{c}; x, z) =`
   :math:`\dfrac{\mu_0}{2\pi}`
   :math:`\dfrac{1}{u}`
   :math:`[\dfrac{w^2}{d^2}\mathbf{E}(k^2)+\mathbf{K}(k^2)]`

   Where:
       :math:`h^{2}\equiv z_{c}-z`

       :math:`u^2\equiv(x+x_{c})^2+h^2`

       :math:`d^{2}\equiv (x - x_{c})^2 + h^2`

       :math:`w^{2}\equiv x^2 -x_{c}^2 - h^2`

       :math:`k^{2}\equiv\dfrac{4xx_{c}}{(x+x_{c})^{2}+(z-z_{c})^{2}}`

       :math:`\mathbf{K} \equiv` complete elliptic integral of the first kind

       :math:`\mathbf{E} \equiv` complete elliptic integral of the second kind

   The implementation used here refactors the above to avoid some zero divisions.


.. py:function:: greens_dbz_dx(xc: float | numpy.ndarray, zc: float | numpy.ndarray, x: float | numpy.ndarray, z: float | numpy.ndarray) -> float | numpy.ndarray

   Calculate :math:`\frac{dB_z}{dx}` (= :math:`\frac{dB_x}{dz}` for vacuum)

   Get the radial gradient of the vertical magnetic field due to a circular filament.

   unit: [N/A/m^2]

   .. math::

       \frac{dB_z}{dx} = \frac{dB_x}{dz} = \frac{\mu_0 I}{2 \pi}\left(
           - \frac{(K+E\frac{g_1}{g_2}) g_{3r}}{2 g_3^{\frac{3}{2}}}
           + \frac{- E \frac{g_{1r}}{g_2} - E \frac{g_1 g_{2r}}{g_2^2}
                   + \frac{dE}{dk} \frac{g_1}{g_2} \text{dkdr}
                   + \frac{dK}{dk} \text{dkdr}
                   }{\sqrt{g_3}}
       \right)

   where :math:`K = K(k^2), E = E(k^2)`.

   :returns: the gradient to the magnetic field


.. py:function:: greens_dpsi_dz(xc: float | numpy.ndarray, zc: float | numpy.ndarray, x: float | numpy.ndarray, z: float | numpy.ndarray, d_xc: float = 0, d_zc: float = 0) -> float | numpy.ndarray

   Calculate the vertical derivative of the poloidal flux at (x, z)
   due to a unit current at (xc, zc) using a Greens function.

   :param xc: Coil x coordinates [m]
   :param zc: Coil z coordinates [m]
   :param x: Calculation x locations
   :param z: Calculation z locations
   :param d_xc: The coil half-width (overload argument)
   :param d_zc: The coil half-height (overload argument)

   :returns: Vertical derivative of the poloidal flux response at (x, z)

   .. rubric:: Notes

   :math:`G_{\dfrac{\partial \psi}{\partial z}}(x_{c}, z_{c}; x, z) =`
   :math:`\dfrac{\mu_0}{2\pi}`
   :math:`\dfrac{h}{u}`
   :math:`[\mathbf{K}(k^2) - \dfrac{v^2}{d^2}\mathbf{E}(k^2)]`

   Where:
       :math:`h^{2}\equiv z_{c}-z`

       :math:`u^2\equiv(x+x_{c})^2+h^2`

       :math:`d^{2}\equiv (x - x_{c})^2 + h^2`

       :math:`v^{2}\equiv x^2 +x_{c}^2 + h^2`

       :math:`k^{2}\equiv\dfrac{4xx_{c}}{(x+x_{c})^{2}+(z-z_{c})^{2}}`

       :math:`\mathbf{K} \equiv` complete elliptic integral of the first kind

       :math:`\mathbf{E} \equiv` complete elliptic integral of the second kind

   The implementation used here refactors the above to avoid some zero divisions.


.. py:function:: greens_Bx(xc: float | numpy.ndarray, zc: float | numpy.ndarray, x: float | numpy.ndarray, z: float | numpy.ndarray, d_xc: float = 0, d_zc: float = 0) -> float | numpy.ndarray

   Calculate radial magnetic field at (x, z) due to unit current at (xc, zc)
   using a Greens function.

   :param xc: Coil x coordinates [m]
   :param zc: Coil z coordinates [m]
   :param x: Calculation x locations
   :param z: Calculation z locations
   :param d_xc: The coil half-width (overload argument)
   :param d_zc: The coil half-height (overload argument)

   :returns: Radial magnetic field response at (x, z)

   :raises ZeroDivisionError: if x == 0

   .. rubric:: Notes

   :math:`G_{B_{x}}(x_{c}, z_{c}; x, z) = -\dfrac{1}{x}`
   :math:`G_{\dfrac{\partial \psi}{\partial z}}`
   :math:`(x_{c}, z_{c}; x, z)`


.. py:function:: greens_Bz(xc: float | numpy.ndarray, zc: float | numpy.ndarray, x: float | numpy.ndarray, z: float | numpy.ndarray, d_xc: float = 0, d_zc: float = 0) -> float | numpy.ndarray

   Calculate vertical magnetic field at (x, z) due to unit current at (xc, zc)
   using a Greens function.

   :param xc: Coil x coordinates [m]
   :param zc: Coil z coordinates [m]
   :param x: Calculation x locations
   :param z: Calculation z locations
   :param d_xc: The coil half-width (overload argument)
   :param d_zc: The coil half-height (overload argument)

   :returns: Vertical magnetic field response at (x, z)

   :raises ZeroDivisionError: if x == 0

   .. rubric:: Notes

   :math:`G_{B_{z}}(x_{c}, z_{c}; x, z) = \dfrac{1}{x}`
   :math:`G_{\dfrac{\partial \psi}{\partial x}}`
   :math:`(x_{c}, z_{c}; x, z)`


.. py:function:: greens_all(xc: float | numpy.ndarray, zc: float | numpy.ndarray, x: float | numpy.ndarray, z: float | numpy.ndarray) -> tuple[float | numpy.ndarray, float | numpy.ndarray, float | numpy.ndarray]

   Speed optimisation of Green's functions for psi, Bx, and Bz

   :param xc: Coil x coordinates [m]
   :param zc: Coil z coordinates [m]
   :param x: Calculation x locations
   :param z: Calculation z locations

   :returns: * *psi* -- Poloidal magnetic flux per radian response at (x, z)
             * *Bx* -- Radial magnetic field response at (x, z)
             * *Bz* -- Vertical magnetic field response at (x, z)

   :raises ZeroDivisionError: if xc <= 0
       if x <= 0