
    \h
+                         S SK Jr  S SKJrJr  S SKJrJr  S SKJ	r	  S SK
Jr  S SKJr  S SKJr  S SKJrJr  S S	KJr  S S
KJr  S SKJrJrJr  \" S5      r " S S\5      rS r " S S\5      rg)    )Expr)DefinedFunctionArgumentIndexError)Ipi)S)Dummy)assoc_legendre)	factorial)Abs	conjugate)exp)sqrt)sincoscotxc                   `    \ rS rSrSr\S 5       rS rSS jrS r	S r
S rS	 rSS
 jrS rSrg)Ynm   a  
Spherical harmonics defined as

.. math::
    Y_n^m(\theta, \varphi) := \sqrt{\frac{(2n+1)(n-m)!}{4\pi(n+m)!}}
                              \exp(i m \varphi)
                              \mathrm{P}_n^m\left(\cos(\theta)\right)

Explanation
===========

``Ynm()`` gives the spherical harmonic function of order $n$ and $m$
in $\theta$ and $\varphi$, $Y_n^m(\theta, \varphi)$. The four
parameters are as follows: $n \geq 0$ an integer and $m$ an integer
such that $-n \leq m \leq n$ holds. The two angles are real-valued
with $\theta \in [0, \pi]$ and $\varphi \in [0, 2\pi]$.

Examples
========

>>> from sympy import Ynm, Symbol, simplify
>>> from sympy.abc import n,m
>>> theta = Symbol("theta")
>>> phi = Symbol("phi")

>>> Ynm(n, m, theta, phi)
Ynm(n, m, theta, phi)

Several symmetries are known, for the order:

>>> Ynm(n, -m, theta, phi)
(-1)**m*exp(-2*I*m*phi)*Ynm(n, m, theta, phi)

As well as for the angles:

>>> Ynm(n, m, -theta, phi)
Ynm(n, m, theta, phi)

>>> Ynm(n, m, theta, -phi)
exp(-2*I*m*phi)*Ynm(n, m, theta, phi)

For specific integers $n$ and $m$ we can evaluate the harmonics
to more useful expressions:

>>> simplify(Ynm(0, 0, theta, phi).expand(func=True))
1/(2*sqrt(pi))

>>> simplify(Ynm(1, -1, theta, phi).expand(func=True))
sqrt(6)*exp(-I*phi)*sin(theta)/(4*sqrt(pi))

>>> simplify(Ynm(1, 0, theta, phi).expand(func=True))
sqrt(3)*cos(theta)/(2*sqrt(pi))

>>> simplify(Ynm(1, 1, theta, phi).expand(func=True))
-sqrt(6)*exp(I*phi)*sin(theta)/(4*sqrt(pi))

>>> simplify(Ynm(2, -2, theta, phi).expand(func=True))
sqrt(30)*exp(-2*I*phi)*sin(theta)**2/(8*sqrt(pi))

>>> simplify(Ynm(2, -1, theta, phi).expand(func=True))
sqrt(30)*exp(-I*phi)*sin(2*theta)/(8*sqrt(pi))

>>> simplify(Ynm(2, 0, theta, phi).expand(func=True))
sqrt(5)*(3*cos(theta)**2 - 1)/(4*sqrt(pi))

>>> simplify(Ynm(2, 1, theta, phi).expand(func=True))
-sqrt(30)*exp(I*phi)*sin(2*theta)/(8*sqrt(pi))

>>> simplify(Ynm(2, 2, theta, phi).expand(func=True))
sqrt(30)*exp(2*I*phi)*sin(theta)**2/(8*sqrt(pi))

We can differentiate the functions with respect
to both angles:

>>> from sympy import Ynm, Symbol, diff
>>> from sympy.abc import n,m
>>> theta = Symbol("theta")
>>> phi = Symbol("phi")

>>> diff(Ynm(n, m, theta, phi), theta)
m*cot(theta)*Ynm(n, m, theta, phi) + sqrt((-m + n)*(m + n + 1))*exp(-I*phi)*Ynm(n, m + 1, theta, phi)

>>> diff(Ynm(n, m, theta, phi), phi)
I*m*Ynm(n, m, theta, phi)

Further we can compute the complex conjugation:

>>> from sympy import Ynm, Symbol, conjugate
>>> from sympy.abc import n,m
>>> theta = Symbol("theta")
>>> phi = Symbol("phi")

>>> conjugate(Ynm(n, m, theta, phi))
(-1)**(2*m)*exp(-2*I*m*phi)*Ynm(n, m, theta, phi)

To get back the well known expressions in spherical
coordinates, we use full expansion:

>>> from sympy import Ynm, Symbol, expand_func
>>> from sympy.abc import n,m
>>> theta = Symbol("theta")
>>> phi = Symbol("phi")

>>> expand_func(Ynm(n, m, theta, phi))
sqrt((2*n + 1)*factorial(-m + n)/factorial(m + n))*exp(I*m*phi)*assoc_legendre(n, m, cos(theta))/(2*sqrt(pi))

See Also
========

Ynm_c, Znm

References
==========

.. [1] https://en.wikipedia.org/wiki/Spherical_harmonics
.. [2] https://mathworld.wolfram.com/SphericalHarmonic.html
.. [3] https://functions.wolfram.com/Polynomials/SphericalHarmonicY/
.. [4] https://dlmf.nist.gov/14.30

c                 h   UR                  5       (       a<  U* n[        R                  U-  [        S[        -  U-  U-  5      -  [        XX45      -  $ UR                  5       (       a  U* n[        XX45      $ UR                  5       (       a(  U* n[        S[        -  U-  U-  5      [        XX45      -  $ g )N)could_extract_minus_signr   NegativeOner   r   r   )clsnmthetaphis        c/var/www/auris/envauris/lib/python3.13/site-packages/sympy/functions/special/spherical_harmonics.pyevalYnm.eval   s     %%''A==!#c"Q$q&*o5A%8MMM))++FEqU((''))$Cr!tAvcz?Su%::: *    c                 N   U R                   u  p#pE[        SU-  S-   S[        -  -  [        X#-
  5      -  [        X#-   5      -  5      [	        [
        U-  U-  5      -  [        X#[        U5      5      -  nUR                  [        [        U5      S-  * S-   5      [        U5      5      $ N         )
argsr   r   r   r   r   r
   r   subsr   )selfhintsr   r   r   r   rvs          r    _eval_expand_funcYnm._eval_expand_func   s    99eAaC!Gad#i&66y7GGHAaCG-aCJ?@ wwtSZ]NQ./U<<r#   c                    US:X  a  [        X5      eUS:X  a  [        X5      eUS:X  ad  U R                  u  p#pEU[        U5      -  [        X#XE5      -  [	        X#-
  X#-   S-   -  5      [        [        * U-  5      -  [        X#S-   XE5      -  -   $ US:X  a%  U R                  u  p#pE[        U-  [        X#XE5      -  $ [        X5      e)Nr'   r&      r(   )r   r)   r   r   r   r   r   )r+   argindexr   r   r   r   s         r    fdiff	Ynm.fdiff   s    q=$T44]$T44]#yyA%E
NSu%::!%!%!),-QBsF;c!UE>WWX Y]#yyA%q53qU000$T44r#   c                      U R                  SS9$ )NTfunc)expandr+   r   r   r   r   kwargss         r    _eval_rewrite_as_polynomialYnm._eval_rewrite_as_polynomial   s     {{{%%r#   c                 ,    U R                  [        5      $ N)rewriter   r9   s         r    _eval_rewrite_as_sinYnm._eval_rewrite_as_sin   s    ||C  r#   c                     SSK JnJn  U" U R                  SS95      nUR	                  [        [        U5      5      [        U5      05      nU" U" U5      5      $ )Nr   )simplifytrigsimpTr6   )sympy.simplifyrC   rD   r8   xreplacer   r   )	r+   r   r   r   r   r:   rC   rD   terms	            r    _eval_rewrite_as_cosYnm._eval_rewrite_as_cos   sJ    5 ./}}c#e*oc%j9:''r#   c                 n    U R                   u  pp4[        R                  U-  U R                  X* X45      -  $ r>   )r)   r   r   r7   )r+   r   r   r   r   s        r    _eval_conjugateYnm._eval_conjugate   s1    99e}}a$))Ar5">>>r#   c                    U R                   u  p4pV[        SU-  S-   S[        -  -  [        X4-
  5      -  [        X4-   5      -  5      [	        XF-  5      -  [        X4[	        U5      5      -  n[        SU-  S-   S[        -  -  [        X4-
  5      -  [        X4-   5      -  5      [        XF-  5      -  [        X4[	        U5      5      -  nXx4$ r%   )r)   r   r   r   r   r
   r   )	r+   deepr,   r   r   r   r   reims	            r    as_real_imagYnm.as_real_imag   s    99eAaC!Gad#i&66y7GGH!%j)!E
;<AaC!Gad#i&66y7GGH!%j)!E
;<xr#   c                    SSK JnJn  U R                  S   R	                  U5      nU R                  S   R	                  U5      nU R                  S   R	                  U5      nU R                  S   R	                  U5      nU" U5         UR                  XEXg5      nS S S 5        [        R                  " WU5      $ ! , (       d  f       N%= f)Nr   )mpworkprecr'   r&   r1   )mpmathrT   rU   r)   
_to_mpmath	spherharmr   _from_mpmath)	r+   precrT   rU   r   r   r   r   ress	            r    _eval_evalfYnm._eval_evalf   s     	(IIaL##D)IIaL##D)		!''-iil%%d+d^,,qU0C   d++ ^s   	B;;
C	 N)r(   )T)__name__
__module____qualname____firstlineno____doc__classmethodr!   r.   r3   r;   r@   rH   rK   rQ   r\   __static_attributes__r^   r#   r    r   r      sE    wr 
; 
;=5&&
!(?
,r#   r   c                 ,    [        [        XX#5      5      $ )a  
Conjugate spherical harmonics defined as

.. math::
    \overline{Y_n^m(\theta, \varphi)} := (-1)^m Y_n^{-m}(\theta, \varphi).

Examples
========

>>> from sympy import Ynm_c, Symbol, simplify
>>> from sympy.abc import n,m
>>> theta = Symbol("theta")
>>> phi = Symbol("phi")
>>> Ynm_c(n, m, theta, phi)
(-1)**(2*m)*exp(-2*I*m*phi)*Ynm(n, m, theta, phi)
>>> Ynm_c(n, m, -theta, phi)
(-1)**(2*m)*exp(-2*I*m*phi)*Ynm(n, m, theta, phi)

For specific integers $n$ and $m$ we can evaluate the harmonics
to more useful expressions:

>>> simplify(Ynm_c(0, 0, theta, phi).expand(func=True))
1/(2*sqrt(pi))
>>> simplify(Ynm_c(1, -1, theta, phi).expand(func=True))
sqrt(6)*exp(I*(-phi + 2*conjugate(phi)))*sin(theta)/(4*sqrt(pi))

See Also
========

Ynm, Znm

References
==========

.. [1] https://en.wikipedia.org/wiki/Spherical_harmonics
.. [2] https://mathworld.wolfram.com/SphericalHarmonic.html
.. [3] https://functions.wolfram.com/Polynomials/SphericalHarmonicY/

)r   r   )r   r   r   r   s       r    Ynm_crg      s    P Su*++r#   c                   (    \ rS rSrSr\S 5       rSrg)Znmi  a  
Real spherical harmonics defined as

.. math::

    Z_n^m(\theta, \varphi) :=
    \begin{cases}
      \frac{Y_n^m(\theta, \varphi) + \overline{Y_n^m(\theta, \varphi)}}{\sqrt{2}} &\quad m > 0 \\
      Y_n^m(\theta, \varphi) &\quad m = 0 \\
      \frac{Y_n^m(\theta, \varphi) - \overline{Y_n^m(\theta, \varphi)}}{i \sqrt{2}} &\quad m < 0 \\
    \end{cases}

which gives in simplified form

.. math::

    Z_n^m(\theta, \varphi) =
    \begin{cases}
      \frac{Y_n^m(\theta, \varphi) + (-1)^m Y_n^{-m}(\theta, \varphi)}{\sqrt{2}} &\quad m > 0 \\
      Y_n^m(\theta, \varphi) &\quad m = 0 \\
      \frac{Y_n^m(\theta, \varphi) - (-1)^m Y_n^{-m}(\theta, \varphi)}{i \sqrt{2}} &\quad m < 0 \\
    \end{cases}

Examples
========

>>> from sympy import Znm, Symbol, simplify
>>> from sympy.abc import n, m
>>> theta = Symbol("theta")
>>> phi = Symbol("phi")
>>> Znm(n, m, theta, phi)
Znm(n, m, theta, phi)

For specific integers n and m we can evaluate the harmonics
to more useful expressions:

>>> simplify(Znm(0, 0, theta, phi).expand(func=True))
1/(2*sqrt(pi))
>>> simplify(Znm(1, 1, theta, phi).expand(func=True))
-sqrt(3)*sin(theta)*cos(phi)/(2*sqrt(pi))
>>> simplify(Znm(2, 1, theta, phi).expand(func=True))
-sqrt(15)*sin(2*theta)*cos(phi)/(4*sqrt(pi))

See Also
========

Ynm, Ynm_c

References
==========

.. [1] https://en.wikipedia.org/wiki/Spherical_harmonics
.. [2] https://mathworld.wolfram.com/SphericalHarmonic.html
.. [3] https://functions.wolfram.com/Polynomials/SphericalHarmonicY/

c                 ,   UR                   (       a'  [        XX45      [        XX45      -   [        S5      -  nU$ UR                  (       a  [        XX45      $ UR
                  (       a.  [        XX45      [        XX45      -
  [        S5      [        -  -  nU$ g )Nr&   )is_positiver   rg   r   is_zerois_negativer   )r   r   r   r   r   zzs         r    r!   Znm.evalE  sy    ==aE'%e*AAT!WLBIYYqU((]]aE'%e*AAd1gaiPBI r#   r^   N)r_   r`   ra   rb   rc   rd   r!   re   r^   r#   r    ri   ri     s    7r  r#   ri   N)sympy.core.exprr   sympy.core.functionr   r   sympy.core.numbersr   r   sympy.core.singletonr   sympy.core.symbolr	   sympy.functionsr
   (sympy.functions.combinatorial.factorialsr   $sympy.functions.elementary.complexesr   r   &sympy.functions.elementary.exponentialr   (sympy.functions.elementary.miscellaneousr   (sympy.functions.elementary.trigonometricr   r   r   _xr   rg   ri   r^   r#   r    <module>r|      sU      C $ " # * > ? 6 9 B B
3ZN,/ N,b(,VC/ Cr#   