magoptlib.sh_gpu
================

.. py:module:: magoptlib.sh_gpu


Functions
---------

.. autoapisummary::

   magoptlib.sh_gpu.normalization_gpu
   magoptlib.sh_gpu.derivative_plm_gpu
   magoptlib.sh_gpu.real_sh_basis_gpu
   magoptlib.sh_gpu.compute_sh_matrix_gpu
   magoptlib.sh_gpu.cart2sph_gpu
   magoptlib.sh_gpu.sph2cart_gpu
   magoptlib.sh_gpu.get_orientations_gpu


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

.. py:function:: normalization_gpu(l, m)

   Compute the normalization constant for real spherical harmonics on the GPU.

   N_{lm} = sqrt((2l+1)/(4π) * (l-|m|)!/(l+|m|)!)

   :param l: Degree of the spherical harmonic.
   :type l: int
   :param m: Order of the spherical harmonic.
   :type m: int

   :returns: The normalization constant as a CuPy scalar.
   :rtype: cp.ndarray (scalar)


.. py:function:: derivative_plm_gpu(l, m, theta, eps=1e-10)

   Compute the derivative of the associated Legendre polynomial P_l^m(cosθ) with respect to θ.

   Uses the recurrence:
       dP/dθ = -sinθ * dP/dx, where x = cosθ

   :param l: Degree of the Legendre polynomial.
   :type l: int
   :param m: Order of the Legendre polynomial.
   :type m: int
   :param theta: Polar angles (radians).
   :type theta: cupy.ndarray
   :param eps: Tolerance for detecting singularities at poles (default is 1e-10).
   :type eps: float, optional

   :returns: The derivative d/dθ of the associated Legendre function evaluated at `theta`.
   :rtype: cupy.ndarray


.. py:function:: real_sh_basis_gpu(l, m, theta, phi, a, r)

   Compute the three parts of the real spherical‐harmonic
   expansion for degree l, order m, at angles theta,phi and radii a (source), r (interest point).

   :param l: Degree of the SH.
   :type l: int
   :param m: Order of the SH.
   :type m: int
   :param theta: Polar angles (radians).
   :type theta: cupy.ndarray
   :param phi: Azimuthal angles (radians).
   :type phi: cupy.ndarray
   :param a: Reference radius for normalization.
   :type a: float or cupy.ndarray
   :param r: Radius at each evaluation point.
   :type r: cupy.ndarray

   :returns: * **radial_part** (*cupy.ndarray*) -- radial basis times (a/r)^(l+2)
             * **theta_part** (*cupy.ndarray*) -- d/dθ basis times (a/r)^(l+2)
             * **phi_part** (*cupy.ndarray*) -- (1/sinθ)·(d/dφ) basis times (a/r)^(l+2)


.. py:function:: compute_sh_matrix_gpu(l_vals, m_vals, phi, theta, a, r)

   Construct the three SH basis matrices.

   :param l_vals: Degrees of the SH basis functions.
   :type l_vals: np.ndarray
   :param m_vals: Orders of the SH basis functions.
   :type m_vals: np.ndarray
   :param phi: Azimuthal angles (radians).
   :type phi: cupy.ndarray
   :param theta: Polar angles (radians).
   :type theta: cupy.ndarray
   :param a: Reference radius.
   :type a: float or cupy.ndarray
   :param r: Actual radius at each point.
   :type r: cupy.ndarray

   :returns: * **Zp** (*cupy.ndarray*) -- Radial SH basis matrix, shape (Np, Nm).
             * **Xp** (*cupy.ndarray*) -- Theta SH basis matrix, shape (Np, Nm).
             * **Yp** (*cupy.ndarray*) -- Phi SH basis matrix, shape (Np, Nm).


.. py:function:: cart2sph_gpu(x, y, z, eps=1e-12)

   Convert Cartesian coordinates to spherical coordinates on the GPU.

   :param x: Cartesian coordinates.
   :type x: cupy.ndarray
   :param y: Cartesian coordinates.
   :type y: cupy.ndarray
   :param z: Cartesian coordinates.
   :type z: cupy.ndarray
   :param eps: Tolerance to avoid division by zero.
   :type eps: float, optional

   :returns: * **r** (*cupy.ndarray*) -- Radius.
             * **theta** (*cupy.ndarray*) -- Polar angle (radians).
             * **phi** (*cupy.ndarray*) -- Azimuthal angle (radians).


.. py:function:: sph2cart_gpu(theta, phi)

   Generate local spherical-to-Cartesian transformation matrices for given angles.

   :param theta: Polar angles (radians).
   :type theta: cupy.ndarray
   :param phi: Azimuthal angles (radians).
   :type phi: cupy.ndarray

   :returns: **M** -- Transformation matrices of shape (N, 3, 3).
   :rtype: cupy.ndarray


.. py:function:: get_orientations_gpu(delta)

   "
   Construct orientation matrices for a Halbach ring based on angles delta.

   Each orientation is defined as Rz(delta) * Ry(90°), rotating the local coordinate system.

   :param delta: Array of angles (radians) defining each magnet's rotation about z.
   :type delta: cupy.ndarray

   :returns: * **orientations** (*cupy.ndarray*) -- Orientation matrices of shape (d, 3, 3), where d is the number of magnets.
             * *Rz[i] =* -- [ c, -s, 0]
               [ s,  c, 0]
               [ 0,  0, 1]