
    \h                    2   S 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
  SSKJr  SSK	JrJrJrJr  SS	KJr  SS
KJr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!  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/J0r0  SSK1J2r2J3r3J4r4  SSK5J6r6  SSK7J8r8  SSK9J:r:J;r;  SSK<J=r=  SSK>J?r?  SSK@JArA  / SQrBS rC " S S 5      rD " S! S"\D\/5      rE " S# S$\D\/5      rF " S% S&\D\.5      rG " S' S(\D\.5      rH " S) S*\D\.5      rI " S+ S,\D\.5      rJ " S- S.\05      rK " S/ S0\5      rL\G" S15      rM\H" S15      rN\I" S15      rO\J" S15      rP\E" S15      rQ\F" S15      rR " S2 S3\45      rS " S4 S5\S\35      rT " S6 S7\S\25      rU " S8 S9\S\35      rV " S: S;\S\25      rW " S< S=\S\35      rX " S> S?\S\25      rYS@ rZ " SA SB\S5      r[ " SC SD\[\35      r\ " SE SF\[\25      r] " SG SH\[\35      r^ " SI SJ\[\25      r_ " SK SL\[\35      r` " SM SN\[\25      raSUSP jrbSQ rcSVSR jrdSS reST rfgO)Wz$Quantum mechanical angular momentum.    )Sum)Add)Tuple)Expr)
int_valued)Mul)IIntegerRationalpi)S)Dummysymbols)sympify)binomial	factorial)exp)sqrt)cossin)simplify)zeros)
prettyForm
stringPictpretty_symbol)QExpr)HermitianOperatorOperatorUnitaryOperator)BraKetState)KroneckerDelta)hbar)ComplexSpaceDirectSumHilbertSpace)TensorProduct)CG)qapply)m_valuesJplusJminusJxJyJzJ2RotationWignerDJxKetJxBraJyKetJyBraJzKetJzBraJzOpJ2OpJxKetCoupledJxBraCoupledJyKetCoupledJyBraCoupledJzKetCoupledJzBraCoupledcoupleuncouplec                     [        U 5      n SU -  S-   nUR                  (       a  US:  d  [        SU -  5      eU[        [	        SU -  S-   5      5       Vs/ s H  o U-
  PM	     sn4$ s  snf )N      r   z<Only integer or half-integer values allowed for j, got: : %r)r   
is_Integer
ValueErrorrangeint)jsizeis      R/var/www/auris/envauris/lib/python3.13/site-packages/sympy/physics/quantum/spin.pyr+   r+   ?   sn    
AQ37D??$(JQN
 	
 s1Q37|!45!4Aa%!45555s   A(c                       \ rS rSrSr\S 5       r\S 5       rS r	S r
S rS rS	 rS
 rS rS rS rS rS rS rS rS rSrg)
SpinOpBaseN   zBase class for spin operators.c                 4    [        [        R                  5      $ Nr&   r   Infinityclslabels     rN   _eval_hilbert_spaceSpinOpBase._eval_hilbert_spaceQ        AJJ''    c                      U R                   S   $ Nr   argsselfs    rN   nameSpinOpBase.nameV       yy|r\   c                 :    U R                   < U R                  < 3$ rS   rc   _coordrb   printerr`   s      rN   _print_contentsSpinOpBase._print_contentsZ   s    DKK00r\   c                     [        [        U R                  5      5      n[        U R                  5      nU R	                  X45      $ rS   )r   strrc   rh   _print_subscript_prettyrb   rj   r`   abs        rN   _print_contents_pretty!SpinOpBase._print_contents_pretty]   s3    s499~&t{{#++A11r\   c                 <    U R                   < SU R                  < 3$ )N_rg   ri   s      rN   _print_contents_latex SpinOpBase._print_contents_latexb   s     IIt{{44r\   c           	          UR                  S[        R                  5      n[        U5      u  pE[	        XD5      n[        U5       H2  n[        U5       H   nU R                  X5U   X5U   5      n	XXx4'   M"     M4     U$ )NrK   )getr   Halfr+   r   rI   matrix_element)
rb   basisoptionsrK   rL   mvalsresultpqmes
             rN   _represent_baseSpinOpBase._represent_basee   sq    KKQVV$qkt"tA4[((!HaqB!qt !  r\   c                 :   UR                  U R                  5      n[        U[        5      (       a  [        UR
                  -  U-  nO6[        U[        5      (       a  U R                  " U40 UD6nO[        X-  5      nXPU-  :X  a  [        eUR                  U5      $ rS   )
rewriter}   
isinstancer#   r%   mr   _apply_operator_Sumr*   NotImplementedError)rb   ket
orig_basisr~   staterets         rN   	_apply_opSpinOpBase._apply_opo   s    DJJ'eU##<&Cs##**5<G<C$Cu*%%{{:&&r\   c                 *    U R                   " US40 UD6$ Nr.   r   rb   r   r~   s      rN   _apply_operator_JxKet SpinOpBase._apply_operator_JxKet}       ~~c43733r\   c                 *    U R                   " US40 UD6$ r   r   r   s      rN   _apply_operator_JxKetCoupled'SpinOpBase._apply_operator_JxKetCoupled   r   r\   c                 *    U R                   " US40 UD6$ Nr/   r   r   s      rN   _apply_operator_JyKet SpinOpBase._apply_operator_JyKet   r   r\   c                 *    U R                   " US40 UD6$ r   r   r   s      rN   _apply_operator_JyKetCoupled'SpinOpBase._apply_operator_JyKetCoupled   r   r\   c                 *    U R                   " US40 UD6$ Nr0   r   r   s      rN   _apply_operator_JzKet SpinOpBase._apply_operator_JzKet   r   r\   c                 *    U R                   " US40 UD6$ r   r   r   s      rN   _apply_operator_JzKetCoupled'SpinOpBase._apply_operator_JzKetCoupled   r   r\   c                    [        U [        [        [        45      (       d  [        e/ n[        [        UR                  5      5       H  n/ nUR                  UR                  S U 5        UR                  U R                  UR                  U   5      5        UR                  UR                  US-   S  5        UR                  UR                  " U6 5        M     [        U6 R                  5       $ NrF   )r   JxOpJyOpr:   r   rI   lenr`   extendappend_apply_operator	__class__r   expand)rb   tpr~   r   nargs         rN   _apply_operator_TensorProduct(SpinOpBase._apply_operator_TensorProduct   s     $tT 233%%s277|$ACJJrwwr{#JJt++BGGAJ78JJrwwq1uv'MM",,,- % F|""$$r\   c                     [        XR                  -  5      nX0UR                  -  :X  a  [        e[        U/UR                  Q76 $ rS   )r*   functionr   r   limits)rb   sr~   new_funcs       rN   r   SpinOpBase._apply_operator_Sum   s:    $zz/*AJJ&%%8'ahh''r\   c                 >    U R                  5       R                  5       $ rS   )_represent_default_basistracerb   r~   s     rN   _eval_traceSpinOpBase._eval_trace   s     ,,.4466r\    N)__name__
__module____qualname____firstlineno____doc__classmethodrY   propertyrc   rk   rs   rw   r   r   r   r   r   r   r   r   r   r   r   __static_attributes__r   r\   rN   rP   rP   N   sq    (( (  12
5'444444%(7r\   rP   c                   J    \ rS rSrSrSrSrS rS rS r	S r
S	 rS
 rS rSrg)JplusOp   zThe J+ operator.+r0   c                 @    S[         -  [        U R                  5      -  $ NrE   )r%   r:   rc   rb   others     rN   _eval_commutator_JminusOp!JplusOp._eval_commutator_JminusOp   s    vd499o%%r\   c                 P   UR                   nUR                  nUR                  (       a&  UR                  (       a  XC:  a  [        R                  $ [
        [        X3[        R                  -   -  XD[        R                  -   -  -
  5      -  [        X4[        R                  -   5      -  $ rS   	rK   r   	is_Numberr   Zeror%   r   Oner8   rb   r   r~   rK   r   s        rN   r   JplusOp._apply_operator_JzKet   sj    EEEE;;1;;vvvDII677aQUU8KKKr\   c                    UR                   nUR                  nUR                  nUR                  nUR                  (       a&  UR                  (       a  XC:  a  [
        R                  $ [        [        X3[
        R                  -   -  XD[
        R                  -   -  -
  5      -  [        X4[
        R                  -   XV5      -  $ rS   rK   r   jncouplingr   r   r   r%   r   r   r@   rb   r   r~   rK   r   r   r   s          rN   r   $JplusOp._apply_operator_JzKetCoupled   s    EEEEVV<<;;1;;vvvDII677QAEE	SU8```r\   c                     [         [        X[        R                  -   -  XD[        R                  -   -  -
  5      -  nU[	        X$S-   5      -  nU[	        X5      -  nU$ r   r%   r   r   r   r$   rb   rK   r   jpmpr   s         rN   r|   JplusOp.matrix_element   Q    d1!%%i=2AEEz?:;;.F++.''r\   c                 &    U R                   " S0 UD6$ NrS   _represent_JzOpr   s     rN   r    JplusOp._represent_default_basis       ##4G44r\   c                 (    U R                   " U40 UD6$ rS   r   rb   r}   r~   s      rN   r   JplusOp._represent_JzOp       ##E5W55r\   c                 J    [        US   5      [        [        US   5      -  -   $ r^   r   r	   r   rb   r`   kwargss      rN   _eval_rewrite_as_xyzJplusOp._eval_rewrite_as_xyz   !    DG}qd1g..r\   r   N)r   r   r   r   r   rh   r}   r   r   r   r|   r   r   r   r   r   r\   rN   r   r      s4    FE&La56/r\   r   c                   D    \ rS rSrSrSrSrS rS rS r	S r
S	 rS
 rSrg)JminusOp   zThe J- operator.-r0   c                 R   UR                   nUR                  nUR                  (       a'  UR                  (       a  XC* ::  a  [        R                  $ [
        [        X3[        R                  -   -  XD[        R                  -
  -  -
  5      -  [        X4[        R                  -
  5      -  $ rS   r   r   s        rN   r   JminusOp._apply_operator_JzKet   sl    EEEE;;1;;BwvvDII677aQUU8KKKr\   c                    UR                   nUR                  nUR                  nUR                  nUR                  (       a'  UR                  (       a  XC* ::  a  [
        R                  $ [        [        X3[
        R                  -   -  XD[
        R                  -
  -  -
  5      -  [        X4[
        R                  -
  XV5      -  $ rS   r   r   s          rN   r   %JminusOp._apply_operator_JzKetCoupled   s    EEEEVV<<;;1;;BwvvDII677QAEE	SU8```r\   c                     [         [        X[        R                  -   -  XD[        R                  -
  -  -
  5      -  nU[	        X$S-
  5      -  nU[	        X5      -  nU$ r   r   r   s         rN   r|   JminusOp.matrix_element   r   r\   c                 &    U R                   " S0 UD6$ r   r   r   s     rN   r   !JminusOp._represent_default_basis   r   r\   c                 (    U R                   " U40 UD6$ rS   r   r   s      rN   r   JminusOp._represent_JzOp   r   r\   c                 J    [        US   5      [        [        US   5      -  -
  $ r^   r   r   s      rN   r   JminusOp._eval_rewrite_as_xyz   r   r\   r   N)r   r   r   r   r   rh   r}   r   r   r|   r   r   r   r   r   r\   rN   r   r      s/    FELa56/r\   r   c                   J    \ rS rSrSrSrSrS rS rS r	S r
S	 rS
 rS rSrg)r   i  zThe Jx operator.xr.   c                 H    [         [        -  [        U R                  5      -  $ rS   )r	   r%   r:   rc   r   s     rN   _eval_commutator_JyOpJxOp._eval_commutator_JyOp	      vd499o%%r\   c                 J    [         * [        -  [        U R                  5      -  $ rS   r	   r%   r   rc   r   s     rN   _eval_commutator_JzOpJxOp._eval_commutator_JzOp      r$wtDII&&r\   c                     [        U R                  5      R                  " U40 UD6n[        U R                  5      R                  " U40 UD6nX4-   [	        S5      -  $ r   )r   rc   r   r   r
   rb   r   r~   r   jms        rN   r   JxOp._apply_operator_JzKet  sO    TYY55cEWEdii 66sFgF##r\   c                     [        U R                  5      R                  " U40 UD6n[        U R                  5      R                  " U40 UD6nX4-   [	        S5      -  $ r   )r   rc   r   r   r
   r  s        rN   r   !JxOp._apply_operator_JzKetCoupled  sO    TYY<<SLGLdii ==cMWM##r\   c                 &    U R                   " S0 UD6$ r   r   r   s     rN   r   JxOp._represent_default_basis  r   r\   c                     [        U R                  5      R                  " U40 UD6n[        U R                  5      R                  " U40 UD6nX4-   [	        S5      -  $ r   )r   rc   r   r   r
   rb   r}   r~   r   r  s        rN   r   JxOp._represent_JzOp  sO    TYY//AAdii 00B'B##r\   c                 B    [        US   5      [        US   5      -   S-  $ Nr   rE   )r   r   r   s      rN   _eval_rewrite_as_plusminusJxOp._eval_rewrite_as_plusminus!  s$    Q 8DG#44a77r\   r   N)r   r   r   r   r   rh   r}   r  r  r   r   r   r   r&  r   r   r\   rN   r   r     s2    FE&'$
$
5$
8r\   r   c                   J    \ rS rSrSrSrSrS rS rS r	S r
S	 rS
 rS rSrg)r   i%  zThe Jy operator.yr/   c                 H    [         [        -  [        U R                  5      -  $ rS   r	   r%   r   rc   r   s     rN   r  JyOp._eval_commutator_JzOp,  r  r\   c                 J    [         * [        -  [        U R                  5      -  $ rS   )r	   r%   r;   rc   r   s     rN   _eval_commutator_JxOpJyOp._eval_commutator_JxOp/  r  r\   c                     [        U R                  5      R                  " U40 UD6n[        U R                  5      R                  " U40 UD6nX4-
  [	        S5      [
        -  -  $ r   )r   rc   r   r   r
   r	   r  s        rN   r   JyOp._apply_operator_JzKet2  sS    TYY55cEWEdii 66sFgF'!*Q,''r\   c                     [        U R                  5      R                  " U40 UD6n[        U R                  5      R                  " U40 UD6nX4-
  [	        S5      [
        -  -  $ r   )r   rc   r   r   r
   r	   r  s        rN   r   !JyOp._apply_operator_JzKetCoupled7  sS    TYY<<SLGLdii ==cMWM'!*Q,''r\   c                 &    U R                   " S0 UD6$ r   r   r   s     rN   r   JyOp._represent_default_basis<  r   r\   c                     [        U R                  5      R                  " U40 UD6n[        U R                  5      R                  " U40 UD6nX4-
  [	        S5      [
        -  -  $ r   )r   rc   r   r   r
   r	   r"  s        rN   r   JyOp._represent_JzOp?  sS    TYY//AAdii 00B'B'!*Q,''r\   c                 P    [        US   5      [        US   5      -
  S[        -  -  $ r%  )r   r   r	   r   s      rN   r&  JyOp._eval_rewrite_as_plusminusD  s(    Q 8DG#44qs;;r\   r   N)r   r   r   r   r   rh   r}   r  r.  r   r   r   r   r&  r   r   r\   rN   r   r   %  s2    FE&'(
(
5(
<r\   r   c                   J    \ rS rSrSrSrSrS rS rS r	S r
S	 rS
 rS rSrg)r:   iH  zThe Jz operator.zr0   c                 H    [         [        -  [        U R                  5      -  $ rS   r  r   s     rN   r.  JzOp._eval_commutator_JxOpO  r  r\   c                 J    [         * [        -  [        U R                  5      -  $ rS   r+  r   s     rN   r  JzOp._eval_commutator_JyOpR  r  r\   c                 :    [         [        U R                  5      -  $ rS   )r%   r   rc   r   s     rN   _eval_commutator_JplusOpJzOp._eval_commutator_JplusOpU  s    GDII&&&r\   c                 <    [         * [        U R                  5      -  $ rS   )r%   r   rc   r   s     rN   r   JzOp._eval_commutator_JminusOpX  s    uXdii(((r\   c                 P    [         U-  nU[        X$5      -  nU[        X5      -  nU$ rS   r%   r$   r   s         rN   r|   JzOp.matrix_element[  s.    b.''.''r\   c                 &    U R                   " S0 UD6$ r   r   r   s     rN   r   JzOp._represent_default_basisa  r   r\   c                 (    U R                   " U40 UD6$ rS   r   r   s      rN   r   JzOp._represent_JzOpd  r   r\   r   N)r   r   r   r   r   rh   r}   r.  r  rA  r   r|   r   r   r   r   r\   rN   r:   r:   H  s2    FE&'')56r\   r:   c                       \ rS rSrSrSrS rS rS rS r	S r
S	 rS
 rS rS rS rS rS rS rS rS rS rS rS rSrg)r;   ih  zThe J^2 operator.2c                 "    [         R                  $ rS   r   r   r   s     rN   r.  J2Op._eval_commutator_JxOpm      vvr\   c                 "    [         R                  $ rS   rO  r   s     rN   r  J2Op._eval_commutator_JyOpp  rQ  r\   c                 "    [         R                  $ rS   rO  r   s     rN   r  J2Op._eval_commutator_JzOps  rQ  r\   c                 "    [         R                  $ rS   rO  r   s     rN   rA  J2Op._eval_commutator_JplusOpv  rQ  r\   c                 "    [         R                  $ rS   rO  r   s     rN   r   J2Op._eval_commutator_JminusOpy  rQ  r\   c                 D    UR                   n[        S-  U-  US-   -  U-  $ NrE   rF   rK   r%   rb   r   r~   rK   s       rN   r   J2Op._apply_operator_JxKet|  '    EEQwqy!a% $$r\   c                 D    UR                   n[        S-  U-  US-   -  U-  $ r[  r\  r]  s       rN   r   !J2Op._apply_operator_JxKetCoupled  r_  r\   c                 D    UR                   n[        S-  U-  US-   -  U-  $ r[  r\  r]  s       rN   r   J2Op._apply_operator_JyKet  r_  r\   c                 D    UR                   n[        S-  U-  US-   -  U-  $ r[  r\  r]  s       rN   r   !J2Op._apply_operator_JyKetCoupled  r_  r\   c                 D    UR                   n[        S-  U-  US-   -  U-  $ r[  r\  r]  s       rN   r   J2Op._apply_operator_JzKet  r_  r\   c                 D    UR                   n[        S-  U-  US-   -  U-  $ r[  r\  r]  s       rN   r   !J2Op._apply_operator_JzKetCoupled  r_  r\   c                 b    [         S-  U-  US-   -  nU[        X$5      -  nU[        X5      -  nU$ r[  rF  r   s         rN   r|   J2Op.matrix_element  s;    '1a!e$.''.''r\   c                 &    U R                   " S0 UD6$ r   r   r   s     rN   r   J2Op._represent_default_basis  r   r\   c                 (    U R                   " U40 UD6$ rS   r   r   s      rN   r   J2Op._represent_JzOp  r   r\   c                 \    [        [        U R                  5      5      n[        S5      nX4-  $ )NrM  )r   rn   rc   rp   s        rN   rs   J2Op._print_contents_pretty  s$    s499~&sOtr\   c                 2    S[        U R                  5      -  $ )Nz%s^2)rn   rc   ri   s      rN   rw   J2Op._print_contents_latex  s    TYY''r\   c                 l    [        US   5      S-  [        US   5      S-  -   [        US   5      S-  -   $ r%  )r   r   r:   r   s      rN   r   J2Op._eval_rewrite_as_xyz  s9    DG}a$tAw-"22T$q']A5EEEr\   c                     US   n[        U5      S-  [        R                  [        U5      [	        U5      -  [	        U5      [        U5      -  -   -  -   $ r%  )r:   r   r{   r   r   )rb   r`   r   rq   s       rN   r&  J2Op._eval_rewrite_as_plusminus  sM    GAwzFFGAJx{*Xa[-CCDE 	Er\   r   N)r   r   r   r   r   rh   r.  r  r  rA  r   r   r   r   r   r   r   r|   r   r   rs   rw   r   r&  r   r   r\   rN   r;   r;   h  sf    F%%%%%%56
(FEr\   r;   c                       \ rS rSrSr\S 5       r\S 5       r\S 5       r	\S 5       r
\S 5       rS rS	 rS
 rS r\S 5       r\S 5       rS rS rS rS rSS.S jrS rS rS rSS.S jrS rS rS rSrg)r2   i  a  Wigner D operator in terms of Euler angles.

Defines the rotation operator in terms of the Euler angles defined by
the z-y-z convention for a passive transformation. That is the coordinate
axes are rotated first about the z-axis, giving the new x'-y'-z' axes. Then
this new coordinate system is rotated about the new y'-axis, giving new
x''-y''-z'' axes. Then this new coordinate system is rotated about the
z''-axis. Conventions follow those laid out in [1]_.

Parameters
==========

alpha : Number, Symbol
    First Euler Angle
beta : Number, Symbol
    Second Euler angle
gamma : Number, Symbol
    Third Euler angle

Examples
========

A simple example rotation operator:

    >>> from sympy import pi
    >>> from sympy.physics.quantum.spin import Rotation
    >>> Rotation(pi, 0, pi/2)
    R(pi,0,pi/2)

With symbolic Euler angles and calculating the inverse rotation operator:

    >>> from sympy import symbols
    >>> a, b, c = symbols('a b c')
    >>> Rotation(a, b, c)
    R(a,b,c)
    >>> Rotation(a, b, c).inverse()
    R(-c,-b,-a)

See Also
========

WignerD: Symbolic Wigner-D function
D: Wigner-D function
d: Wigner small-d function

References
==========

.. [1] Varshalovich, D A, Quantum Theory of Angular Momentum. 1988.
c                 l    [         R                  " U5      n[        U5      S:w  a  [        SU-  5      eU$ )N   z 3 Euler angles required, got: %r)r   
_eval_argsr   rH   )rW   r`   s     rN   r{  Rotation._eval_args  s3    %t9>?$FGGr\   c                 4    [        [        R                  5      $ rS   rT   rV   s     rN   rY   Rotation._eval_hilbert_space  r[   r\   c                      U R                   S   $ r^   rX   ra   s    rN   alphaRotation.alpha      zz!}r\   c                      U R                   S   $ r   r  ra   s    rN   betaRotation.beta  r  r\   c                      U R                   S   $ r   r  ra   s    rN   gammaRotation.gamma  r  r\   c                     g)NRr   ri   s      rN   _print_operator_nameRotation._print_operator_name  s    r\   c                 P    UR                   (       a  [        S5      $ [        S5      $ )Nu   ℛ zR )_use_unicoder   ri   s      rN   _print_operator_name_pretty$Rotation._print_operator_name_pretty   s"    :;;d##r\   c                     g)Nz\mathcal{R}r   ri   s      rN   _print_operator_name_latex#Rotation._print_operator_name_latex  s    r\   c                 ^    [        U R                  * U R                  * U R                  * 5      $ rS   )r2   r  r  r  ra   s    rN   _eval_inverseRotation._eval_inverse	  s#    diiZ$**==r\   c                     [        XX4XV5      $ )a  Wigner D-function.

Returns an instance of the WignerD class corresponding to the Wigner-D
function specified by the parameters.

Parameters
===========

j : Number
    Total angular momentum
m : Number
    Eigenvalue of angular momentum along axis after rotation
mp : Number
    Eigenvalue of angular momentum along rotated axis
alpha : Number, Symbol
    First Euler angle of rotation
beta : Number, Symbol
    Second Euler angle of rotation
gamma : Number, Symbol
    Third Euler angle of rotation

Examples
========

Return the Wigner-D matrix element for a defined rotation, both
numerical and symbolic:

    >>> from sympy.physics.quantum.spin import Rotation
    >>> from sympy import pi, symbols
    >>> alpha, beta, gamma = symbols('alpha beta gamma')
    >>> Rotation.D(1, 1, 0,pi, pi/2,-pi)
    WignerD(1, 1, 0, pi, pi/2, -pi)

See Also
========

WignerD: Symbolic Wigner-D function

r3   )rW   rK   r   r   r  r  r  s          rN   D
Rotation.D  s    R qR44r\   c                      [        XUSUS5      $ )a  Wigner small-d function.

Returns an instance of the WignerD class corresponding to the Wigner-D
function specified by the parameters with the alpha and gamma angles
given as 0.

Parameters
===========

j : Number
    Total angular momentum
m : Number
    Eigenvalue of angular momentum along axis after rotation
mp : Number
    Eigenvalue of angular momentum along rotated axis
beta : Number, Symbol
    Second Euler angle of rotation

Examples
========

Return the Wigner-D matrix element for a defined rotation, both
numerical and symbolic:

    >>> from sympy.physics.quantum.spin import Rotation
    >>> from sympy import pi, symbols
    >>> beta = symbols('beta')
    >>> Rotation.d(1, 1, 0, pi/2)
    WignerD(1, 1, 0, 0, pi/2, 0)

See Also
========

WignerD: Symbolic Wigner-D function

r   r  )rW   rK   r   r   r  s        rN   d
Rotation.d7  s    L qRD!,,r\   c                     U R                   R                  X2X@R                  U R                  U R                  5      nU[        X5      -  nU$ rS   )r   r  r  r  r  r$   r   s         rN   r|   Rotation.matrix_element_  sA    !!2zz499djj
 	.''r\   c           	      x   [        UR                  S[        R                  5      5      n[        UR                  S5      5      n[	        U5      u  pV[        XU5      n[        U5       HO  n[        U5       H=  n	U R                  X6U   X6U	   5      n
U(       a  U
R                  5       XxU	4'   M8  XX4'   M?     MQ     U$ )NrK   doit)	r   rz   r   r{   r+   r   rI   r|   r  )rb   r}   r~   rK   evaluaterL   r   r   r   r   r   s              rN   r   Rotation._represent_basef  s    GKKQVV,-7;;v./qkt"tA4[((!HaqB#%779Fa4L#%14L !  r\   c                 &    U R                   " S0 UD6$ r   r   r   s     rN   r   !Rotation._represent_default_basisu  r   r\   c                 (    U R                   " U40 UD6$ rS   r   r   s      rN   r   Rotation._represent_JzOpx  r   r\   T)dummyc          
         U R                   nU R                  nU R                  nUR                  nUR                  n	UR
                  (       ac  / n
[        U5      nUS   nU HC  n[        R                  XXXg5      nUR                  5       nU
R                  X" X5      -  5        ME     [        U
6 $ U(       a  [        S5      nO[        S5      n[        [        R                  XXXg5      U" X5      -  X* U45      $ NrF   r   )r  r  r  rK   r   	is_numberr+   r2   r  r  r   r   r   r   r   )rb   r   r   r  r~   rq   rr   grK   r   r   rL   szr   rr;  s                   rN   _apply_operator_uncoupled"Rotation._apply_operator_uncoupled{  s    JJIIJJEEEE;;AA;DaBJJqRA1FFH5<(  7N4[T]xzz!q4U1\ABA;OOr\   c                 2    U R                   " [        U40 UD6$ rS   )r  r4   r   s      rN   r   Rotation._apply_operator_JxKet      --eSDGDDr\   c                 2    U R                   " [        U40 UD6$ rS   )r  r6   r   s      rN   r   Rotation._apply_operator_JyKet  r  r\   c                 2    U R                   " [        U40 UD6$ rS   )r  r8   r   s      rN   r   Rotation._apply_operator_JzKet  r  r\   c          
      .   U R                   nU R                  nU R                  nUR                  nUR                  n	UR
                  n
UR                  nUR                  (       ae  / n[        U5      nUS   nU HE  n[        R                  XXXg5      nUR                  5       nUR                  UU" XX5      -  5        MG     [        U6 $ U(       a  [        S5      nO[        S5      n[!        [        R                  XXXg5      U" XX5      -  X* U45      $ r  )r  r  r  rK   r   r   r   r  r+   r2   r  r  r   r   r   r   r   )rb   r   r   r  r~   rq   rr   r  rK   r   r   r   r   rL   r  r   r  r;  s                     rN   _apply_operator_coupled Rotation._apply_operator_coupled  s    JJIIJJEEEEVV<<;;AA;DaBJJqRA1FFH5556  7N4[T]xzz!q4Ur6% %')2qk3 3r\   c                 2    U R                   " [        U40 UD6$ rS   )r  r<   r   s      rN   r   %Rotation._apply_operator_JxKetCoupled      ++L#IIIr\   c                 2    U R                   " [        U40 UD6$ rS   )r  r>   r   s      rN   r   %Rotation._apply_operator_JyKetCoupled  r  r\   c                 2    U R                   " [        U40 UD6$ rS   )r  r@   r   s      rN   r   %Rotation._apply_operator_JzKetCoupled  r  r\   r   N)r   r   r   r   r   r   r{  rY   r   r  r  r  r  r  r  r  r  r  r|   r   r   r   r  r   r   r   r  r   r   r   r   r   r\   rN   r2   r2     s    1f   ( (      $> (5 (5T %- %-N56 >B P,EEE <@ 32JJJr\   r2   c                       \ rS rSrSrSrS r\S 5       r\S 5       r	\S 5       r
\S 5       r\S	 5       r\S
 5       rS rS rS rS rSrg)r3   i  a  Wigner-D function

The Wigner D-function gives the matrix elements of the rotation
operator in the jm-representation. For the Euler angles `\alpha`,
`\beta`, `\gamma`, the D-function is defined such that:

.. math ::
    <j,m| \mathcal{R}(\alpha, \beta, \gamma ) |j',m'> = \delta_{jj'} D(j, m, m', \alpha, \beta, \gamma)

Where the rotation operator is as defined by the Rotation class [1]_.

The Wigner D-function defined in this way gives:

.. math ::
    D(j, m, m', \alpha, \beta, \gamma) = e^{-i m \alpha} d(j, m, m', \beta) e^{-i m' \gamma}

Where d is the Wigner small-d function, which is given by Rotation.d.

The Wigner small-d function gives the component of the Wigner
D-function that is determined by the second Euler angle. That is the
Wigner D-function is:

.. math ::
    D(j, m, m', \alpha, \beta, \gamma) = e^{-i m \alpha} d(j, m, m', \beta) e^{-i m' \gamma}

Where d is the small-d function. The Wigner D-function is given by
Rotation.D.

Note that to evaluate the D-function, the j, m and mp parameters must
be integer or half integer numbers.

Parameters
==========

j : Number
    Total angular momentum
m : Number
    Eigenvalue of angular momentum along axis after rotation
mp : Number
    Eigenvalue of angular momentum along rotated axis
alpha : Number, Symbol
    First Euler angle of rotation
beta : Number, Symbol
    Second Euler angle of rotation
gamma : Number, Symbol
    Third Euler angle of rotation

Examples
========

Evaluate the Wigner-D matrix elements of a simple rotation:

    >>> from sympy.physics.quantum.spin import Rotation
    >>> from sympy import pi
    >>> rot = Rotation.D(1, 1, 0, pi, pi/2, 0)
    >>> rot
    WignerD(1, 1, 0, pi, pi/2, 0)
    >>> rot.doit()
    sqrt(2)/2

Evaluate the Wigner-d matrix elements of a simple rotation

    >>> rot = Rotation.d(1, 1, 0, pi/2)
    >>> rot
    WignerD(1, 1, 0, 0, pi/2, 0)
    >>> rot.doit()
    -sqrt(2)/2

See Also
========

Rotation: Rotation operator

References
==========

.. [1] Varshalovich, D A, Quantum Theory of Angular Momentum. 1988.
Tc                     [        U5      S:X  d  [        SU-  5      e[        U5      nUR                  SS5      nU(       a%  [        R
                  " U /UQ76 R                  5       $ [        R
                  " U /UQ76 $ )N   z6 parameters expected, got %sr  F)r   rH   r   rz   r   __new___eval_wignerd)rW   r`   hintsr  s       rN   r  WignerD.__new__  sk    4yA~<tCDDt}99Z/<<+d+99;;||C'$''r\   c                      U R                   S   $ r^   r_   ra   s    rN   rK   	WignerD.j  re   r\   c                      U R                   S   $ r   r_   ra   s    rN   r   	WignerD.m  re   r\   c                      U R                   S   $ r   r_   ra   s    rN   r   
WignerD.mp  re   r\   c                      U R                   S   $ Nrz  r_   ra   s    rN   r  WignerD.alpha#  re   r\   c                      U R                   S   $ )N   r_   ra   s    rN   r  WignerD.beta'  re   r\   c                      U R                   S   $ )N   r_   ra   s    rN   r  WignerD.gamma+  re   r\   c                    U R                   S:X  a  U R                  S:X  aw  SUR                  U R                  5      < SUR                  U R                  5      < SUR                  U R
                  5      < SUR                  U R                  5      < S3	$ SUR                  U R                  5      < SUR                  U R                  5      < SUR                  U R
                  5      < SUR                  U R                   5      < SUR                  U R                  5      < SUR                  U R                  5      < S3$ )Nr   zd^{z}_{,z}\left(z\right)zD^{)r  r  _printrK   r   r   r  ri   s      rN   _latexWignerD._latex/  s    ::?tzzQ NN466*GNN- !(!8NN499-	0 0 FF$^^DFF3W^^DGG5Ltzz*GNN499,Ew~~VZV`V`Ga	d 	dr\   c                 d   UR                  U R                  5      nUR                  U R                  5      n[        UR	                  S5      6 n[        UR	                  UR                  U R
                  5      5      6 n[        UR                  5       UR                  5       5      n[        UR                  S5      6 n[        UR                  S5      6 nXSR                  5       :  a*  [        UR	                  SXSR                  5       -
  -  5      6 nXTR                  5       :  a*  [        UR	                  SXTR                  5       -
  -  5      6 nU R                  S:X  a=  U R                  S:X  a-  UR                  U R                  5      n[        SSU-  -   5      nOUR                  U R                  5      n[        UR	                  S5      6 n[        UR	                  UR                  U R                  5      5      6 n[        UR	                  S5      6 n[        UR	                  UR                  U R                  5      5      6 n[        SSU-  -   5      n[        UR                  5       6 n[        UR                  U5      6 n[        UR                  U5      6 n[        UR	                  U5      6 nU$ )Nr   r   r  r  )r  rK   r   r   rightr   maxwidthleftr  r  r  r   parensabovebelow)rb   rj   r`   topbotpadr   s          rN   _prettyWignerD._pretty<  s   nnTVV$nnTVV$#))C.)#))GNN477$;<=#))+syy{+#((3-(#((3-(ciiS99;->(?@ACciiS99;->(?@AC::?tzzQ>>$)),D3S=)A>>$**-Dtzz#/Dtzz'..*CDEDtzz#/Dtzz'..*DEFD3S=)A4;;=)%%&r\   c                 6    SUS'   [        U R                  0 UD6$ )NTr  )r3   r`   )rb   r  s     rN   r  WignerD.doit\  s      j		+U++r\   c           
         U R                   nU R                  nU R                  nU R                  nU R                  nU R
                  nUS:X  a  US:X  a  US:X  a  [        X#5      $ UR                  (       d  [        SU-  5      eSnU[        S-  :X  a  [        SU-  S-   5       HV  nXU-   :  d  XU-
  :  d  XU-
  :  a  M  U[        R                  U-  [        X-   U5      -  [        X-
  X-   U-
  5      -  -  nMX     U[        R                  X#-
  -  SU-  -  [        [        X-   5      [        X-
  5      -  [        X-   5      [        X-
  5      -  -  5      -  -  nO[!        U5      u  pU
 H  nU["        R%                  XU[        S-  5      R'                  5       [)        U* U-  5      [*        [-        U* U-  5      -  -   -  ["        R%                  XU* [        S-  5      R'                  5       -  -  nM     U[*        SU-  U-
  U-
  -  -  SSU-  -  -  n[/        U5      nU[1        [*        * U-  U-  5      [1        [*        * U-  U-  5      -  -  nU$ )Nr   z1j parameter must be numerical to evaluate, got %srE   rF   )rK   r   r   r  r  r  r$   r  rH   r   rI   r   NegativeOner   r   r   r+   r2   r  r  r   r	   r   r   r   )rb   rK   r   r   r  r  r  r  krL   r   mpps               rN   r  WignerD._eval_wignerd`  s?   FFFFWW

yy

A:$!)
!!(({{CaGI I2a4< 1Q37^2v:Uaq&jamma'(;;HQVQUUWZ<XXX $ !--16*QT1$y7Gae$8%(1!&(9)AF:K(K8M 3N N NA #1+KDXZZc2a40557cT$Y!CQTPTUYPYNJZ9Z[JJqsBqD16689 9  !acAgl##R1Q3K/AA	S!Ae_S!Bu---r\   r   N)r   r   r   r   r   is_commutativer  r   rK   r   r   r  r  r  r  r  r  r  r   r   r\   rN   r3   r3     s    M^ N(            d@,)r\   r3   Jc                       \ rS rSrSrSrS r\S 5       r\S 5       r	\
S 5       rS rS	 rS
 rS rS rS rS rS rS rSrg)	SpinStatei  z'Base class for angular momentum states.r  c                 (   [        U5      n[        U5      nUR                  (       a7  SU-  [        SU-  5      :w  a  [        SU-  5      eUS:  a  [        SU-  5      eUR                  (       a#  SU-  [        SU-  5      :w  a  [        SU-  5      eUR                  (       aY  UR                  (       aH  [	        U5      U:  a  [        SU< SU< 35      e[        X-
  5      X-
  :w  a  [        SU< SU< 35      e[
        R                  " XU5      $ )	NrE   z*j must be integer or half-integer, got: %sr   zj must be >= 0, got: %sz*m must be integer or half-integer, got: %sz1Allowed values for m are -j <= m <= j, got j, m: z, z8Both j and m must be integer or half-integer, got j, m: )r   r  rJ   rH   absr#   r  )rW   rK   r   s      rN   r  SpinState.__new__  s    AJAJ;;sc!A#h @1DF F1u !:Q!>??;;sc!A#h @1DF F;;1;;1vz ^_ab!cdd15zQU" efhi!jkk}}SQ''r\   c                      U R                   S   $ r^   r  ra   s    rN   rK   SpinState.j  r  r\   c                      U R                   S   $ r   r  ra   s    rN   r   SpinState.m  r  r\   c                 *    [        SUS   -  S-   5      $ )NrE   r   rF   )r&   rV   s     rN   rY   SpinState._eval_hilbert_space  s    AeAhJN++r\   c           	      6   U R                   nU R                  n[        UR                  SS5      5      n[        UR                  SS5      5      n[        UR                  SS5      5      n[	        U5      u  px[        US5      n	[        U5       H  u  pUR                  (       a@  [        R                  U R                   XR                  XEU5      R                  5       XS4'   MV  [        R                  U R                   UU R                  XEU5      XS4'   M     U	$ )Nr  r   r  r  rF   )rK   r   r   rz   r+   r   	enumerater  r2   r  r  )rb   r~   rK   r   r  r  r  rL   r   r   r   mvals               rN   r   SpinState._represent_base  s    FFFFGQ/0w{{61-.GQ/0qktQ 'GA{{'zzFFD&&%u >>Bdf !t  (zz$&&$*.&&%u F!t ( r\   c                     [        U [        5      (       a  U R                  " [        [        40 UD6$ U R                  " [        [
        40 UD6$ rS   )r   r!   _rewrite_basisr.   r5   r4   rb   r`   r~   s      rN   _eval_rewrite_as_JxSpinState._eval_rewrite_as_Jx  ?    dC  &&r5<G<<""2u888r\   c                     [        U [        5      (       a  U R                  " [        [        40 UD6$ U R                  " [        [
        40 UD6$ rS   )r   r!   r  r/   r7   r6   r  s      rN   _eval_rewrite_as_JySpinState._eval_rewrite_as_Jy  r
  r\   c                     [        U [        5      (       a  U R                  " [        [        40 UD6$ U R                  " [        [
        40 UD6$ rS   )r   r!   r  r0   r9   r8   r  s      rN   _eval_rewrite_as_JzSpinState._eval_rewrite_as_Jz  r
  r\   c                    SSK Jn  U R                  nU R                  SS  nUR                  (       a  [        U [        5      (       a*  U[        U5      :X  a  US-  nOSU-  S-
  SU-  S-   -  S-  nOSnU" U 4SU0UD6n[        [        SU-  S-   5       V	s/ s H  oXy-      U" XUU	-
  /UQ76 -  PM     sn	6 n
[        U [        5      (       a  UR                  S5      SL a  [        U
5      $ U
$ Sn	[        S	5      nU R                  US5      U :w  a  U	S-  n	[        S
U	-  5      n [        U [        5      (       a  SUS4nOSU4n[        U [        5      (       a%  U" U R                  " U6 US9S   R                  SS nO1U" U R                  " U6 US9S   R                  S   R                  SS nUS:X  a  U $ U" X[/UQ76 n[         R"                  " X[U R$                  /UQ76 n['        X-  X* U45      $ s  sn	f )Nr   )	representrE   rF   r  r}   coupledFmizmi%d)r   r   )r}   rz  r  )r   r   r   )sympy.physics.quantum.representr  rK   r`   r  r   CoupledSpinStaterJ   r   rI   rz   rC   r   subsr"   r   r2   r  r   r   )rb   r}   evectr~   r  rK   r`   startvectrM   r   r  	test_argsanglesr   lts                   rN   r  SpinState._rewrite_basis  s   =FFyy};;$ 011A;qDEqS1WqsQw/1ET::':DBG!a.Q.Quy/%q5"84"88.QSF$ 011gkk)6LPU6U''MAB))B"d*QVaZ($ 011FO	G	$$$"NNI.e==>@@DQqJ #4>>$ ',../115a99=aC"a+d+ZZtvv7728b"a[119 Rs   G3c                 f   [        U R                  UR                  5      nUR                  5       U R                  La/  X0R	                  S 5      UR                  UR
                  -
     -  nU$ U[        U R                  UR                  5      [        U R
                  UR
                  5      -  -  nU$ rS   )r$   rK   
dual_classr   _represent_JxOpr   rb   brar  r   s       rN   _eval_innerproduct_JxBra"SpinState._eval_innerproduct_JxBra      .>>4>>1**40??F  n-dffcee<= =Fr\   c                 f   [        U R                  UR                  5      nUR                  5       U R                  La/  X0R	                  S 5      UR                  UR
                  -
     -  nU$ U[        U R                  UR                  5      [        U R
                  UR
                  5      -  -  nU$ rS   )r$   rK   r   r   _represent_JyOpr   r"  s       rN   _eval_innerproduct_JyBra"SpinState._eval_innerproduct_JyBra  r&  r\   c                 f   [        U R                  UR                  5      nUR                  5       U R                  La/  X0R	                  S 5      UR                  UR
                  -
     -  nU$ U[        U R                  UR                  5      [        U R
                  UR
                  5      -  -  nU$ rS   )r$   rK   r   r   r   r   r"  s       rN   _eval_innerproduct_JzBra"SpinState._eval_innerproduct_JzBra  r&  r\   c                 &    X-  R                  5       $ rS   )r  )rb   r#  r  s      rN   r   SpinState._eval_trace&  s       r\   r   N)r   r   r   r   r   _label_separatorr  r   rK   r   r   rY   r   r  r  r  r  r$  r)  r,  r   r   r   r\   rN   r  r    sz    1((     , ,$9
9
9
*2X!r\   r  c                   P    \ rS rSrSr\S 5       r\S 5       rS rS r	S r
S rS	rg
)r4   i6  zoEigenket of Jx.

See JzKet for the usage of spin eigenstates.

See Also
========

JzKet: Usage of spin states

c                     [         $ rS   r5   ra   s    rN   r   JxKet.dual_classB      r\   c                     [         $ rS   r<   ra   s    rN   coupled_classJxKet.coupled_classF      r\   c                 &    U R                   " S0 UD6$ r   )r!  r   s     rN   r   JxKet._represent_default_basisJ  r   r\   c                 &    U R                   " S0 UD6$ Nr   r   r   s      rN   r!  JxKet._represent_JxOpM      ##.g..r\   c           	      L    U R                   " SS[        [        SS5      -  0UD6$ Nr  rz  rE   r   r   r   r   r   s      rN   r(  JxKet._represent_JyOpP  s&    ##G"Xa^*;GwGGr\   c                 8    U R                   " SS[        S-  0UD6$ Nr  rE   r   r   r   r   s      rN   r   JxKet._represent_JzOpS  s    ##9A999r\   r   Nr   r   r   r   r   r   r   r8  r   r!  r(  r   r   r   r\   rN   r4   r4   6  sD    	    5/H:r\   r4   c                   8    \ rS rSrSr\S 5       r\S 5       rSrg)r5   iW  zoEigenbra of Jx.

See JzKet for the usage of spin eigenstates.

See Also
========

JzKet: Usage of spin states

c                     [         $ rS   r4   ra   s    rN   r   JxBra.dual_classc  r5  r\   c                     [         $ rS   r=   ra   s    rN   r8  JxBra.coupled_classg  r:  r\   r   N	r   r   r   r   r   r   r   r8  r   r   r\   rN   r5   r5   W  /    	    r\   r5   c                   P    \ rS rSrSr\S 5       r\S 5       rS rS r	S r
S rS	rg
)r6   il  zoEigenket of Jy.

See JzKet for the usage of spin eigenstates.

See Also
========

JzKet: Usage of spin states

c                     [         $ rS   r7   ra   s    rN   r   JyKet.dual_classx  r5  r\   c                     [         $ rS   r>   ra   s    rN   r8  JyKet.coupled_class|  r:  r\   c                 &    U R                   " S0 UD6$ r   )r(  r   s     rN   r   JyKet._represent_default_basis  r   r\   c                 8    U R                   " SS[        S-  0UD6$ Nr  rE   r   rG  r   s      rN   r!  JyKet._represent_JxOp  s    ##:"Q$:'::r\   c                 &    U R                   " S0 UD6$ r>  r   r   s      rN   r(  JyKet._represent_JyOp  r@  r\   c                 n    U R                   " S[        [        SS5      -  [        * S-  [        S-  S.UD6$ Nrz  rE   )r  r  r  r   rC  r   s      rN   r   JyKet._represent_JzOp  s6    ##_"Xa^*;2#a%rRSt_W^__r\   r   NrI  r   r\   rN   r6   r6   l  sD    	    5;/`r\   r6   c                   8    \ rS rSrSr\S 5       r\S 5       rSrg)r7   i  zoEigenbra of Jy.

See JzKet for the usage of spin eigenstates.

See Also
========

JzKet: Usage of spin states

c                     [         $ rS   r6   ra   s    rN   r   JyBra.dual_class  r5  r\   c                     [         $ rS   r?   ra   s    rN   r8  JyBra.coupled_class  r:  r\   r   NrQ  r   r\   rN   r7   r7     rR  r\   r7   c                   P    \ rS rSrSr\S 5       r\S 5       rS rS r	S r
S rS	rg
)r8   i  a
  Eigenket of Jz.

Spin state which is an eigenstate of the Jz operator. Uncoupled states,
that is states representing the interaction of multiple separate spin
states, are defined as a tensor product of states.

Parameters
==========

j : Number, Symbol
    Total spin angular momentum
m : Number, Symbol
    Eigenvalue of the Jz spin operator

Examples
========

*Normal States:*

Defining simple spin states, both numerical and symbolic:

    >>> from sympy.physics.quantum.spin import JzKet, JxKet
    >>> from sympy import symbols
    >>> JzKet(1, 0)
    |1,0>
    >>> j, m = symbols('j m')
    >>> JzKet(j, m)
    |j,m>

Rewriting the JzKet in terms of eigenkets of the Jx operator:
Note: that the resulting eigenstates are JxKet's

    >>> JzKet(1,1).rewrite("Jx")
    |1,-1>/2 - sqrt(2)*|1,0>/2 + |1,1>/2

Get the vector representation of a state in terms of the basis elements
of the Jx operator:

    >>> from sympy.physics.quantum.represent import represent
    >>> from sympy.physics.quantum.spin import Jx, Jz
    >>> represent(JzKet(1,-1), basis=Jx)
    Matrix([
    [      1/2],
    [sqrt(2)/2],
    [      1/2]])

Apply innerproducts between states:

    >>> from sympy.physics.quantum.innerproduct import InnerProduct
    >>> from sympy.physics.quantum.spin import JxBra
    >>> i = InnerProduct(JxBra(1,1), JzKet(1,1))
    >>> i
    <1,1|1,1>
    >>> i.doit()
    1/2

*Uncoupled States:*

Define an uncoupled state as a TensorProduct between two Jz eigenkets:

    >>> from sympy.physics.quantum.tensorproduct import TensorProduct
    >>> j1,m1,j2,m2 = symbols('j1 m1 j2 m2')
    >>> TensorProduct(JzKet(1,0), JzKet(1,1))
    |1,0>x|1,1>
    >>> TensorProduct(JzKet(j1,m1), JzKet(j2,m2))
    |j1,m1>x|j2,m2>

A TensorProduct can be rewritten, in which case the eigenstates that make
up the tensor product is rewritten to the new basis:

    >>> TensorProduct(JzKet(1,1),JxKet(1,1)).rewrite('Jz')
    |1,1>x|1,-1>/2 + sqrt(2)*|1,1>x|1,0>/2 + |1,1>x|1,1>/2

The represent method for TensorProduct's gives the vector representation of
the state. Note that the state in the product basis is the equivalent of the
tensor product of the vector representation of the component eigenstates:

    >>> represent(TensorProduct(JzKet(1,0),JzKet(1,1)))
    Matrix([
    [0],
    [0],
    [0],
    [1],
    [0],
    [0],
    [0],
    [0],
    [0]])
    >>> represent(TensorProduct(JzKet(1,1),JxKet(1,1)), basis=Jz)
    Matrix([
    [      1/2],
    [sqrt(2)/2],
    [      1/2],
    [        0],
    [        0],
    [        0],
    [        0],
    [        0],
    [        0]])

See Also
========

JzKetCoupled: Coupled eigenstates
sympy.physics.quantum.tensorproduct.TensorProduct: Used to specify uncoupled states
uncouple: Uncouples states given coupling parameters
couple: Couples uncoupled states

c                     [         $ rS   r9   ra   s    rN   r   JzKet.dual_class  r5  r\   c                     [         $ rS   r@   ra   s    rN   r8  JzKet.coupled_class  r:  r\   c                 &    U R                   " S0 UD6$ r   r   r   s     rN   r   JzKet._represent_default_basis  r   r\   c           	      L    U R                   " SS[        [        SS5      -  0UD6$ Nr  rz  rE   r   rC  r   s      rN   r!  JzKet._represent_JxOp  s&    ##FHQN):FgFFr\   c                 l    U R                   " S[        [        SS5      -  [        S-  [        S-  S.UD6$ rb  rC  r   s      rN   r(  JzKet._represent_JyOp  s4    ##^"Xa^*;"Q$bQRd^V]^^r\   c                 &    U R                   " S0 UD6$ r>  r   r   s      rN   r   JzKet._represent_JzOp"  r@  r\   r   NrI  r   r\   rN   r8   r8     sG    l\    5G_/r\   r8   c                   8    \ rS rSrSr\S 5       r\S 5       rSrg)r9   i&  zsEigenbra of Jz.

See the JzKet for the usage of spin eigenstates.

See Also
========

JzKet: Usage of spin states

c                     [         $ rS   r8   ra   s    rN   r   JzBra.dual_class2  r5  r\   c                     [         $ rS   rA   ra   s    rN   r8  JzBra.coupled_class6  r:  r\   r   NrQ  r   r\   rN   r9   r9   &  rR  r\   r9   c                    [        U5       Vs/ s H  o"S-   /PM
     nn/ n/ nU  HV  u  pgnUR                  U5        UR                  X6S-
     X7S-
     45        [        X6S-
     X7S-
     -   5      n	XU	S   S-
  '   MX     XT4$ s  snf )NrF   r   )rI   r   sorted)
	jcouplinglengthr   n_list
coupled_jn	coupled_nn1n2j_newn_sorts
             rN   _build_coupledr  ?  s     %f/1AwF/JI"% 6q&>6q&>:<AvQ78 &vay1}	 #
    0s   Bc                       \ rS rSrSrS rS rS rS r\	S 5       r
\	S 5       r\	S	 5       r\	S
 5       r\S 5       rS rS rS rS rSrg)r  iK  z/Base class for coupled angular momentum states.c                 j  ^ [        X5        [        U5      S:X  as  / n[        S[        T5      5       H:  nUR                  SU[	        [        U5       Vs/ s H  nTU   PM
     sn6 45        M<     UR                  S[        T5      U45        O/[        U5      S:X  a  US   nO[        S[        U5      S-   -  5      e[        T[        [        [        45      (       d"  [        STR                  R                  -  5      e[        U[        [        [        45      (       d"  [        SUR                  R                  -  5      e[        S U 5       5      (       d  [        S	5      e[        T5      S-
  [        U5      :X  d%  [        S
[        T5      S-
  [        U5      4-  5      e[        S U 5       5      (       d  [        S5      e[        U5      n[        U5      n[        T Vs/ s H  n[        U5      PM     sn6 m[        U VV	Vs/ s H.  u  pn[        [        U5      [        U	5      [        U5      5      PM0     snn	n6 n[        S T 5       5      (       a  [        ST-  5      e[        S U 5       5      (       a  [        S5      e[        U4S jU 5       5      (       a  [        S5      e[        S U 5       5      (       a  [        S5      e[!        U[        T5      5      u  p[        T5      n[#        U
5       H  u  nu  pU[%        U5      S-
     nU[%        U	5      S-
     nX   n[        U5      R&                  (       a  [        U5      R&                  (       an  [        U5      R&                  (       aT  X-   U:  a  [        SUS-   XU4-  5      e[)        X-
  5      U:  a  [        SUS-   XU4-  5      e[+        X-   5      (       a   X[%        X-   5      S-
  '   M     [        U5      S:  a  US   S   U:w  a  [        S5      e[,        R.                  " XUTU5      $ s  snf s  snf s  snn	nf )Nr   rE   rF   z5CoupledSpinState only takes 3 or 4 arguments, got: %srz  z'jn must be Tuple, list or tuple, got %sz.jcoupling must be Tuple, list or tuple, got %sc              3   X   #    U  H   n[        U[        [        [        45      v   M"     g 7frS   )r   listtupler   .0terms     rN   	<genexpr>+CoupledSpinState.__new__.<locals>.<genexpr>d  s!     Pid:dT5%$899is   (*z6All elements of jcoupling must be list, tuple or Tuplez(jcoupling must have length of %d, got %dc              3   >   #    U  H  n[        U5      S :H  v   M     g7f)rz  Nr   )r  r  s     rN   r  r  j  s     2	13q6Q;	   z,All elements of jcoupling must have length 3c              3   n   #    U  H+  oR                   (       d  M  S U-  [        S U-  5      :g  v   M-     g7frE   Nr  rJ   )r  jis     rN   r  r  s  s(     >2R qts1R4y 2s   55z;All elements of jn must be integer or half-integer, got: %sc              3   l   #    U  H*  u  po1[        U5      :g  =(       d    U[        U5      :g  v   M,     g 7frS   )rJ   )r  r  r  rv   s       rN   r  r  u  s*     K+21SW}-c"g-s   24z%Indices in jcoupling must be integersc              3      >#    U  HB  u  po1S :  =(       d/    US :  =(       d#    U[        T5      :  =(       d    U[        T5      :  v   MD     g7f)rF   Nr  )r  r  r  rv   r   s       rN   r  r  w  s?     ]S\KRQAv?a?2B<?2B<?S\s   A
Az?Indices must be between 1 and the number of coupled spin spacesc              3   v   #    U  H/  u    pUR                   (       d  M  S U-  [        S U-  5      :g  v   M1     g7fr  r  )r  rv   r  s      rN   r  r  y  s.     M9Za qts1R4y 9s   99zGAll coupled j values in coupling scheme must be integer or half-integerzQAll couplings must have j1+j2 >= j3, in coupling number %d got j1,j2,j3: %d,%d,%dzSAll couplings must have |j1+j2| <= j3, in coupling number %d got j1,j2,j3: %d,%d,%dr  z>Last j value coupled together must be the final j of the state)r  r   rI   r   r   	TypeErrorr   r  r  r   r   r   allrH   r   anyr  r  minr  r  r   r#   r  )rW   rK   r   r   r  r   rM   r  r  r  r  r  jvalsj1j2j3s      `            rN   r  CoupledSpinState.__new__N  s   !y>QI1c"g&  1aeAh.Ghr!uh.G)H"IK 'q#b'1o/^q !!ISWZ[dWehiWijll"tUE233ELL112 3 3)dE5%9::L%//889 : :PiPPPHJ J2w{c)n,G!"gk3y>:; < <2	222KLLAJAJB/BbgbkB/1?HJ?H| #7$gbk+?HJ L	 >2>>>Z]__``KKKKDEE]S\]]]^__M9MMMfgg .y#b' B	R$Y/KAxs2w{#Bs2w{#BBr{$$)>)>72;CXCX7R<$ &GJKa%QSY[I\&] ^ ^rw<"$$ &GJKa%QSY[I\&] ^ ^bg&&&(#bg,"# 0 y>A)B-"2a"7]^^}}SQI66q /H2 0Js   P$%P)	5P.c                    UR                  U R                  5      UR                  U R                  5      /n[        U R                  SS9 H)  u  pEUR                  SXAR                  U5      4-  5        M+     [        U R                  S S U R                  S S 5       HQ  u  nu  pxUR                  SSR                  S [        Xx-   5       5       5      < SUR                  U5      < 35        MS     SR                  U5      $ )	NrF   r  zj%d=%sr  zj(r  c              3   8   #    U  H  n[        U5      v   M     g 7frS   rn   r  rM   s     rN   r  0CoupledSpinState._print_label.<locals>.<genexpr>       9AQ   z)=)r  rK   r   r  r   r   zipr  r  joinr  )	rb   rj   r`   rX   rM   r  r   r  r  s	            rN   _print_labelCoupledSpinState._print_label  s    ')?@twwa0EALL>>"%%   1   4dnnSb6IJLBLL9997>>";M  K xxr\   c                    U R                   U R                  /n[        U R                  SS9 HZ  u  pESU-  n[	        U5      n[        US-   5      n[        UR                  UR                  U5      5      6 nUR                  U5        M\     [        U R                  S S U R                  S S 5       Hs  u  nu  pSR                  S [        X-   5       5       5      n[        SU-   S-   5      n[        UR                  UR                  U5      5      6 nUR                  U5        Mu     U R                  " X0R                  U/UQ76 $ )	NrF   r  j%d=r  r  c              3   D   #    U  H  n[        S U-  5      S   v   M     g7f)r  r  Nr   r  s     rN   r  7CoupledSpinState._print_label_pretty.<locals>.<genexpr>  s     O!uqy1"5s    rK   )rK   r   r  r   r   r   r  r  r   r  r  r  r  r  _print_sequence_prettyr0  )rb   rj   r`   rX   rM   r  symbitemr   r  r  r   s               rN   _print_label_pretty$CoupledSpinState._print_label_pretty  s     twwa0EA19D &DdSj)Dtzz'..*<=>DLL 1   4dnnSb6IJLBOvbgOOAcAgm,Dtzz'..*<=>DLL	 K
 **(('
48
 	
r\   c           
      0   UR                   " U R                  /UQ76 UR                   " U R                  /UQ76 /n[        U R                  SS9 H+  u  pEUR                  SXAR                   " U/UQ76 4-  5        M-     [        U R                  S S U R                  S S 5       HU  u  nu  pxSR                  S [        Xx-   5       5       5      n	UR                  SU	< SUR                   " U/UQ76 < 35        MW     U R                  R                  U5      $ )	NrF   r  z	j_{%d}=%sr  r  c              3   8   #    U  H  n[        U5      v   M     g 7frS   r  r  s     rN   r  6CoupledSpinState._print_label_latex.<locals>.<genexpr>  r  r  zj_{z}=)r  rK   r   r  r   r   r  r  r  r  r  r0  )
rb   rj   r`   rX   rM   r  r   r  r  r   s
             rN   _print_label_latex#CoupledSpinState._print_label_latex  s    NN466)D)NN466)D)
 twwa0EALL>>"+Dt+D'EEG 1 4dnnSb6IJLB999ALL7>>"+Dt+DEG K $$))%00r\   c                      U R                   S   $ r   r  ra   s    rN   r   CoupledSpinState.jn  r  r\   c                      U R                   S   $ r  r  ra   s    rN   r   CoupledSpinState.coupling  r  r\   c                 f    [        U R                  S   [        U R                  S   5      5      S   $ )Nrz  rE   rF   r  rX   r   ra   s    rN   r  CoupledSpinState.coupled_jn  )    djjmSA-?@CCr\   c                 f    [        U R                  S   [        U R                  S   5      5      S   $ )Nrz  rE   r   r  ra   s    rN   r  CoupledSpinState.coupled_n  r  r\   c                     [        US   6 nUR                  (       a<  [        [        [	        SU-  S-   5      SS5       Vs/ s H  n[        U5      PM     sn6 $ [        SU-  S-   5      $ s  snf )NrE   rF   r   )r   r  r'   rI   rJ   r&   )rW   rX   rK   r  s       rN   rY   $CoupledSpinState._eval_hilbert_space  sj    qN;;(U3qQRsUVw<YZ\^E_*aE_LOE_*abb  !a(( +bs    A*c                 T   U R                  5       nU R                  R                  (       d  [        S5      eU R                  R
                  R                  (       d  [        S5      e[        U R                  R
                  S5      nU R                  [        U R                  5      :X  a  U R                  S-  nO(SU R                  -  S-
  SSU R                  -  -   -  S-  nU" U R                  U R                  5      R                  " S0 UD6X4USU R                  -  -   S-   2S4'   U$ )Nz1State must not have symbolic j value to representz2State must not have symbolic j values to representrF   rE   r  r   r   )
uncoupled_classrK   r  rH   hilbert_space	dimensionr   rJ   r   r   )rb   r~   r  r   r  s        rN   _represent_coupled_base(CoupledSpinState._represent_coupled_base  s   $$&vvCE E!!++55DF Ft))33Q766S[ FFAIEtvvX\A$&&L1!3E05FFDFF1+O1, 17.517UQtvvX%))1,-r\   c                     [        U [        5      (       a  U R                  " [        [        40 UD6$ U R                  " [        [
        40 UD6$ rS   )r   r!   r  r.   r=   r<   r  s      rN   r  $CoupledSpinState._eval_rewrite_as_Jx  ?    dC  &&r<C7CC""2|?w??r\   c                     [        U [        5      (       a  U R                  " [        [        40 UD6$ U R                  " [        [
        40 UD6$ rS   )r   r!   r  r/   r?   r>   r  s      rN   r  $CoupledSpinState._eval_rewrite_as_Jy  r  r\   c                     [        U [        5      (       a  U R                  " [        [        40 UD6$ U R                  " [        [
        40 UD6$ rS   )r   r!   r  r0   rA   r@   r  s      rN   r  $CoupledSpinState._eval_rewrite_as_Jz  r  r\   r   N)r   r   r   r   r   r  r  r  r  r   r   r   r  r  r   rY   r  r  r  r  r   r   r\   rN   r  r  K  s    9@7D

"
1     D D D D 
) 
)"@
@
@r\   r  c                   P    \ rS rSrSr\S 5       r\S 5       rS rS r	S r
S rS	rg
)r<   i  zCoupled eigenket of Jx.

See JzKetCoupled for the usage of coupled spin eigenstates.

See Also
========

JzKetCoupled: Usage of coupled spin states

c                     [         $ rS   rO  ra   s    rN   r   JxKetCoupled.dual_class  r:  r\   c                     [         $ rS   rL  ra   s    rN   r  JxKetCoupled.uncoupled_class  r5  r\   c                 &    U R                   " S0 UD6$ r   r   r   s     rN   r   %JxKetCoupled._represent_default_basis  r   r\   c                 &    U R                   " S0 UD6$ r>  r  r   s      rN   r!  JxKetCoupled._represent_JxOp      ++6g66r\   c           	      L    U R                   " SS[        [        SS5      -  0UD6$ rB  r  r   r   r   s      rN   r(  JxKetCoupled._represent_JyOp  s&    ++O"Xa^2COwOOr\   c                 8    U R                   " SS[        S-  0UD6$ rF  r  r   r   s      rN   r   JxKetCoupled._represent_JzOp  s    ++AAAAAr\   r   Nr   r   r   r   r   r   r   r  r   r!  r(  r   r   r   r\   rN   r<   r<     sE    	    57PBr\   r<   c                   8    \ rS rSrSr\S 5       r\S 5       rSrg)r=   i  zCoupled eigenbra of Jx.

See JzKetCoupled for the usage of coupled spin eigenstates.

See Also
========

JzKetCoupled: Usage of coupled spin states

c                     [         $ rS   r7  ra   s    rN   r   JxBraCoupled.dual_class$  r:  r\   c                     [         $ rS   r3  ra   s    rN   r  JxBraCoupled.uncoupled_class(  r5  r\   r   N	r   r   r   r   r   r   r   r  r   r   r\   rN   r=   r=     /    	    r\   r=   c                   P    \ rS rSrSr\S 5       r\S 5       rS rS r	S r
S rS	rg
)r>   i-  zCoupled eigenket of Jy.

See JzKetCoupled for the usage of coupled spin eigenstates.

See Also
========

JzKetCoupled: Usage of coupled spin states

c                     [         $ rS   ri  ra   s    rN   r   JyKetCoupled.dual_class9  r:  r\   c                     [         $ rS   rf  ra   s    rN   r  JyKetCoupled.uncoupled_class=  r5  r\   c                 &    U R                   " S0 UD6$ r   r   r   s     rN   r   %JyKetCoupled._represent_default_basisA  r   r\   c                 8    U R                   " SS[        S-  0UD6$ r]  r  r   s      rN   r!  JyKetCoupled._represent_JxOpD  s    ++B"Q$B'BBr\   c                 &    U R                   " S0 UD6$ r>  r  r   s      rN   r(  JyKetCoupled._represent_JyOpG  r  r\   c                 n    U R                   " S[        [        SS5      -  [        * S-  [        S-  S.UD6$ rb  r  r   s      rN   r   JyKetCoupled._represent_JzOpJ  s8    ++g"Xa^2C2#a%WYZ[W[g_fggr\   r   Nr  r   r\   rN   r>   r>   -  sE    	    5C7hr\   r>   c                   8    \ rS rSrSr\S 5       r\S 5       rSrg)r?   iN  zCoupled eigenbra of Jy.

See JzKetCoupled for the usage of coupled spin eigenstates.

See Also
========

JzKetCoupled: Usage of coupled spin states

c                     [         $ rS   rX  ra   s    rN   r   JyBraCoupled.dual_classZ  r:  r\   c                     [         $ rS   rU  ra   s    rN   r  JyBraCoupled.uncoupled_class^  r5  r\   r   Nr  r   r\   rN   r?   r?   N  r  r\   r?   c                   P    \ rS rSrSr\S 5       r\S 5       rS rS r	S r
S rS	rg
)r@   ic  a  Coupled eigenket of Jz

Spin state that is an eigenket of Jz which represents the coupling of
separate spin spaces.

The arguments for creating instances of JzKetCoupled are ``j``, ``m``,
``jn`` and an optional ``jcoupling`` argument. The ``j`` and ``m`` options
are the total angular momentum quantum numbers, as used for normal states
(e.g. JzKet).

The other required parameter in ``jn``, which is a tuple defining the `j_n`
angular momentum quantum numbers of the product spaces. So for example, if
a state represented the coupling of the product basis state
`\left|j_1,m_1\right\rangle\times\left|j_2,m_2\right\rangle`, the ``jn``
for this state would be ``(j1,j2)``.

The final option is ``jcoupling``, which is used to define how the spaces
specified by ``jn`` are coupled, which includes both the order these spaces
are coupled together and the quantum numbers that arise from these
couplings. The ``jcoupling`` parameter itself is a list of lists, such that
each of the sublists defines a single coupling between the spin spaces. If
there are N coupled angular momentum spaces, that is ``jn`` has N elements,
then there must be N-1 sublists. Each of these sublists making up the
``jcoupling`` parameter have length 3. The first two elements are the
indices of the product spaces that are considered to be coupled together.
For example, if we want to couple `j_1` and `j_4`, the indices would be 1
and 4. If a state has already been coupled, it is referenced by the
smallest index that is coupled, so if `j_2` and `j_4` has already been
coupled to some `j_{24}`, then this value can be coupled by referencing it
with index 2. The final element of the sublist is the quantum number of the
coupled state. So putting everything together, into a valid sublist for
``jcoupling``, if `j_1` and `j_2` are coupled to an angular momentum space
with quantum number `j_{12}` with the value ``j12``, the sublist would be
``(1,2,j12)``, N-1 of these sublists are used in the list for
``jcoupling``.

Note the ``jcoupling`` parameter is optional, if it is not specified, the
default coupling is taken. This default value is to coupled the spaces in
order and take the quantum number of the coupling to be the maximum value.
For example, if the spin spaces are `j_1`, `j_2`, `j_3`, `j_4`, then the
default coupling couples `j_1` and `j_2` to `j_{12}=j_1+j_2`, then,
`j_{12}` and `j_3` are coupled to `j_{123}=j_{12}+j_3`, and finally
`j_{123}` and `j_4` to `j=j_{123}+j_4`. The jcoupling value that would
correspond to this is:

    ``((1,2,j1+j2),(1,3,j1+j2+j3))``

Parameters
==========

args : tuple
    The arguments that must be passed are ``j``, ``m``, ``jn``, and
    ``jcoupling``. The ``j`` value is the total angular momentum. The ``m``
    value is the eigenvalue of the Jz spin operator. The ``jn`` list are
    the j values of argular momentum spaces coupled together. The
    ``jcoupling`` parameter is an optional parameter defining how the spaces
    are coupled together. See the above description for how these coupling
    parameters are defined.

Examples
========

Defining simple spin states, both numerical and symbolic:

    >>> from sympy.physics.quantum.spin import JzKetCoupled
    >>> from sympy import symbols
    >>> JzKetCoupled(1, 0, (1, 1))
    |1,0,j1=1,j2=1>
    >>> j, m, j1, j2 = symbols('j m j1 j2')
    >>> JzKetCoupled(j, m, (j1, j2))
    |j,m,j1=j1,j2=j2>

Defining coupled spin states for more than 2 coupled spaces with various
coupling parameters:

    >>> JzKetCoupled(2, 1, (1, 1, 1))
    |2,1,j1=1,j2=1,j3=1,j(1,2)=2>
    >>> JzKetCoupled(2, 1, (1, 1, 1), ((1,2,2),(1,3,2)) )
    |2,1,j1=1,j2=1,j3=1,j(1,2)=2>
    >>> JzKetCoupled(2, 1, (1, 1, 1), ((2,3,1),(1,2,2)) )
    |2,1,j1=1,j2=1,j3=1,j(2,3)=1>

Rewriting the JzKetCoupled in terms of eigenkets of the Jx operator:
Note: that the resulting eigenstates are JxKetCoupled

    >>> JzKetCoupled(1,1,(1,1)).rewrite("Jx")
    |1,-1,j1=1,j2=1>/2 - sqrt(2)*|1,0,j1=1,j2=1>/2 + |1,1,j1=1,j2=1>/2

The rewrite method can be used to convert a coupled state to an uncoupled
state. This is done by passing coupled=False to the rewrite function:

    >>> JzKetCoupled(1, 0, (1, 1)).rewrite('Jz', coupled=False)
    -sqrt(2)*|1,-1>x|1,1>/2 + sqrt(2)*|1,1>x|1,-1>/2

Get the vector representation of a state in terms of the basis elements
of the Jx operator:

    >>> from sympy.physics.quantum.represent import represent
    >>> from sympy.physics.quantum.spin import Jx
    >>> from sympy import S
    >>> represent(JzKetCoupled(1,-1,(S(1)/2,S(1)/2)), basis=Jx)
    Matrix([
    [        0],
    [      1/2],
    [sqrt(2)/2],
    [      1/2]])

See Also
========

JzKet: Normal spin eigenstates
uncouple: Uncoupling of coupling spin states
couple: Coupling of uncoupled spin states

c                     [         $ rS   r  ra   s    rN   r   JzKetCoupled.dual_class  r:  r\   c                     [         $ rS   r}  ra   s    rN   r  JzKetCoupled.uncoupled_class  r5  r\   c                 &    U R                   " S0 UD6$ r   r   r   s     rN   r   %JzKetCoupled._represent_default_basis  r   r\   c           	      L    U R                   " SS[        [        SS5      -  0UD6$ ru  r  r   s      rN   r!  JzKetCoupled._represent_JxOp  s&    ++NHQN1BNgNNr\   c                 l    U R                   " S[        [        SS5      -  [        S-  [        S-  S.UD6$ rb  r  r   s      rN   r(  JzKetCoupled._represent_JyOp  s6    ++f"Xa^2C"Q$VXYZVZf^effr\   c                 &    U R                   " S0 UD6$ r>  r  r   s      rN   r   JzKetCoupled._represent_JzOp  r  r\   r   Nr  r   r\   rN   r@   r@   c  sG    rh    5Og7r\   r@   c                   8    \ rS rSrSr\S 5       r\S 5       rSrg)rA   i  zCoupled eigenbra of Jz.

See the JzKetCoupled for the usage of coupled spin eigenstates.

See Also
========

JzKetCoupled: Usage of coupled spin states

c                     [         $ rS   rp  ra   s    rN   r   JzBraCoupled.dual_class  r:  r\   c                     [         $ rS   rm  ra   s    rN   r  JzBraCoupled.uncoupled_class  r5  r\   r   Nr  r   r\   rN   rA   rA     r  r\   rA   Nc                    ^ U R                  [        5      nU Hq  m[        S TR                   5       5      (       d  M&  [        U4S jTR                   5       5      (       d  [	        S5      eU R                  T[        TU5      5      n Ms     U $ )a,	  Couple a tensor product of spin states

This function can be used to couple an uncoupled tensor product of spin
states. All of the eigenstates to be coupled must be of the same class. It
will return a linear combination of eigenstates that are subclasses of
CoupledSpinState determined by Clebsch-Gordan angular momentum coupling
coefficients.

Parameters
==========

expr : Expr
    An expression involving TensorProducts of spin states to be coupled.
    Each state must be a subclass of SpinState and they all must be the
    same class.

jcoupling_list : list or tuple
    Elements of this list are sub-lists of length 2 specifying the order of
    the coupling of the spin spaces. The length of this must be N-1, where N
    is the number of states in the tensor product to be coupled. The
    elements of this sublist are the same as the first two elements of each
    sublist in the ``jcoupling`` parameter defined for JzKetCoupled. If this
    parameter is not specified, the default value is taken, which couples
    the first and second product basis spaces, then couples this new coupled
    space to the third product space, etc

Examples
========

Couple a tensor product of numerical states for two spaces:

    >>> from sympy.physics.quantum.spin import JzKet, couple
    >>> from sympy.physics.quantum.tensorproduct import TensorProduct
    >>> couple(TensorProduct(JzKet(1,0), JzKet(1,1)))
    -sqrt(2)*|1,1,j1=1,j2=1>/2 + sqrt(2)*|2,1,j1=1,j2=1>/2


Numerical coupling of three spaces using the default coupling method, i.e.
first and second spaces couple, then this couples to the third space:

    >>> couple(TensorProduct(JzKet(1,1), JzKet(1,1), JzKet(1,0)))
    sqrt(6)*|2,2,j1=1,j2=1,j3=1,j(1,2)=2>/3 + sqrt(3)*|3,2,j1=1,j2=1,j3=1,j(1,2)=2>/3

Perform this same coupling, but we define the coupling to first couple
the first and third spaces:

    >>> couple(TensorProduct(JzKet(1,1), JzKet(1,1), JzKet(1,0)), ((1,3),(1,2)) )
    sqrt(2)*|2,2,j1=1,j2=1,j3=1,j(1,3)=1>/2 - sqrt(6)*|2,2,j1=1,j2=1,j3=1,j(1,3)=2>/6 + sqrt(3)*|3,2,j1=1,j2=1,j3=1,j(1,3)=2>/3

Couple a tensor product of symbolic states:

    >>> from sympy import symbols
    >>> j1,m1,j2,m2 = symbols('j1 m1 j2 m2')
    >>> couple(TensorProduct(JzKet(j1,m1), JzKet(j2,m2)))
    Sum(CG(j1, m1, j2, m2, j, m1 + m2)*|j,m1 + m2,j1=j1,j2=j2>, (j, m1 + m2, j1 + j2))

c              3   B   #    U  H  n[        U[        5      v   M     g 7frS   )r   r  r  r   s     rN   r  couple.<locals>.<genexpr>C  s     EWE:eY//W   c              3   l   >#    U  H)  oR                   TR                  S    R                   L v   M+     g7f)r   N)r   r`   )r  r   r   s     rN   r  r   F  s&     Pu??bggaj&:&::s   14z!All states must be the same basis)atomsr(   r  r`   r  r  _couple)exprjcoupling_listrq   r   s      @rN   rB   rB     su    t 	

=!AERWWEEEPPPP?@@yyWR89  Kr\   c                 .   U R                   nUS   R                  5       nUc4  / n[        S[        U5      5       H  nUR	                  SUS-   45        M     [        U5      [        U5      S-
  :X  d%  [        S[        U5      S-
  [        U5      4-  5      e[        S U 5       5      (       d  [        S5      e[        S U 5       5      (       a  [        S5      e[        S U 5       5      (       aL  S/[        U5      -  nU H7  u  pgXVS-
     S	:X  d  XWS-
     S	:X  a  [        S
5      eS	U[        Xg5      S-
  '   M9     U Vs/ s H  oR                  PM     n	nU Vs/ s H  oR                  PM     n
n/ n[        [        U5      5       Vs/ s H  oS-   /PM
     nnU HW  nUu  pg[        XS-
     5      n[        XS-
     5      nUR	                  UU45        [        UU-   5      U[        Xg5      S-
  '   MY     [        S U 5       5      (       GaF  U VVs/ s H2  n[        US   US   -    Vs/ s H  oIUS-
     XS-
     -
  PM     sn6 PM4     nnn/ n[        US	   S-   5       GH  n[        U5      n[!        UU-   S-
  U5      n[        U5       GH  n[#        UUU5      n[        S [%        UU5       5       5      (       a  M4  / n[        U	5      n/ n[%        UU5       H  u  u  nnnU[        U5      S-
     nU[        U5      S-
     nUU-   U-
  nUU[        UU-   5      S-
  '   [        U Vs/ s H  nU
US-
     PM     sn6 n [        U Vs/ s H  nU
US-
     PM     sn6 n!U U!-   n"UR	                  UU UU!UU"45        UR	                  [        U5      [        U5      U45        M     [        S U 5       5      (       a  GM4  [        S U 5       5      (       a  GMN  [        S U 5       5      (       a  GMh  ['        U V#s/ s H  n#[)        U#6 R+                  5       PM     sn#6 n$U" WW"U	U5      nUR	                  U$U-  5        GM     GM     [        U6 $ / n/ n/ n%[        U	5      nU GH1  u  nnU[        U5      S-
     nU[        U5      S-
     n[        UU-   5      [        U5      :X  a  [-        S5      nO6SSR/                  UU-    Vs/ s H  nSU-  PM
     sn5      -   n&[-        U&5      nUU[        UU-   5      S-
  '   [        U Vs/ s H  nU
US-
     PM     sn6 n [        U Vs/ s H  nU
US-
     PM     sn6 n!U U!-   n"UR	                  UU UU!UU"45        UR	                  [        U5      [        U5      U45        U%R	                  UU"UU-   45        GM4     ['        U V#s/ s H  n#[)        U#6 PM     sn#6 n$U" WW"U	U5      n[1        U$U-  /U%Q76 $ s  snf s  snf s  snf s  snf s  snnf s  snf s  snf s  sn#f s  snf s  snf s  snf s  sn#f )Nr   rF   z(jcoupling_list must be length %d, got %dc              3   >   #    U  H  n[        U5      S :H  v   M     g7fr  r  )r  r   s     rN   r  _couple.<locals>.<genexpr>Z  s     B>xH">r  z"Each coupling must define 2 spacesc              3   .   #    U  H  u  pX:H  v   M     g 7frS   r   r  r  r  s      rN   r  r)  \  s     
1.28.   z'Spin spaces cannot couple to themselvesc              3      #    U  H8  u  p[        U5      R                  =(       a    [        U5      R                  v   M:     g 7frS   )r   r  r+  s      rN   r  r)  ^  s.     
Xvr72;  :WR[%:%::s   A Ar  z8Spaces coupling j_n's are referenced by smallest n valuec              3      #    U  H7  oR                   R                  =(       a    UR                  R                  v   M9     g 7frS   )rK   r  r   r  s     rN   r  r)  w  s*     
Gu772!2!22s   ?Ac              3   .   #    U  H  u  pX:  v   M     g 7frS   r   )r  r  r   s      rN   r  r)    s     B)Aqu)Ar,  c              3   J   #    U  H  n[        US    5      US   :  v   M     g7f)r  r  Nr  r  s     rN   r  r)    s!     C($s47|d1g-(s   !#c              3   B   #    U  H  oS    US   -   US   :  v   M     g7fr   rE   r  Nr   r  s     rN   r  r)    s$     HxtAwa(472xr!  c              3   V   #    U  H  n[        US    US   -
  5      US   :  v   M!     g7fr3  r1  r  s     rN   r  r)    s+     MHDs47T!W,-Q7Hs   ')rK    z%s)r`   r8  rI   r   r   r  r  rH   r  r  rK   r   r  r  r  r   r   _confignum_to_difflistr  r   r)   r  r   r  r   )'r   r&  statescoupled_evectr   j_testr  r  r   r   mncoupling_listrM   r  
j_couplingj1_nj2_nr   diff_maxr   difftot
config_num	diff_listcg_terms	coupled_jr  coupling_diffr  r  r  r  m1m2m3r  coeff	sum_termsj3_names'                                          rN   r$  r$  L  s1   WWF1I++-M q#f+&A!!Aq1u:/ ' ~#f+/1BVq#n*=>? @ 	@B>BBB=>>

1.
111BCC

X
XXXS[$FB1f~#v1f~'; !\]]&(F3r;?# %  &	&ve''vB	&%	&ve''vB	& M %c&k 24 21Aw 2F4$
F6N#F6N#tTl,$*4$;$7Ba! % 
G
GGG :GI9FX HQK!!=% ' =%qAYE2 =% ' )9F 	 I(2,*+DM"A4!8a<.C#Cj
2:tQG	 BY)ABBB  H		36}i3P/LT4-"CIM3B"CIM3Bb=0B8:Is4$;/!35D9DqAED9;BD9DqAED9;BbBOOb"b"b"%=?$$s4y#d)R&@B 4Q C(CCCHxHHHMHMMMXFXTD	 0XFH%b"b)<eEk*? ) ,J F| 		H	'JD$CIM+BCIM+B4$;3v;.S\4$;(G;a;(G HHW%02Is4$;'!+-D1DqAED13BD1DqAED13BbBOOb"b"b"57s4y#d)R8:b"b2g./ ( h7hdD	h79b"b)45;+++i 
'	&
 5' I2  :9 G  )H 21
 8sT   WWW$W./W)W.1W4W9 W>XX
-X
*X)W.c           	      z    U R                  [        5      nU H  nU R                  U[        XAU5      5      n M!     U $ )aE
  Uncouple a coupled spin state

Gives the uncoupled representation of a coupled spin state. Arguments must
be either a spin state that is a subclass of CoupledSpinState or a spin
state that is a subclass of SpinState and an array giving the j values
of the spaces that are to be coupled

Parameters
==========

expr : Expr
    The expression containing states that are to be coupled. If the states
    are a subclass of SpinState, the ``jn`` and ``jcoupling`` parameters
    must be defined. If the states are a subclass of CoupledSpinState,
    ``jn`` and ``jcoupling`` will be taken from the state.

jn : list or tuple
    The list of the j-values that are coupled. If state is a
    CoupledSpinState, this parameter is ignored. This must be defined if
    state is not a subclass of CoupledSpinState. The syntax of this
    parameter is the same as the ``jn`` parameter of JzKetCoupled.

jcoupling_list : list or tuple
    The list defining how the j-values are coupled together. If state is a
    CoupledSpinState, this parameter is ignored. This must be defined if
    state is not a subclass of CoupledSpinState. The syntax of this
    parameter is the same as the ``jcoupling`` parameter of JzKetCoupled.

Examples
========

Uncouple a numerical state using a CoupledSpinState state:

    >>> from sympy.physics.quantum.spin import JzKetCoupled, uncouple
    >>> from sympy import S
    >>> uncouple(JzKetCoupled(1, 0, (S(1)/2, S(1)/2)))
    sqrt(2)*|1/2,-1/2>x|1/2,1/2>/2 + sqrt(2)*|1/2,1/2>x|1/2,-1/2>/2

Perform the same calculation using a SpinState state:

    >>> from sympy.physics.quantum.spin import JzKet
    >>> uncouple(JzKet(1, 0), (S(1)/2, S(1)/2))
    sqrt(2)*|1/2,-1/2>x|1/2,1/2>/2 + sqrt(2)*|1/2,1/2>x|1/2,-1/2>/2

Uncouple a numerical state of three coupled spaces using a CoupledSpinState state:

    >>> uncouple(JzKetCoupled(1, 1, (1, 1, 1), ((1,3,1),(1,2,1)) ))
    |1,-1>x|1,1>x|1,1>/2 - |1,0>x|1,0>x|1,1>/2 + |1,1>x|1,0>x|1,0>/2 - |1,1>x|1,1>x|1,-1>/2

Perform the same calculation using a SpinState state:

    >>> uncouple(JzKet(1, 1), (1, 1, 1), ((1,3,1),(1,2,1)) )
    |1,-1>x|1,1>x|1,1>/2 - |1,0>x|1,0>x|1,1>/2 + |1,1>x|1,0>x|1,0>/2 - |1,1>x|1,1>x|1,-1>/2

Uncouple a symbolic state using a CoupledSpinState state:

    >>> from sympy import symbols
    >>> j,m,j1,j2 = symbols('j m j1 j2')
    >>> uncouple(JzKetCoupled(j, m, (j1, j2)))
    Sum(CG(j1, m1, j2, m2, j, m)*|j1,m1>x|j2,m2>, (m1, -j1, j1), (m2, -j2, j2))

Perform the same calculation using a SpinState state

    >>> uncouple(JzKet(j, m), (j1, j2))
    Sum(CG(j1, m1, j2, m2, j, m)*|j1,m1>x|j2,m2>, (m1, -j1, j1), (m2, -j2, j2))

)r#  r  r  	_uncouple)r%  r   r&  rq   r   s        rN   rC   rC     s9    H 	

9Ayy	%^ DE Kr\   c                 
   [        U [        5      (       a6  U R                  nU R                  nU R                  nU R                  5       nGO"[        U [        5      (       Ga  Uc  [        S5      e[        U[        [        45      (       d  [        S5      eUcZ  / n[        S[        U5      5       H?  nUR                  SSU-   [        [        US-   5       Vs/ s H  oqU   PM	     sn6 45        MA     [        U[        [        45      (       d  [        S5      e[        U5      [        U5      S-
  :X  d  [        S5      e[        U[        U5      5      u  p4U R                   nO[        S5      eU R"                  nU R$                  n/ n	[        U5      n
['        XC5       HB  u  nu  pXS   S-
     nXS   S-
     nU	R                  XXU45        X[)        X-   5      S-
  '   MD     UR*                  (       Ga  UR*                  (       Ga{  U Vs/ s H  nSU-  PM
     nn[        U6 U-
  n[        U5      n[-        UU-   S-
  U5      n/ n[        U5       GH$  n[/        UUU5      n[1        S	 ['        UU5       5       5      (       a  M4  / nU	 Hv  nUu  nnpn[        U Vs/ s H  nUUS-
     UUS-
     -
  PM     sn6 n[        U Vs/ s H  nUUS-
     UUS-
     -
  PM     sn6 nUU-   nUR                  UUUUUU45        Mx     [3        U Vs/ s H  n[5        U6 R7                  5       PM     sn6 n [9        ['        UU5       VV!s/ s H  u  nn!U" XwU!-
  5      PM     sn!n6 n UR                  U U -  5        GM'     [        U6 $ S
[        U5      S-   -  n"[;        U"5      n#U	S S  VVVVVVs/ s Hj  u  nnpnU[        U Vs/ s H  nU#US-
     PM     sn6 U[        U Vs/ s H  nU#US-
     PM     sn6 U[        UU-    Vs/ s H  nU#US-
     PM     sn6 4PMl     nnnnnnnUR                  " U	S   4 VVVVVVs/ s HI  u  nnpnU[        U Vs/ s H  nU#US-
     PM     sn6 U[        U Vs/ s H  nU#US-
     PM     sn6 Xx4PMK     snnnnnn6   [3        U V$s/ s H  n$[5        U$6 PM     sn$6 n%['        UU#5       VVs/ s H
  u  pxX* U4PM     n&nn[9        ['        UU#5       VVs/ s H  u  pxU" Xx5      PM     snn6 n [=        U%U -  /U&Q76 $ s  snf s  snf s  snf s  snf s  snf s  sn!nf s  snf s  snf s  snf s  snnnnnnf s  snf s  snf s  snnnnnnf s  sn$f s  snnf s  snnf )Nz'Must specify j-values for coupled statezjn must be list or tuplerF   z!jcoupling must be a list or tuplez?Must specify 2 fewer coupling terms than the number of j valueszstate must be a spin stater   rE   c              3   .   #    U  H  u  pX:  v   M     g 7frS   r   )r  r  r   s      rN   r  _uncouple.<locals>.<genexpr>9  s     >%=TQ15%=r,  zm1:%dr  )r   r  r   r  r  r  r  rH   r  r  r  rI   r   r   r   r  r   rK   r   r  r  r  r   r6  r  r   r)   r  r(   r   r   )'r   r   r&  r  r  r  rM   rK   r   r;  j_listr  r  r  r  r  r  r?  r@  r   rA  r   rB  rC  rD  r   r=  r>  rG  rH  rI  r  rJ  r  m_strr   cg_termcg_coeffrK  s'                                          rN   rN  rN    sn   %)**XXOO	%%
%%'	E9	%	%:FGG"tUm,,677!N1c"g&%%AsE!a%L$ALqUL$ABCF ' .4-88?@@>"c"gk1^__ .~s2w G	455AAM"XF J2HRqEAIqEAIrrr24#%s27|a  3 	{{{q{{{"$&"QQqS"&Bx!|Gtax!|T**J.z4CI>SH%=>>>H))1&dBB4I4aRAY1q5)994IK4I4aRAY1q5)994IK"W"b"b"b!9; * CBINN,CEE!/22y/AC/Atq!5E?/ACFEMM%+& %  F| 3r7Q;' cppsqsbtw wbtH^dTV\^ T:TuQU|T:;T:TuQU|T:;TD[A[uQU|[ABDbt 	 w 	@Mb@Q?RU U?R%;T4 s4$@4aU1q5\4$@As4$@4aU1q5\4$@A!?RU 	V X>X'WX>?-0U^=^TQq"aj^	=#b%. J.$!%+. JL8E>.I..} %B2 ' JI DC ;:Aw %A$@U ?= Js   TTTT" T'
T,+U T2UT71UT<"	U<UU#U0U"
UUU$+U*
2U
Uc                     / n[        U5       HV  nUnX$-
  S-
  n[        X-   S-
  U5      nX:  a!  X-  n US-  n[        X-   S-
  U5      nX:  a  M!  UR                  XQ-
  5        MX     U$ r   )rI   r   r   )rB  r@  list_lenrC  r   	prev_diff	rem_spotsrem_configss           rN   r6  r6  X  s    I8_	L1$	t/!3T:'%JAID"4#3a#7>K ' 	)*  r\   rS   )NN)gr   sympy.concrete.summationsr   sympy.core.addr   sympy.core.containersr   sympy.core.exprr   sympy.core.numbersr   sympy.core.mulr   r	   r
   r   r   sympy.core.singletonr   sympy.core.symbolr   r   sympy.core.sympifyr   (sympy.functions.combinatorial.factorialsr   r   &sympy.functions.elementary.exponentialr   (sympy.functions.elementary.miscellaneousr   (sympy.functions.elementary.trigonometricr   r   sympy.simplify.simplifyr   sympy.matricesr    sympy.printing.pretty.stringpictr   r   &sympy.printing.pretty.pretty_symbologyr   sympy.physics.quantum.qexprr   sympy.physics.quantum.operatorr   r   r    sympy.physics.quantum.stater!   r"   r#   (sympy.functions.special.tensor_functionsr$   sympy.physics.quantum.constantsr%   sympy.physics.quantum.hilbertr&   r'   #sympy.physics.quantum.tensorproductr(   sympy.physics.quantum.cgr)   sympy.physics.quantum.qapplyr*   __all__r+   rP   r   r   r   r   r:   r;   r2   r3   r.   r/   r0   r1   r,   r-   r  r4   r5   r6   r7   r8   r9   r  r  r<   r=   r>   r?   r@   rA   rB   r$  rC   rN  r6  r   r\   rN   <module>rv     s=   * )  '   )  9 9 " . & J 6 9 ? ,   C @ -= = 7 7 C 0 M = ' /:6\7 \7~)/j( )/X&/z8 &/R 8:(  8F <:(  <F6:( 6@FE:( FERIJ IJVMd M` 
#Y	#Y	#Y	#Y	#Z! Z!z:Is :BIs *`Is `BIs *A/Is A/HIs 2	!i@y i@XB#S BB#S *h#S hB#S *G7#S G7T#S 2CLn,bGTN/br\   