(phmSrSSKrSSKrSSKJrJr SSKJrJ r SSK J r SSK J r Jr SSKJr SSKJr SSKr"S S \5r"S S \5r"S S\5r"SS\R2R45r"SS\R2R45r"SS\5rS#SjrSrSr Sr!Sr"Sr#Sr$Sr%Sr&Sr'Sr(S r)S$S!jr*S"r+g)%zR Matrix functions that use Pade approximation with inverse scaling and squaring. N) SqrtmError _sqrtm_triu)schurrsf2csf)funm)svdvalssolve_triangular)LinearOperator) onenormestc\rSrSrSrg)LogmRankWarningN__name__ __module__ __qualname____firstlineno____static_attributes__rQ/var/www/html/venv/lib/python3.13/site-packages/scipy/linalg/_matfuncs_inv_ssq.pyr r rr c\rSrSrSrg)LogmExactlySingularWarningrNrrrrrrrrrc\rSrSrSrg)LogmNearlySingularWarningrNrrrrrrrrrc\rSrSrSrg) LogmErrorrNrrrrr r rrr c\rSrSrSrg)FractionalMatrixPowerError"rNrrrrr#r#"rrr#c6\rSrSrSrSrSrSrSrSr Sr g ) _MatrixM1PowerOperator'z4 A representation of the linear operator (A - I)^p. cURS:wd URSURS:wa [S5eUS:dU[U5:wa [S5eXlX lURUlURUlg)Nrz%expected A to be like a square matrixz'expected p to be a non-negative integer)ndimshape ValueErrorint_A_p)selfAps r__init___MatrixM1PowerOperator.__init__,sm 66Q;!''!* 2DE E q5AQKFG GFF WW rcz[UR5H!nURRU5U- nM# U$Nranger0r/dotr1xis r_matvec_MatrixM1PowerOperator._matvec6/twwA A"A rcz[UR5H!nURUR5U- nM# U$r7)r9r0r:r/r;s r_rmatvec_MatrixM1PowerOperator._rmatvec;s/twwAdgg"A rcz[UR5H!nURRU5U- nM# U$r7r8)r1Xr=s r_matmat_MatrixM1PowerOperator._matmat@r@rcV[URRUR5$r7)r&r/Tr0)r1s r_adjoint_MatrixM1PowerOperator._adjointEs%dggii99r)r/r0r+r,N) rrrr__doc__r4r>rBrFrJrrrrr&r&'s    :rr&c*[[X5X#XES9$)aM Efficiently estimate the 1-norm of (A - I)^p. Parameters ---------- A : ndarray Matrix whose 1-norm of a power is to be computed. p : int Non-negative integer power. t : int, optional A positive parameter controlling the tradeoff between accuracy versus time and memory usage. Larger values take longer and use more memory but give more accurate output. itmax : int, optional Use at most this many iterations. compute_v : bool, optional Request a norm-maximizing linear operator input vector if True. compute_w : bool, optional Request a norm-maximizing linear operator output vector if True. Returns ------- est : float An underestimate of the 1-norm of the sparse matrix. v : ndarray, optional The vector such that ||Av||_1 == est*||v||_1. It can be thought of as an input to the linear operator that gives an output with particularly large norm. w : ndarray, optional The vector Av which has relatively large 1-norm. It can be thought of as an output of the linear operator that is relatively large in norm compared to the input. )titmax compute_v compute_w)r r&)r2r3rNrOrPrQs r_onenormest_m1_powerrRJs!J ,Q2  HHrc[[R"UR[R- S[R-- 55$)a0 Compute the scalar unwinding number. Uses Eq. (5.3) in [1]_, and should be equal to (z - log(exp(z)) / (2 pi i). Note that this definition differs in sign from the original definition in equations (5, 6) in [2]_. The sign convention is justified in [3]_. Parameters ---------- z : complex A complex number. Returns ------- unwinding_number : integer The scalar unwinding number of z. References ---------- .. [1] Nicholas J. Higham and Lijing lin (2011) "A Schur-Pade Algorithm for Fractional Powers of a Matrix." SIAM Journal on Matrix Analysis and Applications, 32 (3). pp. 1056-1078. ISSN 0895-4798 .. [2] Robert M. Corless and David J. Jeffrey, "The unwinding number." Newsletter ACM SIGSAM Bulletin Volume 30, Issue 2, June 1996, Pages 28-35. .. [3] Russell Bradford and Robert M. Corless and James H. Davenport and David J. Jeffrey and Stephen M. Watt, "Reasoning about the elementary functions of complex analysis" Annals of Mathematics and Artificial Intelligence, 36: 303-318, 2002. r))r.npceilimagpi)zs r_unwindkrYss2H rww1RUU734 55rcUS:d[U5U:wa [S5eUS:XaUS- $US:Xa[R"U5S- $Un[R"U5[R S- :a[R"U5nUS- nUS- n[R"U5nSU-n[ SU5H!n[R"U5nUSU--nM# X4- nU$)a+ Computes r = a^(1 / (2^k)) - 1. This is algorithm (2) of [1]_. The purpose is to avoid a danger of subtractive cancellation. For more computational efficiency it should probably be cythonized. Parameters ---------- a : complex A complex number. k : integer A nonnegative integer. Returns ------- r : complex The value r = a^(1 / (2^k)) - 1 computed with less cancellation. Notes ----- The algorithm as formulated in the reference does not handle k=0 or k=1 correctly, so these are special-cased in this implementation. This function is intended to not allow `a` to belong to the closed negative real axis, but this constraint is relaxed. References ---------- .. [1] Awad H. Al-Mohy (2012) "A more accurate Briggs method for the logarithm", Numerical Algorithms, 59 : 393--402. rz expected a nonnegative integer kr*r))r.r-rTsqrtanglerWr9)akk_hatz0rjs r_briggs_helper_functionrcsD 1uA! ;<<Av1u awwqzA~ 88A;"%%!) # AEE U GGAJ Eq%A AQU A! FrcX:XaX#-XS- --nU$[X- 5[X-5S- :aX!U-X-- -X- - nU$X- X-- n[R"U5n[R"U5n[R"U5nU[R"US- Xv--5-n [ Xv- 5n U (aX8[R S-U ---n OX8-n S[R"U 5-X- - n X-nU$)a Compute a superdiagonal entry of a fractional matrix power. This is Eq. (5.6) in [1]_. Parameters ---------- l1 : complex A diagonal entry of the matrix. l2 : complex A diagonal entry of the matrix. t12 : complex A superdiagonal entry of the matrix. p : float A fractional power. Returns ------- f12 : complex A superdiagonal entry of the fractional matrix power. Notes ----- Care has been taken to return a real number if possible when all of the inputs are real numbers. References ---------- .. [1] Nicholas J. Higham and Lijing lin (2011) "A Schur-Pade Algorithm for Fractional Powers of a Matrix." SIAM Journal on Matrix Analysis and Applications, 32 (3). pp. 1056-1078. ISSN 0895-4798 r*r)?)absrTlogarctanhexprYrWsinh) l1l2t12r3f12rXlog_l1log_l2 arctanh_ztmp_atmp_utmp_btmp_cs r!_fractional_power_superdiag_entryrvs F xgqS !" J! RWBG q( (!e&'273 JW !JJqM bffacFO455) RUURZ%%778EMEBGGEN"bg.m Jrc X:XaX - nU$[X- 5[X-5S- :a7U[R"U5[R"U5- -X- - nU$X- X-- n[[R"U5[R"U5- 5nU(a:US-[R"U5[R S-U---X- - nU$US-[R"U5-X- - nU$)a Compute a superdiagonal entry of a matrix logarithm. This is like Eq. (11.28) in [1]_, except the determination of whether l1 and l2 are sufficiently far apart has been modified. Parameters ---------- l1 : complex A diagonal entry of the matrix. l2 : complex A diagonal entry of the matrix. t12 : complex A superdiagonal entry of the matrix. Returns ------- f12 : complex A superdiagonal entry of the matrix logarithm. Notes ----- Care has been taken to return a real number if possible when all of the inputs are real numbers. References ---------- .. [1] Nicholas J. Higham (2008) "Functions of Matrices: Theory and Computation" ISBN 978-0-898716-46-7 r)re)rfrTrgrYrhrW)rkrlrmrnrXus r_logm_superdiag_entryry sB xh J RWBG q( (RVVBZ"&&*,-9 J W ! RVVBZ"&&*, - 'RZZ]RUU2XaZ78BGDC J'BJJqM)RW5C Jrc^^[UR5S:wd URSURS:wa [S5eURu nUnSn[R"U5n[R "U5U:wa [ S5e[R"[R"US- 5SS9TS:aP[R"U5nUS- n[R"[R"US- 5SS9TS:aMP[U5Hn[U5nM UnSn[US5S -n [US 5S -n [X5n S n S HnU TU::dMUn O U cXt:a[US 5S -n [US5S-n [X5mTTS::aH[UU4SjS55nUS::aUn O~TS- TS::aUS:aUS- n[U5nUS- nM[US5S-n[X5n[TU5nSHnUTU::dMUn O U bO[U5nUS- nU cMU[R"U5- n[S[R"U555nU(a[U5HnUUU4n[!UU5nUUUU4'M [R""U*5n[US- 5H9nUUU4nUUS-US-4nUUUS-4n[%UUUU5nUUUUS-4'M; [R&"U[R("U55(d [ S5eUX|4$)a A helper function for inverse scaling and squaring for Pade approximation. Parameters ---------- T0 : (N, N) array_like upper triangular Matrix involved in inverse scaling and squaring. theta : indexable The values theta[1] .. theta[7] must be available. They represent bounds related to Pade approximation, and they depend on the matrix function which is being computed. For example, different values of theta are required for matrix logarithm than for fractional matrix power. Returns ------- R : (N, N) array_like upper triangular Composition of zero or more matrix square roots of T0, minus I. s : non-negative integer Number of square roots taken. m : positive integer The degree of the Pade approximation. Notes ----- This subroutine appears as a chunk of lines within a couple of published algorithms; for example it appears as lines 4--35 in algorithm (3.1) of [1]_, and as lines 3--34 in algorithm (4.1) of [2]_. The instances of 'goto line 38' in algorithm (3.1) of [1]_ probably mean 'goto line 36' and have been interpreted accordingly. References ---------- .. [1] Nicholas J. Higham and Lijing Lin (2013) "An Improved Schur-Pade Algorithm for Fractional Powers of a Matrix and their Frechet Derivatives." .. [2] Awad H. Al-Mohy and Nicholas J. Higham (2012) "Improved Inverse Scaling and Squaring Algorithms for the Matrix Logarithm." SIAM Journal on Scientific Computing, 34 (4). C152-C169. ISSN 1095-7197 r)rr**expected an upper triangular square matrixz%Diagonal entries of T must be nonzeroinitial?gUUUUUU?N)r*r)g?c3>># UHnTTU::dMUv M g7fr7r).0r=a3thetas r +_inverse_squaring_helper..sB12q>QQs  )rrrrr皙?)rrc3j# UH)oRS:=(d URS:gv M+ g7frNrealrVrr<s rrr&N+Qvvz8QVVq[8+13zR is not upper triangular)lenr,r-rTdiag count_nonzero Exceptionmaxabsoluter[r9rrRminidentityallrcexp2rv array_equaltriu)T0rnrIs0tmp_diagr=sr^d2d3a2md4j1d5a4etaRhas_principal_branchrbr]rar3rkrlrmrnrs ` @r_inverse_squaring_helperr8sX\ 288}RXXa[BHHQK7EFF 88DAq A BwwqzH !Q&?@@ &&X\*B 7%( B778$ a &&X\*B 7%( B 2Y N A A a # ,B a # ,B RB A  q>A  ) 6%a+4B !!Q 'C 0 [ q>BBBBQwa58#AQNQ !!Q 'C 0 ["bkAeAh =  N Q3 )< BKKNAN"''"+NNqA1a4A'1-AAadG GGQBKqsAAqDBAaC1HBQ!V*C3BCCCAa1fI  >>!RWWQZ ( (344 a7Nrc US:a [S5eSUs=:aS:d O [S5eUS:XaU*$US-S:XaUS-nU*U-SSU-S- -- $US-S:XaUS- S-nU*U- SSU-S--- $[SU35e)Nr*zexpected a positive integer iexpected -1 < t < 1r)rzunnexpected value of i, i = )r-r)r=rNrbs r_fractional_power_pade_constantrs1u899 JQJ.//Avr Q! FQ1!a=)) Q! UqLQ1!a=))6qc:;;rcUS:d[U5U:wa [S5eSUs=:aS:d O [S5e[R"U5n[ UR 5S:wd UR SUR S:wa [S5eUR u n[R "U5nU[SU-U5-n[SU-S- SS5HnU[Xa5-n[XE-U5nM! XE-n[R"U[R"U55(d [S5eU$) aE Evaluate the Pade approximation of a fractional matrix power. Evaluate the degree-m Pade approximation of R to the fractional matrix power t using the continued fraction in bottom-up fashion using algorithm (4.1) in [1]_. Parameters ---------- R : (N, N) array_like Upper triangular matrix whose fractional power to evaluate. t : float Fractional power between -1 and 1 exclusive. m : positive integer Degree of Pade approximation. Returns ------- U : (N, N) array_like The degree-m Pade approximation of R to the fractional power t. This matrix will be upper triangular. References ---------- .. [1] Nicholas J. Higham and Lijing lin (2011) "A Schur-Pade Algorithm for Fractional Powers of a Matrix." SIAM Journal on Matrix Analysis and Applications, 32 (3). pp. 1056-1078. ISSN 0895-4798 r*zexpected a positive integer mrrr)rr{U is not upper triangular) r.r-rTasarrayrr,rrr9r rrr) rrNrridentYrbrhsUs r_fractional_power_paders> 1uA! 899 JQJ.// 1 A 177|qAGGAJ!''!*4EFF 77DAq KKNE +AaC 33A 1Q37Ar "1!77 UY ,#  A >>!RWWQZ ( (344 HrcXSSSSSSSS.nURu nUn[R"U5n[R"U[R"U55(a[R"XQ-5nO[ XB5upxn [ U*X5n[R"U5n [ S U 55n [US S 5Hn X:aURU5nMU (dM$U[R"U *5-n X]-U[R"U5'[US - 5H5nXNU4nXNS -US -4nXNUS -4n[UUUU 5nUXnUS -4'M7 M [R"U[R"U55(d [S 5eU$) ab Compute a fractional power of an upper triangular matrix. The fractional power is restricted to fractions -1 < t < 1. This uses algorithm (3.1) of [1]_. The Pade approximation itself uses algorithm (4.1) of [2]_. Parameters ---------- T : (N, N) array_like Upper triangular matrix whose fractional power to evaluate. t : float Fractional power between -1 and 1 exclusive. Returns ------- X : (N, N) array_like The fractional power of the matrix. References ---------- .. [1] Nicholas J. Higham and Lijing Lin (2013) "An Improved Schur-Pade Algorithm for Fractional Powers of a Matrix and their Frechet Derivatives." .. [2] Nicholas J. Higham and Lijing lin (2011) "A Schur-Pade Algorithm for Fractional Powers of a Matrix." SIAM Journal on Matrix Analysis and Applications, 32 (3). pp. 1056-1078. ISSN 0895-4798 gǖ2>gמYb?gUN@?g?W[?gX9v?rgB`"?)r*r)rrrrrc3j# UH)oRS:=(d URS:gv M+ g7frrrs rr/_remainder_matrix_power_triu..As&"Mf66A:#<1#>!RWWQZ ( (344 Hrc[R"U5n[UR5S:wd URSURS:wa [ S5eURu n[R "U[R "U55(aSnUnOr[R"U5(aK[U5upC[R "U[R "U55(d [XC5upCO [USS9upC[R"U5n[R"U5U:wa [S5e[R"U5(a/[R"U5S:aUR[5n[!XA5nUb@[R""U5R$nUR'U5R'U5$U$) a Compute the fractional power of a matrix, for fractions -1 < t < 1. This uses algorithm (3.1) of [1]_. The Pade approximation itself uses algorithm (4.1) of [2]_. Parameters ---------- A : (N, N) array_like Matrix whose fractional power to evaluate. t : float Fractional power between -1 and 1 exclusive. Returns ------- X : (N, N) array_like The fractional power of the matrix. References ---------- .. [1] Nicholas J. Higham and Lijing Lin (2013) "An Improved Schur-Pade Algorithm for Fractional Powers of a Matrix and their Frechet Derivatives." .. [2] Nicholas J. Higham and Lijing lin (2011) "A Schur-Pade Algorithm for Fractional Powers of a Matrix." SIAM Journal on Matrix Analysis and Applications, 32 (3). pp. 1056-1078. ISSN 0895-4798 r)rr*zinput must be a square arrayNcomplexoutputz`cannot use inverse scaling and squaring to find the fractional matrix power of a singular matrix)rTrrr,r-rr isrealobjrrrrr#rastyperr conjugaterIr:)r2rNrZrIT_diagrZHs r_remainder_matrix_powerrTsg@ 1 A 177|qAGGAJ!''!*4788 77DAq ~~a$$   <<??8DA>>!RWWQZ00q}9-DAWWQZF 1$(CD D  ||A266&>A- HHW  %Q*A} \\!_  uuQx||Brc^ [R"U5n[UR5S:wd URSURS:wa [ S5eU[ U5:Xa)[R RU[ U55$[U5nUS(aUSUS- nU[R"U5- nU[R"U5- nXCSU- --U*U-::a"[ [R"U55nUm O![ [R"U55nUm [UT 5n[R RX5nURU5$US:a7[R"U5n U R[R 5 U $U[R"U5- n[ [R"U55nUm [#UU 4SjSS9upz[R RX5nURU5$![R Ra Nf=f) zu Compute the fractional power of a matrix. See the fractional_matrix_power docstring in matfuncs.py for more info. r)rr*expected a square matrixrc>[UT5$r7)pow)r<bs r*_fractional_matrix_power..s C1IrF)disp)rTrrr,r-r.linalg matrix_powerrfloorrUrr: LinAlgError empty_likefillnanr) r2r3rk2p1p2r]rQrEinfors @r_fractional_matrix_powerrs 1 A 177|qAGGAJ!''!*4344CF{yy%%aQ00 A uqTAbE\ !_ ^ q2v 2#( *BHHQK AABGGAJAA '1-A &&q,A558O  1u MM!  rvv !_   q-E: II " "1 (uuQxyy$$   s<;H00IIcZ[R"U5n[UR5S:wd URSURS:wa [ S5eURu n[R "U5n[R "U5=(a [R"USS9S:nU(aUnOUR[5nSn[XE5upgn[RRU5upU Rn U RU4:wdU RU4:wa [S5eS S U --n S U -n [R "U5n [R""U5n [%X5HupU ['XU--X-5- n M U [R("U5-n [+S [R "U555nU(a[R,"[R "U55U [R."U5'[1US- 5H6nUUU4nUUS-US-4nUUUS-4n[3UUU5U UUS-4'M8 [R4"U [R6"U 55(d [S 5eU $) au Compute matrix logarithm of an upper triangular matrix. The matrix logarithm is the inverse of expm: expm(logm(`T`)) == `T` Parameters ---------- T : (N, N) array_like Upper triangular matrix whose logarithm to evaluate Returns ------- logm : (N, N) ndarray Matrix logarithm of `T` References ---------- .. [1] Awad H. Al-Mohy and Nicholas J. Higham (2012) "Improved Inverse Scaling and Squaring Algorithms for the Matrix Logarithm." SIAM Journal on Scientific Computing, 34 (4). C152-C169. ISSN 1095-7197 .. [2] Nicholas J. Higham (2008) "Functions of Matrices: Theory and Computation" ISBN 978-0-898716-46-7 .. [3] Nicholas J. Higham and Lijing lin (2011) "A Schur-Pade Algorithm for Fractional Powers of a Matrix." SIAM Journal on Matrix Analysis and Applications, 32 (3). pp. 1056-1078. ISSN 0895-4798 r)rr*r{r|r})Ng0>g3kb?gj+ݓ?gz):˯?gMb?g|?5^?g;On?grh|?gjt?gjt?gQ?grh|?gw/?g?5^I ?gOn?g+?zinternal errorrc3j# UH)oRS:=(d URS:gv M+ g7frrrs rr_logm_triu..rrr)rTrrr,r-rrrrrrscipyspecialp_rootsrrr zeros_likezipr rrrgrr9ryrr)rIrr keep_it_realrrrrrnodesweightsrralphabetarr=rkrlrms r _logm_triurs7F 1 A 177|qAGGAJ!''!*4EFF 77DAqWWQZF<<?Frvvfb'AQ'FL  XXg  0E 'r1GA!]]**1-NE JJE {{qdgmmt3()) #+ EGmG KKNE aA7*  e1fneg 66+OA N"''"+NN!#rwwr{ 3"//!  qsAAqDBAaC1HBQ!V*C-b"c:Aa1fI  >>!RWWQZ ( (344 HrcSn[R"[R"U55n[R"US:H5(ahSn[R "U[ SS9 U(dUR5nURSn[U5HnXU4(aMX Xf4'M U$[R"X2:5(aSn[R "U[SS9 U$)Ng#B ;rz*The logm input matrix is exactly singular.r) stacklevelz-The logm input matrix may be nearly singular.) rTrranywarningswarnrcopyr,r9r)rIinplacetri_epsabs_diagexact_singularity_msgrr=near_singularity_msgs r)_logm_force_nonsingular_triangular_matrixr4sG{{2771:&H vvh!m L +-GTUVA GGAJqAT77!!$ H " # #N *,ERST Hrc[R"U5n[UR5S:wd URSURS:wa [ S5e[ UR R[R5(a[R"U[S9n[R"U5n[R"U[R"U55(aX[U5n[R"[R"U5SS9S:aUR!["5n[%U5$U(aK['U5up#[R"U[R"U55(d [)X#5up#O ['USS 9up#[US S 9n[%U5n[R*"U5R,nUR/U5R/U5$![0[24a: [R4"U5nUR7[R85 Us$f=f) a. Compute the matrix logarithm. See the logm docstring in matfuncs.py for more info. Notes ----- In this function we look at triangular matrices that are similar to the input matrix. If any diagonal entry of such a triangular matrix is exactly zero then the original matrix is singular. The matrix logarithm does not exist for such matrices, but in such cases we will pretend that the diagonal entries that are zero are actually slightly positive by an ad-hoc amount, in the interest of returning something more useful than NaN. This will cause a warning. r)rr*r)dtyper|r}rrT)r)rTrrr,r- issubclassrtypeintegerfloatrrrrrrrrrrrrrIr:rr rrr)r2rrIrrrrEs r_logmrHs" 1 A 177|qAGGAJ!''!*4344!'',, ++ JJq &<<?L >>!RWWQZ ( (9!BG9B2G99AII)r)rFF)F),rLrnumpyrTscipy.linalg._matfuncs_sqrtmrrscipy.linalg._decomp_schurrrscipy.linalg._matfuncsr scipy.linalgrr scipy.sparse.linalg._interfacer scipy.sparse.linalgr scipy.specialr UserWarningr rrrrr r#r&rRrYrcrvryrrrrrrrrrrrrrs@5'29* k       %%  !6!6 :^:H27&HR$6N4n5p,^FR<$/ dL ^HV/d` F (.r