linalg.pyc
1 o 2 [��c�g � @ s0 d Z g d�ZddlZddlZddlZddlmZmZmZm Z m 3 Z 4 m Z m Z m Z mZmZmZmZmZmZmZmZmZmZmZmZmZmZm Z m Z m Z m Z m Z m!Z!m"Z"m#Z#m$Z$m%Z%m&Z&m'Z'm(Z(m)Z)m*Z*m+Z+m,Z,m-Z-m.Z.m/Z/ ddl0m1Z1 ddl2m3Z3 ddlm4Z4 ddl5m6Z6m7Z7 dd l8m9Z9 ej:e4j;d 5 d �Z;e Z<e3d 6 �G d d � d e=��Z>dd� Z?e?� Z@[?dd� ZAdd� ZBdd� ZCdd� ZDdd� ZEdd� ZFd d � ZGd d � ZHd d!� ZIe e e e ee ee iZJe ee eeeeeiZKe fd"d#�ZLefd$d%�ZMd&d'� ZNd(d)� ZOd*d+� ZPd,d-� ZQd.d/� ZRd0d1� ZSd2d3� ZTd4d5� ZUd�d6d7�ZVe;eV�d�d8d9��ZWd:d;� ZXe;eX�d<d=� �ZYd�d>d?�ZZe;eZ�d�dAdB��Z[dCdD� Z\e;e\�dEdF� �Z]dGdH� Z^e;e^�dIdJ� �Z_e;e\�dKdL� �Z`d�dMdN�Zae;ea�d�dPdQ��Zbe;e\�dRdS� �Zcd�dTdU�Zde;ed�d�dWdX��ZedYdZ� Zfe;e\�d[d\� �Zge;ed�d�d]d^��Zhd�d_d`�Zie;ei�d�dcdd��Zjd�dedf�Zke;ek�d�dgdh��Zld�didj�Zme;em�d�dkdl��Znd�dmdn�Zoe;eo�d�dpdq��Zpe;e\�drds� �Zqe;e\�dtdu� �Zrd�dvdw�Zse;es�d�dydz��Ztd{d|� Zud�d}d~�Zve;ev�d�dd���Zwdd��d�d��Zxe;ex�dd��d�d���Zyd�d�d��Zzd�d�d��Z{d�d�d��Z|dS )�ax Lite version of scipy.linalg. 7 8 Notes 9 ----- 10 This module is a lite version of the linalg.py module in SciPy which 11 contains high-level Python interface to the LAPACK library. The lite 12 version only accesses the following LAPACK functions: dgesv, zgesv, 13 dgeev, zgeev, dgesdd, zgesdd, dgelsd, zgelsd, dsyevd, zheevd, dgetrf, 14 zgetrf, dpotrf, zpotrf, dgeqrf, zgeqrf, zungqr, dorgqr. 15 )� matrix_power�solve� tensorsolve� tensorinv�inv�cholesky�eigvals�eigvalsh�pinv�slogdet�det�svd�eig�eigh�lstsq�norm�qr�cond� matrix_rank� LinAlgError� multi_dot� N)*�array�asarray�zeros�empty� 16 empty_like�intc�single�double�csingle�cdouble�inexact�complexfloating�newaxis�all�Inf�dot�add�multiply�sqrt�sum�isfinite�finfo�errstate� geterrobj�moveaxis�amin�amax�product�abs� 17 atleast_2d�intp� 18 asanyarray�object_�matmul�swapaxes�divide� count_nonzero�isnan�sign�argsort�sort� 19 reciprocal)�normalize_axis_index)� 20 set_module)� overrides)�triu�eye)� _umath_linalgz numpy.linalg)�modulec @ s e Zd ZdZdS )r a 21 Generic Python-exception-derived object raised by linalg functions. 22 23 General purpose exception class, derived from Python's exception.Exception 24 class, programmatically raised in linalg functions when a Linear 25 Algebra-related condition would prevent further correct execution of the 26 function. 27 28 Parameters 29 ---------- 30 None 31 32 Examples 33 -------- 34 >>> from numpy import linalg as LA 35 >>> LA.inv(np.zeros((2,2))) 36 Traceback (most recent call last): 37 File "<stdin>", line 1, in <module> 38 File "...linalg.py", line 350, 39 in inv return wrap(solve(a, identity(a.shape[0], dtype=a.dtype))) 40 File "...linalg.py", line 249, 41 in solve 42 raise LinAlgError('Singular matrix') 43 numpy.linalg.LinAlgError: Singular matrix 44 45 N)�__name__� 46 __module__� __qualname__�__doc__� rL rL ��C:\Users\Jacks.GUTTSPC\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.10_qbz5n2kfra8p0\LocalCache\local-packages\Python310\site-packages\numpy\linalg\linalg.pyr , s r c C sR t � } | d }tddddd�� t � d }W d � n1 s w Y ||d gS )Nr �call�ignore)�invalid�overr: �under� )r. r- )Zerrobj�bufsizeZinvalid_call_errmaskrL rL rM �_determine_error_statesJ s � � 47 rU c C � t d��)NzSingular matrix�r ��err�flagrL rL rM �_raise_linalgerror_singularX � r[ c C rV )Nz Matrix is not positive definiterW rX rL rL rM � _raise_linalgerror_nonposdef[ r\ r] c C rV )Nz Eigenvalues did not convergerW rX rL rL rM �-_raise_linalgerror_eigenvalues_nonconvergence^ r\ r^ c C rV )NzSVD did not convergerW rX rL rL rM �%_raise_linalgerror_svd_nonconvergencea r\ r_ c C rV )Nz,SVD did not converge in Linear Least SquaresrW rX rL rL rM �_raise_linalgerror_lstsqd r\ r` c C rV )Nz:Incorrect argument found while performing QR factorizationrW rX rL rL rM �_raise_linalgerror_qrg r\ ra c C s t t�}| |d< |S )N� )�list�_linalg_error_extobj)�callback�extobjrL rL rM �get_linalg_error_extobjk s rg c C s t | �}t| d|j�}||fS )N�__array_prepare__)r �getattr�__array_wrap__)�a�new�wraprL rL rM � 48 _makearrayp s rn c C s 49 t | t�S �N)� 50 issubclassr" )�trL rL rM � isComplexTypeu s 51 rr c C � t �| |�S ro )�_real_types_map�get�rq �defaultrL rL rM � _realType� � rx c C rs ro )�_complex_types_mapru rv rL rL rM � _complexType� ry r{ c G s� t }d}| D ]/}t|jjt�r-t|jj�rd}t|jjd d�}|d u r,td|jjf ��nt }|t u r5t }q|rBt 52 }t | }||fS t }||fS )NFT)rw z&array type %s is unsupported in linalg) r rp �dtype�typer! rr rx � TypeError�namer r rz )�arrays� result_type� 53 is_complexrk �rtrq rL rL rM � _commonType� s, ����r� c G sX g }| D ]}|j jdvr|�t||j �d�d�� q|�|� qt|�dkr*|d S |S )N)�=�|r� �r| rS r )r| � byteorder�appendr � newbyteorder�len)r� �ret�arrrL rL rM �_to_native_byte_order� s r� c G s& | D ]}|j dkrtd|j ��qd S )Nrb z9%d-dimensional array given. Array must be two-dimensional��ndimr �r� rk rL rL rM � 54 _assert_2d� � 55 ���r� c G s& | D ]}|j dk rtd|j ��qd S )Nrb zB%d-dimensional array given. Array must be at least two-dimensionalr� r� rL rL rM �_assert_stacked_2d� r� r� c G s0 | D ]}|j dd � \}}||krtd��qd S )N�����z-Last 2 dimensions of the array must be square)�shaper )r� rk �m�nrL rL rM �_assert_stacked_square� s ��r� c G s" | D ] }t |��� std��qd S )Nz#Array must not contain infs or NaNs)r+ r$ r r� rL rL rM �_assert_finite� s 56 ��r� c C s | j dkot| jdd � �dkS )Nr r� )�sizer2 r� )r� rL rL rM � _is_empty_2d� s r� c C s t | dd�S )a 57 Transpose each matrix in a stack of matrices. 58 59 Unlike np.transpose, this only swaps the last two axes, rather than all of 60 them 61 62 Parameters 63 ---------- 64 a : (...,M,N) array_like 65 66 Returns 67 ------- 68 aT : (...,N,M) ndarray 69 �����r� )r9 �rk rL rL rM � transpose� s r� c C � | |fS ro rL )rk �b�axesrL rL rM �_tensorsolve_dispatcher� r\ r� c 70 C s� t | �\} }t|�}| j}|dur-ttd|��}|D ] }|�|� |�||� q| �|�} | j||j d� }d}|D ]}||9 }q<| j |d krNt 71 d��| � ||�} |� � }|t | |��} || _| S )a 72 Solve the tensor equation ``a x = b`` for x. 73 74 It is assumed that all indices of `x` are summed over in the product, 75 together with the rightmost indices of `a`, as is done in, for example, 76 ``tensordot(a, x, axes=x.ndim)``. 77 78 Parameters 79 ---------- 80 a : array_like 81 Coefficient tensor, of shape ``b.shape + Q``. `Q`, a tuple, equals 82 the shape of that sub-tensor of `a` consisting of the appropriate 83 number of its rightmost indices, and must be such that 84 ``prod(Q) == prod(b.shape)`` (in which sense `a` is said to be 85 'square'). 86 b : array_like 87 Right-hand tensor, which can be of any shape. 88 axes : tuple of ints, optional 89 Axes in `a` to reorder to the right, before inversion. 90 If None (default), no reordering is done. 91 92 Returns 93 ------- 94 x : ndarray, shape Q 95 96 Raises 97 ------ 98 LinAlgError 99 If `a` is singular or not 'square' (in the above sense). 100 101 See Also 102 -------- 103 numpy.tensordot, tensorinv, numpy.einsum 104 105 Examples 106 -------- 107 >>> a = np.eye(2*3*4) 108 >>> a.shape = (2*3, 4, 2, 3, 4) 109 >>> b = np.random.randn(2*3, 4) 110 >>> x = np.linalg.tensorsolve(a, b) 111 >>> x.shape 112 (2, 3, 4) 113 >>> np.allclose(np.tensordot(a, x, axes=3), b) 114 True 115 116 Nr rS rb zfInput arrays must satisfy the requirement prod(a.shape[b.ndim:]) == prod(a.shape[:b.ndim]))rn r r� rc �range�remove�insertr� r� r� r �reshape�ravelr ) 117 rk r� r� rm �anZallaxes�k�oldshape�prod�resrL rL rM r � s, 0 118 119 120 � r c C r� ro rL )rk r� rL rL rM �_solve_dispatcher. r\ r� c 121 C s� t | �\} }t| � t| � t |�\}}t| |�\}}|j| jd kr'tj}ntj}t|�r0dnd}t t 122 �}|| |||d�} || j |dd��S )aC 123 Solve a linear matrix equation, or system of linear scalar equations. 124 125 Computes the "exact" solution, `x`, of the well-determined, i.e., full 126 rank, linear matrix equation `ax = b`. 127 128 Parameters 129 ---------- 130 a : (..., M, M) array_like 131 Coefficient matrix. 132 b : {(..., M,), (..., M, K)}, array_like 133 Ordinate or "dependent variable" values. 134 135 Returns 136 ------- 137 x : {(..., M,), (..., M, K)} ndarray 138 Solution to the system a x = b. Returned shape is identical to `b`. 139 140 Raises 141 ------ 142 LinAlgError 143 If `a` is singular or not square. 144 145 See Also 146 -------- 147 scipy.linalg.solve : Similar function in SciPy. 148 149 Notes 150 ----- 151 152 .. versionadded:: 1.8.0 153 154 Broadcasting rules apply, see the `numpy.linalg` documentation for 155 details. 156 157 The solutions are computed using LAPACK routine ``_gesv``. 158 159 `a` must be square and of full-rank, i.e., all rows (or, equivalently, 160 columns) must be linearly independent; if either is not true, use 161 `lstsq` for the least-squares best "solution" of the 162 system/equation. 163 164 References 165 ---------- 166 .. [1] G. Strang, *Linear Algebra and Its Applications*, 2nd Ed., Orlando, 167 FL, Academic Press, Inc., 1980, pg. 22. 168 169 Examples 170 -------- 171 Solve the system of equations ``x0 + 2 * x1 = 1`` and ``3 * x0 + 5 * x1 = 2``: 172 173 >>> a = np.array([[1, 2], [3, 5]]) 174 >>> b = np.array([1, 2]) 175 >>> x = np.linalg.solve(a, b) 176 >>> x 177 array([-1., 1.]) 178 179 Check that the solution is correct: 180 181 >>> np.allclose(np.dot(a, x), b) 182 True 183 184 rS �DD->D�dd->d�� signaturerf F��copy) rn r� r� r� r� rF �solve1r rr rg r[ �astype) 185 rk r� �_rm rq �result_t�gufuncr� rf �rrL rL rM r 2 s A r c C � | fS ro rL )rk �indrL rL rM �_tensorinv_dispatcher� � r� rb c C st t | �} | j}d}|dkr'||d� |d|� }||d� D ]}||9 }q ntd��| �|d�} t| �}|j|� S )a� 186 Compute the 'inverse' of an N-dimensional array. 187 188 The result is an inverse for `a` relative to the tensordot operation 189 ``tensordot(a, b, ind)``, i. e., up to floating-point accuracy, 190 ``tensordot(tensorinv(a), a, ind)`` is the "identity" tensor for the 191 tensordot operation. 192 193 Parameters 194 ---------- 195 a : array_like 196 Tensor to 'invert'. Its shape must be 'square', i. e., 197 ``prod(a.shape[:ind]) == prod(a.shape[ind:])``. 198 ind : int, optional 199 Number of first indices that are involved in the inverse sum. 200 Must be a positive integer, default is 2. 201 202 Returns 203 ------- 204 b : ndarray 205 `a`'s tensordot inverse, shape ``a.shape[ind:] + a.shape[:ind]``. 206 207 Raises 208 ------ 209 LinAlgError 210 If `a` is singular or not 'square' (in the above sense). 211 212 See Also 213 -------- 214 numpy.tensordot, tensorsolve 215 216 Examples 217 -------- 218 >>> a = np.eye(4*6) 219 >>> a.shape = (4, 6, 8, 3) 220 >>> ainv = np.linalg.tensorinv(a, ind=2) 221 >>> ainv.shape 222 (8, 3, 4, 6) 223 >>> b = np.random.randn(4, 6) 224 >>> np.allclose(np.tensordot(ainv, b), np.linalg.tensorsolve(a, b)) 225 True 226 227 >>> a = np.eye(4*6) 228 >>> a.shape = (24, 8, 3) 229 >>> ainv = np.linalg.tensorinv(a, ind=1) 230 >>> ainv.shape 231 (8, 3, 24) 232 >>> b = np.random.randn(24) 233 >>> np.allclose(np.tensordot(ainv, b, 1), np.linalg.tensorsolve(a, b)) 234 True 235 236 rS r NzInvalid ind argument.r� )r r� � 237 ValueErrorr� r )rk r� r� r� Zinvshaper� �iarL rL rM r � s 6 238 � 239 r c C r� ro rL r� rL rL rM �_unary_dispatcher� r� r� c C sb t | �\} }t| � t| � t| �\}}t|�rdnd}tt�}tj| ||d�}||j |dd��S )aS 240 Compute the (multiplicative) inverse of a matrix. 241 242 Given a square matrix `a`, return the matrix `ainv` satisfying 243 ``dot(a, ainv) = dot(ainv, a) = eye(a.shape[0])``. 244 245 Parameters 246 ---------- 247 a : (..., M, M) array_like 248 Matrix to be inverted. 249 250 Returns 251 ------- 252 ainv : (..., M, M) ndarray or matrix 253 (Multiplicative) inverse of the matrix `a`. 254 255 Raises 256 ------ 257 LinAlgError 258 If `a` is not square or inversion fails. 259 260 See Also 261 -------- 262 scipy.linalg.inv : Similar function in SciPy. 263 264 Notes 265 ----- 266 267 .. versionadded:: 1.8.0 268 269 Broadcasting rules apply, see the `numpy.linalg` documentation for 270 details. 271 272 Examples 273 -------- 274 >>> from numpy.linalg import inv 275 >>> a = np.array([[1., 2.], [3., 4.]]) 276 >>> ainv = inv(a) 277 >>> np.allclose(np.dot(a, ainv), np.eye(2)) 278 True 279 >>> np.allclose(np.dot(ainv, a), np.eye(2)) 280 True 281 282 If a is a matrix object, then the return value is a matrix as well: 283 284 >>> ainv = inv(np.matrix(a)) 285 >>> ainv 286 matrix([[-2. , 1. ], 287 [ 1.5, -0.5]]) 288 289 Inverses of several matrices can be computed at once: 290 291 >>> a = np.array([[[1., 2.], [3., 4.]], [[1, 3], [3, 5]]]) 292 >>> inv(a) 293 array([[[-2. , 1. ], 294 [ 1.5 , -0.5 ]], 295 [[-1.25, 0.75], 296 [ 0.75, -0.25]]]) 297 298 �D->D�d->dr� Fr� ) 299 rn r� r� r� rr rg r[ rF r r� )rk rm rq r� r� rf �ainvrL rL rM r � s > r c C r� ro rL )rk r� rL rL rM �_matrix_power_dispatcher r� r� c 300 C sF t | �} t| � t| � zt�|�}W n ty$ } ztd�|�d}~ww | jtkr-t}n | j dkr5t 301 }nt d��|dkrOt | �} t | jd | jd�| d< | S |dk r[t| �} t|�}|d kra| S |dkrj|| | �S |d 302 krv||| | �| �S d }}|dkr�|du r�| n|||�}t|d�\}}|r�|du r�|n|||�}|dks~|S ) a� 303 Raise a square matrix to the (integer) power `n`. 304 305 For positive integers `n`, the power is computed by repeated matrix 306 squarings and matrix multiplications. If ``n == 0``, the identity matrix 307 of the same shape as M is returned. If ``n < 0``, the inverse 308 is computed and then raised to the ``abs(n)``. 309 310 .. note:: Stacks of object matrices are not currently supported. 311 312 Parameters 313 ---------- 314 a : (..., M, M) array_like 315 Matrix to be "powered". 316 n : int 317 The exponent can be any integer or long integer, positive, 318 negative, or zero. 319 320 Returns 321 ------- 322 a**n : (..., M, M) ndarray or matrix object 323 The return value is the same shape and type as `M`; 324 if the exponent is positive or zero then the type of the 325 elements is the same as those of `M`. If the exponent is 326 negative the elements are floating-point. 327 328 Raises 329 ------ 330 LinAlgError 331 For matrices that are not square or that (for negative powers) cannot 332 be inverted numerically. 333 334 Examples 335 -------- 336 >>> from numpy.linalg import matrix_power 337 >>> i = np.array([[0, 1], [-1, 0]]) # matrix equiv. of the imaginary unit 338 >>> matrix_power(i, 3) # should = -i 339 array([[ 0, -1], 340 [ 1, 0]]) 341 >>> matrix_power(i, 0) 342 array([[1, 0], 343 [0, 1]]) 344 >>> matrix_power(i, -3) # should = 1/(-i) = i, but w/ f.p. elements 345 array([[ 0., 1.], 346 [-1., 0.]]) 347 348 Somewhat more sophisticated example 349 350 >>> q = np.zeros((4, 4)) 351 >>> q[0:2, 0:2] = -i 352 >>> q[2:4, 2:4] = i 353 >>> q # one of the three quaternion units not equal to 1 354 array([[ 0., -1., 0., 0.], 355 [ 1., 0., 0., 0.], 356 [ 0., 0., 0., 1.], 357 [ 0., 0., -1., 0.]]) 358 >>> matrix_power(q, 2) # = -np.eye(4) 359 array([[-1., 0., 0., 0.], 360 [ 0., -1., 0., 0.], 361 [ 0., 0., -1., 0.], 362 [ 0., 0., 0., -1.]]) 363 364 zexponent must be an integerNrb z6matrix_power not supported for stacks of object arraysr r� r� .rS � )r6 r� r� �operator�indexr~ r| �objectr8 r� r& �NotImplementedErrorr rE r� r r3 �divmod)rk r� �eZfmatmul�z�result�bitrL rL rM r " sJ A 365 �� 366 367 � 368 �r c C sf t t�}tj}t| �\} }t| � t| � t| �\}}t|�r!dnd}|| ||d�}||j |dd��S )a� 369 Cholesky decomposition. 370 371 Return the Cholesky decomposition, `L * L.H`, of the square matrix `a`, 372 where `L` is lower-triangular and .H is the conjugate transpose operator 373 (which is the ordinary transpose if `a` is real-valued). `a` must be 374 Hermitian (symmetric if real-valued) and positive-definite. No 375 checking is performed to verify whether `a` is Hermitian or not. 376 In addition, only the lower-triangular and diagonal elements of `a` 377 are used. Only `L` is actually returned. 378 379 Parameters 380 ---------- 381 a : (..., M, M) array_like 382 Hermitian (symmetric if all elements are real), positive-definite 383 input matrix. 384 385 Returns 386 ------- 387 L : (..., M, M) array_like 388 Lower-triangular Cholesky factor of `a`. Returns a matrix object if 389 `a` is a matrix object. 390 391 Raises 392 ------ 393 LinAlgError 394 If the decomposition fails, for example, if `a` is not 395 positive-definite. 396 397 See Also 398 -------- 399 scipy.linalg.cholesky : Similar function in SciPy. 400 scipy.linalg.cholesky_banded : Cholesky decompose a banded Hermitian 401 positive-definite matrix. 402 scipy.linalg.cho_factor : Cholesky decomposition of a matrix, to use in 403 `scipy.linalg.cho_solve`. 404 405 Notes 406 ----- 407 408 .. versionadded:: 1.8.0 409 410 Broadcasting rules apply, see the `numpy.linalg` documentation for 411 details. 412 413 The Cholesky decomposition is often used as a fast way of solving 414 415 .. math:: A \mathbf{x} = \mathbf{b} 416 417 (when `A` is both Hermitian/symmetric and positive-definite). 418 419 First, we solve for :math:`\mathbf{y}` in 420 421 .. math:: L \mathbf{y} = \mathbf{b}, 422 423 and then for :math:`\mathbf{x}` in 424 425 .. math:: L.H \mathbf{x} = \mathbf{y}. 426 427 Examples 428 -------- 429 >>> A = np.array([[1,-2j],[2j,5]]) 430 >>> A 431 array([[ 1.+0.j, -0.-2.j], 432 [ 0.+2.j, 5.+0.j]]) 433 >>> L = np.linalg.cholesky(A) 434 >>> L 435 array([[1.+0.j, 0.+0.j], 436 [0.+2.j, 1.+0.j]]) 437 >>> np.dot(L, L.T.conj()) # verify that L * L.H = A 438 array([[1.+0.j, 0.-2.j], 439 [0.+2.j, 5.+0.j]]) 440 >>> A = [[1,-2j],[2j,5]] # what happens if A is only array_like? 441 >>> np.linalg.cholesky(A) # an ndarray object is returned 442 array([[1.+0.j, 0.+0.j], 443 [0.+2.j, 1.+0.j]]) 444 >>> # But a matrix object is returned if A is a matrix object 445 >>> np.linalg.cholesky(np.matrix(A)) 446 matrix([[ 1.+0.j, 0.+0.j], 447 [ 0.+2.j, 1.+0.j]]) 448 449 r� r� r� Fr� ) 450 rg r] rF Z cholesky_lorn r� r� r� rr r� )rk rf r� rm rq r� r� r� rL rL rM r � s T r c C r� ro rL )rk �moderL rL rM �_qr_dispatcher� r� r� �reducedc C s |dvr1|dv rd� d�}tj|tdd� d}n|dv r)d }tj|tdd� d 451 }ntd |� d ���t| �\} }t| � | jd d� \}}t| �\}}| j |dd�} t 452 | �} t ||�}||krbt j } nt j} t|�rkdnd} 453 tt�} | | | 454 | d�} |dkr�t| dd|�dd�f �} | j |dd�} || �S |dkr�t| �}|j |dd�}| j |dd�} ||�| fS |d 455 kr�| j |dd�} || �S |dkr�||kr�|}t j} n|}t j} t|�r�dnd} 456 tt�} | | | | 457 | d�}t| dd|�dd�f �} |j |dd�}| j |dd�} ||�|| �fS )a� 458 Compute the qr factorization of a matrix. 459 460 Factor the matrix `a` as *qr*, where `q` is orthonormal and `r` is 461 upper-triangular. 462 463 Parameters 464 ---------- 465 a : array_like, shape (..., M, N) 466 An array-like object with the dimensionality of at least 2. 467 mode : {'reduced', 'complete', 'r', 'raw'}, optional 468 If K = min(M, N), then 469 470 * 'reduced' : returns q, r with dimensions 471 (..., M, K), (..., K, N) (default) 472 * 'complete' : returns q, r with dimensions (..., M, M), (..., M, N) 473 * 'r' : returns r only with dimensions (..., K, N) 474 * 'raw' : returns h, tau with dimensions (..., N, M), (..., K,) 475 476 The options 'reduced', 'complete, and 'raw' are new in numpy 1.8, 477 see the notes for more information. The default is 'reduced', and to 478 maintain backward compatibility with earlier versions of numpy both 479 it and the old default 'full' can be omitted. Note that array h 480 returned in 'raw' mode is transposed for calling Fortran. The 481 'economic' mode is deprecated. The modes 'full' and 'economic' may 482 be passed using only the first letter for backwards compatibility, 483 but all others must be spelled out. See the Notes for more 484 explanation. 485 486 487 Returns 488 ------- 489 q : ndarray of float or complex, optional 490 A matrix with orthonormal columns. When mode = 'complete' the 491 result is an orthogonal/unitary matrix depending on whether or not 492 a is real/complex. The determinant may be either +/- 1 in that 493 case. In case the number of dimensions in the input array is 494 greater than 2 then a stack of the matrices with above properties 495 is returned. 496 r : ndarray of float or complex, optional 497 The upper-triangular matrix or a stack of upper-triangular 498 matrices if the number of dimensions in the input array is greater 499 than 2. 500 (h, tau) : ndarrays of np.double or np.cdouble, optional 501 The array h contains the Householder reflectors that generate q 502 along with r. The tau array contains scaling factors for the 503 reflectors. In the deprecated 'economic' mode only h is returned. 504 505 Raises 506 ------ 507 LinAlgError 508 If factoring fails. 509 510 See Also 511 -------- 512 scipy.linalg.qr : Similar function in SciPy. 513 scipy.linalg.rq : Compute RQ decomposition of a matrix. 514 515 Notes 516 ----- 517 This is an interface to the LAPACK routines ``dgeqrf``, ``zgeqrf``, 518 ``dorgqr``, and ``zungqr``. 519 520 For more information on the qr factorization, see for example: 521 https://en.wikipedia.org/wiki/QR_factorization 522 523 Subclasses of `ndarray` are preserved except for the 'raw' mode. So if 524 `a` is of type `matrix`, all the return values will be matrices too. 525 526 New 'reduced', 'complete', and 'raw' options for mode were added in 527 NumPy 1.8.0 and the old option 'full' was made an alias of 'reduced'. In 528 addition the options 'full' and 'economic' were deprecated. Because 529 'full' was the previous default and 'reduced' is the new default, 530 backward compatibility can be maintained by letting `mode` default. 531 The 'raw' option was added so that LAPACK routines that can multiply 532 arrays by q using the Householder reflectors can be used. Note that in 533 this case the returned arrays are of type np.double or np.cdouble and 534 the h array is transposed to be FORTRAN compatible. No routines using 535 the 'raw' return are currently exposed by numpy, but some are available 536 in lapack_lite and just await the necessary work. 537 538 Examples 539 -------- 540 >>> a = np.random.randn(9, 6) 541 >>> q, r = np.linalg.qr(a) 542 >>> np.allclose(a, np.dot(q, r)) # a does equal qr 543 True 544 >>> r2 = np.linalg.qr(a, mode='r') 545 >>> np.allclose(r, r2) # mode='r' returns the same r as mode='full' 546 True 547 >>> a = np.random.normal(size=(3, 2, 2)) # Stack of 2 x 2 matrices as input 548 >>> q, r = np.linalg.qr(a) 549 >>> q.shape 550 (3, 2, 2) 551 >>> r.shape 552 (3, 2, 2) 553 >>> np.allclose(a, np.matmul(q, r)) 554 True 555 556 Example illustrating a common use of `qr`: solving of least squares 557 problems 558 559 What are the least-squares-best `m` and `y0` in ``y = y0 + mx`` for 560 the following data: {(0,1), (1,0), (1,2), (2,1)}. (Graph the points 561 and you'll see that it should be y0 = 0, m = 1.) The answer is provided 562 by solving the over-determined matrix equation ``Ax = b``, where:: 563 564 A = array([[0, 1], [1, 1], [1, 1], [2, 1]]) 565 x = array([[y0], [m]]) 566 b = array([[1], [0], [2], [1]]) 567 568 If A = qr such that q is orthonormal (which is always possible via 569 Gram-Schmidt), then ``x = inv(r) * (q.T) * b``. (In numpy practice, 570 however, we simply use `lstsq`.) 571 572 >>> A = np.array([[0, 1], [1, 1], [1, 1], [2, 1]]) 573 >>> A 574 array([[0, 1], 575 [1, 1], 576 [1, 1], 577 [2, 1]]) 578 >>> b = np.array([1, 2, 2, 3]) 579 >>> q, r = np.linalg.qr(A) 580 >>> p = np.dot(q.T, b) 581 >>> np.dot(np.linalg.inv(r), p) 582 array([ 1., 1.]) 583 584 )r� �completer� �raw)�f�full� )z7The 'full' option is deprecated in favor of 'reduced'. 585 z,For backward compatibility let mode default.r� �� 586 stacklevelr� )r� �economicz$The 'economic' option is deprecated.r� zUnrecognized mode '�'r� NTr� r� r� r� r� .Fr� r� r� r� )�join�warnings�warn�DeprecationWarningr� rn r� r� r� r� r� �minrF Z 587 qr_r_raw_mZ 588 qr_r_raw_nrr rg ra rD r� Z qr_completeZ 589 qr_reduced)rk r� �msgrm r� r� rq r� �mnr� r� rf �taur� �q�mcrL rL rM r � s` 590 591 r c C s� t | �\} }t| � t| � t| � t| �\}}tt�}t|�r"dnd}tj | ||d�}t|�sCt 592 |j dk�r?|j }t |�}nt|�}|j|dd�S )ai 593 Compute the eigenvalues of a general matrix. 594 595 Main difference between `eigvals` and `eig`: the eigenvectors aren't 596 returned. 597 598 Parameters 599 ---------- 600 a : (..., M, M) array_like 601 A complex- or real-valued matrix whose eigenvalues will be computed. 602 603 Returns 604 ------- 605 w : (..., M,) ndarray 606 The eigenvalues, each repeated according to its multiplicity. 607 They are not necessarily ordered, nor are they necessarily 608 real for real matrices. 609 610 Raises 611 ------ 612 LinAlgError 613 If the eigenvalue computation does not converge. 614 615 See Also 616 -------- 617 eig : eigenvalues and right eigenvectors of general arrays 618 eigvalsh : eigenvalues of real symmetric or complex Hermitian 619 (conjugate symmetric) arrays. 620 eigh : eigenvalues and eigenvectors of real symmetric or complex 621 Hermitian (conjugate symmetric) arrays. 622 scipy.linalg.eigvals : Similar function in SciPy. 623 624 Notes 625 ----- 626 627 .. versionadded:: 1.8.0 628 629 Broadcasting rules apply, see the `numpy.linalg` documentation for 630 details. 631 632 This is implemented using the ``_geev`` LAPACK routines which compute 633 the eigenvalues and eigenvectors of general square arrays. 634 635 Examples 636 -------- 637 Illustration, using the fact that the eigenvalues of a diagonal matrix 638 are its diagonal elements, that multiplying a matrix on the left 639 by an orthogonal matrix, `Q`, and on the right by `Q.T` (the transpose 640 of `Q`), preserves the eigenvalues of the "middle" matrix. In other words, 641 if `Q` is orthogonal, then ``Q * A * Q.T`` has the same eigenvalues as 642 ``A``: 643 644 >>> from numpy import linalg as LA 645 >>> x = np.random.random() 646 >>> Q = np.array([[np.cos(x), -np.sin(x)], [np.sin(x), np.cos(x)]]) 647 >>> LA.norm(Q[0, :]), LA.norm(Q[1, :]), np.dot(Q[0, :],Q[1, :]) 648 (1.0, 1.0, 0.0) 649 650 Now multiply a diagonal matrix by ``Q`` on one side and by ``Q.T`` on the other: 651 652 >>> D = np.diag((-1,1)) 653 >>> LA.eigvals(D) 654 array([-1., 1.]) 655 >>> A = np.dot(Q, D) 656 >>> A = np.dot(A, Q.T) 657 >>> LA.eigvals(A) 658 array([ 1., -1.]) # random 659 660 r� zd->Dr� r Fr� )rn r� r� r� r� rg r^ rr rF r r$ �imag�realrx r{ r� )rk rm rq r� rf r� �wrL rL rM r � s G � 661 r c C r� ro rL )rk �UPLOrL rL rM �_eigvalsh_dispatcher% r� r� �Lc C s� |� � }|dvr td��tt�}|dkrtj}ntj}t| �\} }t| � t | � t 662 | �\}}t |�r5dnd}|| ||d�}|j t |�dd�S ) a� 663 Compute the eigenvalues of a complex Hermitian or real symmetric matrix. 664 665 Main difference from eigh: the eigenvectors are not computed. 666 667 Parameters 668 ---------- 669 a : (..., M, M) array_like 670 A complex- or real-valued matrix whose eigenvalues are to be 671 computed. 672 UPLO : {'L', 'U'}, optional 673 Specifies whether the calculation is done with the lower triangular 674 part of `a` ('L', default) or the upper triangular part ('U'). 675 Irrespective of this value only the real parts of the diagonal will 676 be considered in the computation to preserve the notion of a Hermitian 677 matrix. It therefore follows that the imaginary part of the diagonal 678 will always be treated as zero. 679 680 Returns 681 ------- 682 w : (..., M,) ndarray 683 The eigenvalues in ascending order, each repeated according to 684 its multiplicity. 685 686 Raises 687 ------ 688 LinAlgError 689 If the eigenvalue computation does not converge. 690 691 See Also 692 -------- 693 eigh : eigenvalues and eigenvectors of real symmetric or complex Hermitian 694 (conjugate symmetric) arrays. 695 eigvals : eigenvalues of general real or complex arrays. 696 eig : eigenvalues and right eigenvectors of general real or complex 697 arrays. 698 scipy.linalg.eigvalsh : Similar function in SciPy. 699 700 Notes 701 ----- 702 703 .. versionadded:: 1.8.0 704 705 Broadcasting rules apply, see the `numpy.linalg` documentation for 706 details. 707 708 The eigenvalues are computed using LAPACK routines ``_syevd``, ``_heevd``. 709 710 Examples 711 -------- 712 >>> from numpy import linalg as LA 713 >>> a = np.array([[1, -2j], [2j, 5]]) 714 >>> LA.eigvalsh(a) 715 array([ 0.17157288, 5.82842712]) # may vary 716 717 >>> # demonstrate the treatment of the imaginary part of the diagonal 718 >>> a = np.array([[5+2j, 9-2j], [0+2j, 2-1j]]) 719 >>> a 720 array([[5.+2.j, 9.-2.j], 721 [0.+2.j, 2.-1.j]]) 722 >>> # with UPLO='L' this is numerically equivalent to using LA.eigvals() 723 >>> # with: 724 >>> b = np.array([[5.+0.j, 0.-2.j], [0.+2.j, 2.-0.j]]) 725 >>> b 726 array([[5.+0.j, 0.-2.j], 727 [0.+2.j, 2.+0.j]]) 728 >>> wa = LA.eigvalsh(a) 729 >>> wb = LA.eigvals(b) 730 >>> wa; wb 731 array([1., 6.]) 732 array([6.+0.j, 1.+0.j]) 733 734 �r� �U� UPLO argument must be 'L' or 'U'r� �D->dr� r� Fr� )�upperr� rg r^ rF Z eigvalsh_loZ eigvalsh_uprn r� r� r� rr r� rx ) rk r� rf r� rm rq r� r� r� rL rL rM r ) s K� r c C s& t | �\}}| �|�j�� } | ||fS ro )r� r� �Tr� )rk rq r� rL rL rM � _convertarray� s 735 r� c C s� t | �\} }t| � t| � t| � t| �\}}tt�}t|�r"dnd}tj | ||d�\}}t|�sDt 736 |j dk�rD|j }|j }t |�}nt|�}|j|dd�}|j|dd�||�fS )a� 737 Compute the eigenvalues and right eigenvectors of a square array. 738 739 Parameters 740 ---------- 741 a : (..., M, M) array 742 Matrices for which the eigenvalues and right eigenvectors will 743 be computed 744 745 Returns 746 ------- 747 w : (..., M) array 748 The eigenvalues, each repeated according to its multiplicity. 749 The eigenvalues are not necessarily ordered. The resulting 750 array will be of complex type, unless the imaginary part is 751 zero in which case it will be cast to a real type. When `a` 752 is real the resulting eigenvalues will be real (0 imaginary 753 part) or occur in conjugate pairs 754 755 v : (..., M, M) array 756 The normalized (unit "length") eigenvectors, such that the 757 column ``v[:,i]`` is the eigenvector corresponding to the 758 eigenvalue ``w[i]``. 759 760 Raises 761 ------ 762 LinAlgError 763 If the eigenvalue computation does not converge. 764 765 See Also 766 -------- 767 eigvals : eigenvalues of a non-symmetric array. 768 eigh : eigenvalues and eigenvectors of a real symmetric or complex 769 Hermitian (conjugate symmetric) array. 770 eigvalsh : eigenvalues of a real symmetric or complex Hermitian 771 (conjugate symmetric) array. 772 scipy.linalg.eig : Similar function in SciPy that also solves the 773 generalized eigenvalue problem. 774 scipy.linalg.schur : Best choice for unitary and other non-Hermitian 775 normal matrices. 776 777 Notes 778 ----- 779 780 .. versionadded:: 1.8.0 781 782 Broadcasting rules apply, see the `numpy.linalg` documentation for 783 details. 784 785 This is implemented using the ``_geev`` LAPACK routines which compute 786 the eigenvalues and eigenvectors of general square arrays. 787 788 The number `w` is an eigenvalue of `a` if there exists a vector 789 `v` such that ``a @ v = w * v``. Thus, the arrays `a`, `w`, and 790 `v` satisfy the equations ``a @ v[:,i] = w[i] * v[:,i]`` 791 for :math:`i \in \{0,...,M-1\}`. 792 793 The array `v` of eigenvectors may not be of maximum rank, that is, some 794 of the columns may be linearly dependent, although round-off error may 795 obscure that fact. If the eigenvalues are all different, then theoretically 796 the eigenvectors are linearly independent and `a` can be diagonalized by 797 a similarity transformation using `v`, i.e, ``inv(v) @ a @ v`` is diagonal. 798 799 For non-Hermitian normal matrices the SciPy function `scipy.linalg.schur` 800 is preferred because the matrix `v` is guaranteed to be unitary, which is 801 not the case when using `eig`. The Schur factorization produces an 802 upper triangular matrix rather than a diagonal matrix, but for normal 803 matrices only the diagonal of the upper triangular matrix is needed, the 804 rest is roundoff error. 805 806 Finally, it is emphasized that `v` consists of the *right* (as in 807 right-hand side) eigenvectors of `a`. A vector `y` satisfying 808 ``y.T @ a = z * y.T`` for some number `z` is called a *left* 809 eigenvector of `a`, and, in general, the left and right eigenvectors 810 of a matrix are not necessarily the (perhaps conjugate) transposes 811 of each other. 812 813 References 814 ---------- 815 G. Strang, *Linear Algebra and Its Applications*, 2nd Ed., Orlando, FL, 816 Academic Press, Inc., 1980, Various pp. 817 818 Examples 819 -------- 820 >>> from numpy import linalg as LA 821 822 (Almost) trivial example with real e-values and e-vectors. 823 824 >>> w, v = LA.eig(np.diag((1, 2, 3))) 825 >>> w; v 826 array([1., 2., 3.]) 827 array([[1., 0., 0.], 828 [0., 1., 0.], 829 [0., 0., 1.]]) 830 831 Real matrix possessing complex e-values and e-vectors; note that the 832 e-values are complex conjugates of each other. 833 834 >>> w, v = LA.eig(np.array([[1, -1], [1, 1]])) 835 >>> w; v 836 array([1.+1.j, 1.-1.j]) 837 array([[0.70710678+0.j , 0.70710678-0.j ], 838 [0. -0.70710678j, 0. +0.70710678j]]) 839 840 Complex-valued matrix with real e-values (but complex-valued e-vectors); 841 note that ``a.conj().T == a``, i.e., `a` is Hermitian. 842 843 >>> a = np.array([[1, 1j], [-1j, 1]]) 844 >>> w, v = LA.eig(a) 845 >>> w; v 846 array([2.+0.j, 0.+0.j]) 847 array([[ 0. +0.70710678j, 0.70710678+0.j ], # may vary 848 [ 0.70710678+0.j , -0. +0.70710678j]]) 849 850 Be careful about round-off error! 851 852 >>> a = np.array([[1 + 1e-9, 0], [0, 1 - 1e-9]]) 853 >>> # Theor. e-values are 1 +/- 1e-9 854 >>> w, v = LA.eig(a) 855 >>> w; v 856 array([1., 1.]) 857 array([[1., 0.], 858 [0., 1.]]) 859 860 zD->DDzd->DDr� g Fr� )rn r� r� r� r� rg r^ rr rF r r$ r� r� rx r{ r� )rk rm rq r� rf r� r� �vtrL rL rM r � s" � 861 r c 862 C s� |� � }|dvr td��t| �\} }t| � t| � t| �\}}tt�}|dkr,tj }ntj 863 }t |�r5dnd}|| ||d�\}} |j t |�dd�}| j |dd�} ||| �fS ) aw 864 Return the eigenvalues and eigenvectors of a complex Hermitian 865 (conjugate symmetric) or a real symmetric matrix. 866 867 Returns two objects, a 1-D array containing the eigenvalues of `a`, and 868 a 2-D square array or matrix (depending on the input type) of the 869 corresponding eigenvectors (in columns). 870 871 Parameters 872 ---------- 873 a : (..., M, M) array 874 Hermitian or real symmetric matrices whose eigenvalues and 875 eigenvectors are to be computed. 876 UPLO : {'L', 'U'}, optional 877 Specifies whether the calculation is done with the lower triangular 878 part of `a` ('L', default) or the upper triangular part ('U'). 879 Irrespective of this value only the real parts of the diagonal will 880 be considered in the computation to preserve the notion of a Hermitian 881 matrix. It therefore follows that the imaginary part of the diagonal 882 will always be treated as zero. 883 884 Returns 885 ------- 886 w : (..., M) ndarray 887 The eigenvalues in ascending order, each repeated according to 888 its multiplicity. 889 v : {(..., M, M) ndarray, (..., M, M) matrix} 890 The column ``v[:, i]`` is the normalized eigenvector corresponding 891 to the eigenvalue ``w[i]``. Will return a matrix object if `a` is 892 a matrix object. 893 894 Raises 895 ------ 896 LinAlgError 897 If the eigenvalue computation does not converge. 898 899 See Also 900 -------- 901 eigvalsh : eigenvalues of real symmetric or complex Hermitian 902 (conjugate symmetric) arrays. 903 eig : eigenvalues and right eigenvectors for non-symmetric arrays. 904 eigvals : eigenvalues of non-symmetric arrays. 905 scipy.linalg.eigh : Similar function in SciPy (but also solves the 906 generalized eigenvalue problem). 907 908 Notes 909 ----- 910 911 .. versionadded:: 1.8.0 912 913 Broadcasting rules apply, see the `numpy.linalg` documentation for 914 details. 915 916 The eigenvalues/eigenvectors are computed using LAPACK routines ``_syevd``, 917 ``_heevd``. 918 919 The eigenvalues of real symmetric or complex Hermitian matrices are 920 always real. [1]_ The array `v` of (column) eigenvectors is unitary 921 and `a`, `w`, and `v` satisfy the equations 922 ``dot(a, v[:, i]) = w[i] * v[:, i]``. 923 924 References 925 ---------- 926 .. [1] G. Strang, *Linear Algebra and Its Applications*, 2nd Ed., Orlando, 927 FL, Academic Press, Inc., 1980, pg. 222. 928 929 Examples 930 -------- 931 >>> from numpy import linalg as LA 932 >>> a = np.array([[1, -2j], [2j, 5]]) 933 >>> a 934 array([[ 1.+0.j, -0.-2.j], 935 [ 0.+2.j, 5.+0.j]]) 936 >>> w, v = LA.eigh(a) 937 >>> w; v 938 array([0.17157288, 5.82842712]) 939 array([[-0.92387953+0.j , -0.38268343+0.j ], # may vary 940 [ 0. +0.38268343j, 0. -0.92387953j]]) 941 942 >>> np.dot(a, v[:, 0]) - w[0] * v[:, 0] # verify 1st e-val/vec pair 943 array([5.55111512e-17+0.0000000e+00j, 0.00000000e+00+1.2490009e-16j]) 944 >>> np.dot(a, v[:, 1]) - w[1] * v[:, 1] # verify 2nd e-val/vec pair 945 array([0.+0.j, 0.+0.j]) 946 947 >>> A = np.matrix(a) # what happens if input is a matrix object 948 >>> A 949 matrix([[ 1.+0.j, -0.-2.j], 950 [ 0.+2.j, 5.+0.j]]) 951 >>> w, v = LA.eigh(A) 952 >>> w; v 953 array([0.17157288, 5.82842712]) 954 matrix([[-0.92387953+0.j , -0.38268343+0.j ], # may vary 955 [ 0. +0.38268343j, 0. -0.92387953j]]) 956 957 >>> # demonstrate the treatment of the imaginary part of the diagonal 958 >>> a = np.array([[5+2j, 9-2j], [0+2j, 2-1j]]) 959 >>> a 960 array([[5.+2.j, 9.-2.j], 961 [0.+2.j, 2.-1.j]]) 962 >>> # with UPLO='L' this is numerically equivalent to using LA.eig() with: 963 >>> b = np.array([[5.+0.j, 0.-2.j], [0.+2.j, 2.-0.j]]) 964 >>> b 965 array([[5.+0.j, 0.-2.j], 966 [0.+2.j, 2.+0.j]]) 967 >>> wa, va = LA.eigh(a) 968 >>> wb, vb = LA.eig(b) 969 >>> wa; wb 970 array([1., 6.]) 971 array([6.+0.j, 1.+0.j]) 972 >>> va; vb 973 array([[-0.4472136 +0.j , -0.89442719+0.j ], # may vary 974 [ 0. +0.89442719j, 0. -0.4472136j ]]) 975 array([[ 0.89442719+0.j , -0. +0.4472136j], 976 [-0. +0.4472136j, 0.89442719+0.j ]]) 977 r� r� r� zD->dD�d->ddr� Fr� )r� r� rn r� r� r� rg r^ rF Zeigh_loZeigh_uprr r� rx ) 978 rk r� rm rq r� rf r� r� r� r� rL rL rM r % s$ u � r c C r� ro rL )rk � full_matrices� 979 compute_uv� hermitianrL rL rM �_svd_dispatcher� r� r� TFc C s� ddl }t| �\} }|rq|r^t| �\}}t|�}t|�}t|�dddd�f } |j|| dd�}|j|| dd�}|j|| dddd�f dd�}t||dddd�f ��� } 980 ||�||| 981 �fS t | �}t|�}t 982 |�dddd�f S t | � t | �\} } t t�} | jdd� \}}|r�|r�||k r�tj}ntj}n ||k r�tj}ntj}t| �r�dnd}|| || d �\}}}|j| d 983 d �}|jt| �d 984 d �}|j| d 985 d �}||�|||�fS ||k r�tj}ntj}t| �r�d nd }|| || d �}|jt| �d 986 d �}|S )a- 987 Singular Value Decomposition. 988 989 When `a` is a 2D array, and ``full_matrices=False``, then it is 990 factorized as ``u @ np.diag(s) @ vh = (u * s) @ vh``, where 991 `u` and the Hermitian transpose of `vh` are 2D arrays with 992 orthonormal columns and `s` is a 1D array of `a`'s singular 993 values. When `a` is higher-dimensional, SVD is applied in 994 stacked mode as explained below. 995 996 Parameters 997 ---------- 998 a : (..., M, N) array_like 999 A real or complex array with ``a.ndim >= 2``. 1000 full_matrices : bool, optional 1001 If True (default), `u` and `vh` have the shapes ``(..., M, M)`` and 1002 ``(..., N, N)``, respectively. Otherwise, the shapes are 1003 ``(..., M, K)`` and ``(..., K, N)``, respectively, where 1004 ``K = min(M, N)``. 1005 compute_uv : bool, optional 1006 Whether or not to compute `u` and `vh` in addition to `s`. True 1007 by default. 1008 hermitian : bool, optional 1009 If True, `a` is assumed to be Hermitian (symmetric if real-valued), 1010 enabling a more efficient method for finding singular values. 1011 Defaults to False. 1012 1013 .. versionadded:: 1.17.0 1014 1015 Returns 1016 ------- 1017 u : { (..., M, M), (..., M, K) } array 1018 Unitary array(s). The first ``a.ndim - 2`` dimensions have the same 1019 size as those of the input `a`. The size of the last two dimensions 1020 depends on the value of `full_matrices`. Only returned when 1021 `compute_uv` is True. 1022 s : (..., K) array 1023 Vector(s) with the singular values, within each vector sorted in 1024 descending order. The first ``a.ndim - 2`` dimensions have the same 1025 size as those of the input `a`. 1026 vh : { (..., N, N), (..., K, N) } array 1027 Unitary array(s). The first ``a.ndim - 2`` dimensions have the same 1028 size as those of the input `a`. The size of the last two dimensions 1029 depends on the value of `full_matrices`. Only returned when 1030 `compute_uv` is True. 1031 1032 Raises 1033 ------ 1034 LinAlgError 1035 If SVD computation does not converge. 1036 1037 See Also 1038 -------- 1039 scipy.linalg.svd : Similar function in SciPy. 1040 scipy.linalg.svdvals : Compute singular values of a matrix. 1041 1042 Notes 1043 ----- 1044 1045 .. versionchanged:: 1.8.0 1046 Broadcasting rules apply, see the `numpy.linalg` documentation for 1047 details. 1048 1049 The decomposition is performed using LAPACK routine ``_gesdd``. 1050 1051 SVD is usually described for the factorization of a 2D matrix :math:`A`. 1052 The higher-dimensional case will be discussed below. In the 2D case, SVD is 1053 written as :math:`A = U S V^H`, where :math:`A = a`, :math:`U= u`, 1054 :math:`S= \mathtt{np.diag}(s)` and :math:`V^H = vh`. The 1D array `s` 1055 contains the singular values of `a` and `u` and `vh` are unitary. The rows 1056 of `vh` are the eigenvectors of :math:`A^H A` and the columns of `u` are 1057 the eigenvectors of :math:`A A^H`. In both cases the corresponding 1058 (possibly non-zero) eigenvalues are given by ``s**2``. 1059 1060 If `a` has more than two dimensions, then broadcasting rules apply, as 1061 explained in :ref:`routines.linalg-broadcasting`. This means that SVD is 1062 working in "stacked" mode: it iterates over all indices of the first 1063 ``a.ndim - 2`` dimensions and for each combination SVD is applied to the 1064 last two indices. The matrix `a` can be reconstructed from the 1065 decomposition with either ``(u * s[..., None, :]) @ vh`` or 1066 ``u @ (s[..., None] * vh)``. (The ``@`` operator can be replaced by the 1067 function ``np.matmul`` for python versions below 3.5.) 1068 1069 If `a` is a ``matrix`` object (as opposed to an ``ndarray``), then so are 1070 all the return values. 1071 1072 Examples 1073 -------- 1074 >>> a = np.random.randn(9, 6) + 1j*np.random.randn(9, 6) 1075 >>> b = np.random.randn(2, 7, 8, 3) + 1j*np.random.randn(2, 7, 8, 3) 1076 1077 Reconstruction based on full SVD, 2D case: 1078 1079 >>> u, s, vh = np.linalg.svd(a, full_matrices=True) 1080 >>> u.shape, s.shape, vh.shape 1081 ((9, 9), (6,), (6, 6)) 1082 >>> np.allclose(a, np.dot(u[:, :6] * s, vh)) 1083 True 1084 >>> smat = np.zeros((9, 6), dtype=complex) 1085 >>> smat[:6, :6] = np.diag(s) 1086 >>> np.allclose(a, np.dot(u, np.dot(smat, vh))) 1087 True 1088 1089 Reconstruction based on reduced SVD, 2D case: 1090 1091 >>> u, s, vh = np.linalg.svd(a, full_matrices=False) 1092 >>> u.shape, s.shape, vh.shape 1093 ((9, 6), (6,), (6, 6)) 1094 >>> np.allclose(a, np.dot(u * s, vh)) 1095 True 1096 >>> smat = np.diag(s) 1097 >>> np.allclose(a, np.dot(u, np.dot(smat, vh))) 1098 True 1099 1100 Reconstruction based on full SVD, 4D case: 1101 1102 >>> u, s, vh = np.linalg.svd(b, full_matrices=True) 1103 >>> u.shape, s.shape, vh.shape 1104 ((2, 7, 8, 8), (2, 7, 3), (2, 7, 3, 3)) 1105 >>> np.allclose(b, np.matmul(u[..., :3] * s[..., None, :], vh)) 1106 True 1107 >>> np.allclose(b, np.matmul(u[..., :3], s[..., None] * vh)) 1108 True 1109 1110 Reconstruction based on reduced SVD, 4D case: 1111 1112 >>> u, s, vh = np.linalg.svd(b, full_matrices=False) 1113 >>> u.shape, s.shape, vh.shape 1114 ((2, 7, 8, 3), (2, 7, 3), (2, 7, 3, 3)) 1115 >>> np.allclose(b, np.matmul(u * s[..., None, :], vh)) 1116 True 1117 >>> np.allclose(b, np.matmul(u, s[..., None] * vh)) 1118 True 1119 1120 r N.r� ��axisr� zD->DdDzd->dddr� Fr� r� r� )�numpyrn r r= r3 r> �take_along_axisr� � conjugater r? r� r� rg r_ r� rF Zsvd_m_fZsvd_n_fZsvd_m_sZsvd_n_srr r� rx Zsvd_mZsvd_n)rk r� r� r� �_nxrm �s�u�sgn�sidxr� rq r� rf r� r� r� r� �vhrL rL rM r � sT 1121 r c C r� ro rL )�x�prL rL rM �_cond_dispatcher{ r� r c C s� t | �} t| �r td��|du s|dks|dkrIt| dd�}tdd�� |dkr1|d |d 1122 }n|d 1123 |d }W d � n1 sCw Y nGt| � t| � t| �\}}t|�r]d nd }tdd�� t j 1124 | |d �}t | |dd�t ||dd� }W d � n1 s�w Y |j |dd�}t |�}t |�}|�� r�|t | �jdd� M }|jdkr�t||< n|r�t|d< |jdkr�|d }|S )a� 1125 Compute the condition number of a matrix. 1126 1127 This function is capable of returning the condition number using 1128 one of seven different norms, depending on the value of `p` (see 1129 Parameters below). 1130 1131 Parameters 1132 ---------- 1133 x : (..., M, N) array_like 1134 The matrix whose condition number is sought. 1135 p : {None, 1, -1, 2, -2, inf, -inf, 'fro'}, optional 1136 Order of the norm used in the condition number computation: 1137 1138 ===== ============================ 1139 p norm for matrices 1140 ===== ============================ 1141 None 2-norm, computed directly using the ``SVD`` 1142 'fro' Frobenius norm 1143 inf max(sum(abs(x), axis=1)) 1144 -inf min(sum(abs(x), axis=1)) 1145 1 max(sum(abs(x), axis=0)) 1146 -1 min(sum(abs(x), axis=0)) 1147 2 2-norm (largest sing. value) 1148 -2 smallest singular value 1149 ===== ============================ 1150 1151 inf means the `numpy.inf` object, and the Frobenius norm is 1152 the root-of-sum-of-squares norm. 1153 1154 Returns 1155 ------- 1156 c : {float, inf} 1157 The condition number of the matrix. May be infinite. 1158 1159 See Also 1160 -------- 1161 numpy.linalg.norm 1162 1163 Notes 1164 ----- 1165 The condition number of `x` is defined as the norm of `x` times the 1166 norm of the inverse of `x` [1]_; the norm can be the usual L2-norm 1167 (root-of-sum-of-squares) or one of a number of other matrix norms. 1168 1169 References 1170 ---------- 1171 .. [1] G. Strang, *Linear Algebra and Its Applications*, Orlando, FL, 1172 Academic Press, Inc., 1980, pg. 285. 1173 1174 Examples 1175 -------- 1176 >>> from numpy import linalg as LA 1177 >>> a = np.array([[1, 0, -1], [0, 1, 0], [1, 0, 1]]) 1178 >>> a 1179 array([[ 1, 0, -1], 1180 [ 0, 1, 0], 1181 [ 1, 0, 1]]) 1182 >>> LA.cond(a) 1183 1.4142135623730951 1184 >>> LA.cond(a, 'fro') 1185 3.1622776601683795 1186 >>> LA.cond(a, np.inf) 1187 2.0 1188 >>> LA.cond(a, -np.inf) 1189 1.0 1190 >>> LA.cond(a, 1) 1191 2.0 1192 >>> LA.cond(a, -1) 1193 1.0 1194 >>> LA.cond(a, 2) 1195 1.4142135623730951 1196 >>> LA.cond(a, -2) 1197 0.70710678118654746 # may vary 1198 >>> min(LA.svd(a, compute_uv=False))*min(LA.svd(LA.inv(a), compute_uv=False)) 1199 0.70710678118654746 # may vary 1200 1201 z#cond is not defined on empty arraysNrb r� F�r� rO )r$ ).r� ).r r� r� �r� �r� r� r� r� r rL )r r� r r r- r� r� r� rr rF r r r� r< �anyr� r% ) r r r� r� rq r� r� Zinvx�nan_maskrL rL rM r s@ P � �� � 1202 1203 1204 r c C r� ro rL )�A�tolr� rL rL rM �_matrix_rank_dispatcher� r� r c C s� t | �} | jdk rtt| dk� �S t| d|d�}|du r4|jddd�t| jd d� � t|j�j }nt |�d 1205 t 1206 f }t ||kdd �S ) a� 1207 Return matrix rank of array using SVD method 1208 1209 Rank of the array is the number of singular values of the array that are 1210 greater than `tol`. 1211 1212 .. versionchanged:: 1.14 1213 Can now operate on stacks of matrices 1214 1215 Parameters 1216 ---------- 1217 A : {(M,), (..., M, N)} array_like 1218 Input vector or stack of matrices. 1219 tol : (...) array_like, float, optional 1220 Threshold below which SVD values are considered zero. If `tol` is 1221 None, and ``S`` is an array with singular values for `M`, and 1222 ``eps`` is the epsilon value for datatype of ``S``, then `tol` is 1223 set to ``S.max() * max(M, N) * eps``. 1224 1225 .. versionchanged:: 1.14 1226 Broadcasted against the stack of matrices 1227 hermitian : bool, optional 1228 If True, `A` is assumed to be Hermitian (symmetric if real-valued), 1229 enabling a more efficient method for finding singular values. 1230 Defaults to False. 1231 1232 .. versionadded:: 1.14 1233 1234 Returns 1235 ------- 1236 rank : (...) array_like 1237 Rank of A. 1238 1239 Notes 1240 ----- 1241 The default threshold to detect rank deficiency is a test on the magnitude 1242 of the singular values of `A`. By default, we identify singular values less 1243 than ``S.max() * max(M, N) * eps`` as indicating rank deficiency (with 1244 the symbols defined above). This is the algorithm MATLAB uses [1]. It also 1245 appears in *Numerical recipes* in the discussion of SVD solutions for linear 1246 least squares [2]. 1247 1248 This default threshold is designed to detect rank deficiency accounting for 1249 the numerical errors of the SVD computation. Imagine that there is a column 1250 in `A` that is an exact (in floating point) linear combination of other 1251 columns in `A`. Computing the SVD on `A` will not produce a singular value 1252 exactly equal to 0 in general: any difference of the smallest SVD value from 1253 0 will be caused by numerical imprecision in the calculation of the SVD. 1254 Our threshold for small SVD values takes this numerical imprecision into 1255 account, and the default threshold will detect such numerical rank 1256 deficiency. The threshold may declare a matrix `A` rank deficient even if 1257 the linear combination of some columns of `A` is not exactly equal to 1258 another column of `A` but only numerically very close to another column of 1259 `A`. 1260 1261 We chose our default threshold because it is in wide use. Other thresholds 1262 are possible. For example, elsewhere in the 2007 edition of *Numerical 1263 recipes* there is an alternative threshold of ``S.max() * 1264 np.finfo(A.dtype).eps / 2. * np.sqrt(m + n + 1.)``. The authors describe 1265 this threshold as being based on "expected roundoff error" (p 71). 1266 1267 The thresholds above deal with floating point roundoff error in the 1268 calculation of the SVD. However, you may have more information about the 1269 sources of error in `A` that would make you consider other tolerance values 1270 to detect *effective* rank deficiency. The most useful measure of the 1271 tolerance depends on the operations you intend to use on your matrix. For 1272 example, if your data come from uncertain measurements with uncertainties 1273 greater than floating point epsilon, choosing a tolerance near that 1274 uncertainty may be preferable. The tolerance may be absolute if the 1275 uncertainties are absolute rather than relative. 1276 1277 References 1278 ---------- 1279 .. [1] MATLAB reference documentation, "Rank" 1280 https://www.mathworks.com/help/techdoc/ref/rank.html 1281 .. [2] W. H. Press, S. A. Teukolsky, W. T. Vetterling and B. P. Flannery, 1282 "Numerical Recipes (3rd edition)", Cambridge University Press, 2007, 1283 page 795. 1284 1285 Examples 1286 -------- 1287 >>> from numpy.linalg import matrix_rank 1288 >>> matrix_rank(np.eye(4)) # Full rank matrix 1289 4 1290 >>> I=np.eye(4); I[-1,-1] = 0. # rank deficient matrix 1291 >>> matrix_rank(I) 1292 3 1293 >>> matrix_rank(np.ones((4,))) # 1 dimension - rank 1 unless all 0 1294 1 1295 >>> matrix_rank(np.zeros((4,))) 1296 0 1297 rb r F)r� r� Nr� T�r� �keepdimsr� .r� ) r r� �intr$ r �maxr� r, r| �epsr# r; )r r r� �SrL rL rM r � s ^ 1298 .r c C r� ro rL )rk �rcondr� rL rL rM �_pinv_dispatchere r� r �V瞯�<c C s� t | �\} }t|�}t| �r+| jdd� \}}t| jdd� ||f | jd�}||�S | �� } t| d|d�\}}} |dtf t |ddd � } 1299 || 1300 k} t 1301 d 1302 || |d �}d || < t t | �t |dtf t |���}||�S ) a� 1303 Compute the (Moore-Penrose) pseudo-inverse of a matrix. 1304 1305 Calculate the generalized inverse of a matrix using its 1306 singular-value decomposition (SVD) and including all 1307 *large* singular values. 1308 1309 .. versionchanged:: 1.14 1310 Can now operate on stacks of matrices 1311 1312 Parameters 1313 ---------- 1314 a : (..., M, N) array_like 1315 Matrix or stack of matrices to be pseudo-inverted. 1316 rcond : (...) array_like of float 1317 Cutoff for small singular values. 1318 Singular values less than or equal to 1319 ``rcond * largest_singular_value`` are set to zero. 1320 Broadcasts against the stack of matrices. 1321 hermitian : bool, optional 1322 If True, `a` is assumed to be Hermitian (symmetric if real-valued), 1323 enabling a more efficient method for finding singular values. 1324 Defaults to False. 1325 1326 .. versionadded:: 1.17.0 1327 1328 Returns 1329 ------- 1330 B : (..., N, M) ndarray 1331 The pseudo-inverse of `a`. If `a` is a `matrix` instance, then so 1332 is `B`. 1333 1334 Raises 1335 ------ 1336 LinAlgError 1337 If the SVD computation does not converge. 1338 1339 See Also 1340 -------- 1341 scipy.linalg.pinv : Similar function in SciPy. 1342 scipy.linalg.pinvh : Compute the (Moore-Penrose) pseudo-inverse of a 1343 Hermitian matrix. 1344 1345 Notes 1346 ----- 1347 The pseudo-inverse of a matrix A, denoted :math:`A^+`, is 1348 defined as: "the matrix that 'solves' [the least-squares problem] 1349 :math:`Ax = b`," i.e., if :math:`\bar{x}` is said solution, then 1350 :math:`A^+` is that matrix such that :math:`\bar{x} = A^+b`. 1351 1352 It can be shown that if :math:`Q_1 \Sigma Q_2^T = A` is the singular 1353 value decomposition of A, then 1354 :math:`A^+ = Q_2 \Sigma^+ Q_1^T`, where :math:`Q_{1,2}` are 1355 orthogonal matrices, :math:`\Sigma` is a diagonal matrix consisting 1356 of A's so-called singular values, (followed, typically, by 1357 zeros), and then :math:`\Sigma^+` is simply the diagonal matrix 1358 consisting of the reciprocals of A's singular values 1359 (again, followed by zeros). [1]_ 1360 1361 References 1362 ---------- 1363 .. [1] G. Strang, *Linear Algebra and Its Applications*, 2nd Ed., Orlando, 1364 FL, Academic Press, Inc., 1980, pp. 139-142. 1365 1366 Examples 1367 -------- 1368 The following example checks that ``a * a+ * a == a`` and 1369 ``a+ * a * a+ == a+``: 1370 1371 >>> a = np.random.randn(9, 6) 1372 >>> B = np.linalg.pinv(a) 1373 >>> np.allclose(a, np.dot(a, np.dot(B, a))) 1374 True 1375 >>> np.allclose(B, np.dot(B, np.dot(a, B))) 1376 True 1377 1378 r� Nr� F)r� r� .r� Tr rS )�where�outr )rn r r� r� r r| r� r r# r1 r: r8 r� r( ) rk r r� rm r� r� r� r r� r� �cutoff�largerL rL rM r i s O 1379 r c C sr t | �} t| � t| � t| �\}}t|�}t|�r dnd}tj| |d�\}}|j|dd�}|j|dd�}||fS )aK 1380 Compute the sign and (natural) logarithm of the determinant of an array. 1381 1382 If an array has a very small or very large determinant, then a call to 1383 `det` may overflow or underflow. This routine is more robust against such 1384 issues, because it computes the logarithm of the determinant rather than 1385 the determinant itself. 1386 1387 Parameters 1388 ---------- 1389 a : (..., M, M) array_like 1390 Input array, has to be a square 2-D array. 1391 1392 Returns 1393 ------- 1394 sign : (...) array_like 1395 A number representing the sign of the determinant. For a real matrix, 1396 this is 1, 0, or -1. For a complex matrix, this is a complex number 1397 with absolute value 1 (i.e., it is on the unit circle), or else 0. 1398 logdet : (...) array_like 1399 The natural log of the absolute value of the determinant. 1400 1401 If the determinant is zero, then `sign` will be 0 and `logdet` will be 1402 -Inf. In all cases, the determinant is equal to ``sign * np.exp(logdet)``. 1403 1404 See Also 1405 -------- 1406 det 1407 1408 Notes 1409 ----- 1410 1411 .. versionadded:: 1.8.0 1412 1413 Broadcasting rules apply, see the `numpy.linalg` documentation for 1414 details. 1415 1416 .. versionadded:: 1.6.0 1417 1418 The determinant is computed via LU factorization using the LAPACK 1419 routine ``z/dgetrf``. 1420 1421 1422 Examples 1423 -------- 1424 The determinant of a 2-D array ``[[a, b], [c, d]]`` is ``ad - bc``: 1425 1426 >>> a = np.array([[1, 2], [3, 4]]) 1427 >>> (sign, logdet) = np.linalg.slogdet(a) 1428 >>> (sign, logdet) 1429 (-1, 0.69314718055994529) # may vary 1430 >>> sign * np.exp(logdet) 1431 -2.0 1432 1433 Computing log-determinants for a stack of matrices: 1434 1435 >>> a = np.array([ [[1, 2], [3, 4]], [[1, 2], [2, 1]], [[1, 3], [3, 1]] ]) 1436 >>> a.shape 1437 (3, 2, 2) 1438 >>> sign, logdet = np.linalg.slogdet(a) 1439 >>> (sign, logdet) 1440 (array([-1., -1., -1.]), array([ 0.69314718, 1.09861229, 2.07944154])) 1441 >>> sign * np.exp(logdet) 1442 array([-2., -3., -8.]) 1443 1444 This routine succeeds where ordinary `det` does not: 1445 1446 >>> np.linalg.det(np.eye(500) * 0.1) 1447 0.0 1448 >>> np.linalg.slogdet(np.eye(500) * 0.1) 1449 (1, -1151.2925464970228) 1450 1451 zD->Ddr� r Fr� ) r r� r� r� rx rr rF r 1452 r� )rk rq r� Zreal_tr� r= �logdetrL rL rM r 1453 � s K r 1454 c C sT t | �} t| � t| � t| �\}}t|�rdnd}tj| |d�}|j|dd�}|S )a- 1455 Compute the determinant of an array. 1456 1457 Parameters 1458 ---------- 1459 a : (..., M, M) array_like 1460 Input array to compute determinants for. 1461 1462 Returns 1463 ------- 1464 det : (...) array_like 1465 Determinant of `a`. 1466 1467 See Also 1468 -------- 1469 slogdet : Another way to represent the determinant, more suitable 1470 for large matrices where underflow/overflow may occur. 1471 scipy.linalg.det : Similar function in SciPy. 1472 1473 Notes 1474 ----- 1475 1476 .. versionadded:: 1.8.0 1477 1478 Broadcasting rules apply, see the `numpy.linalg` documentation for 1479 details. 1480 1481 The determinant is computed via LU factorization using the LAPACK 1482 routine ``z/dgetrf``. 1483 1484 Examples 1485 -------- 1486 The determinant of a 2-D array [[a, b], [c, d]] is ad - bc: 1487 1488 >>> a = np.array([[1, 2], [3, 4]]) 1489 >>> np.linalg.det(a) 1490 -2.0 # may vary 1491 1492 Computing determinants for a stack of matrices: 1493 1494 >>> a = np.array([ [[1, 2], [3, 4]], [[1, 2], [2, 1]], [[1, 3], [3, 1]] ]) 1495 >>> a.shape 1496 (3, 2, 2) 1497 >>> np.linalg.det(a) 1498 array([-2., -3., -8.]) 1499 1500 r� r� r Fr� )r r� r� r� rr rF r r� )rk rq r� r� r� rL rL rM r % s 1 r c C r� ro rL )rk r� r rL rL rM �_lstsq_dispatcherb r\ r r� c C s� t | �\} }t |�\}}|jdk}|r|dd�tf }t| |� | jdd� \}}|jdd� \}} ||kr:td��t| |�\} 1501 } t| �} |dkrStj dt 1502 dd� d }|du rat | 1503 �j t ||� }||kritj} ntj} t| 1504 �rrd 1505 nd }tt�}| d kr�t|jdd� || d f |jd �}| | ||||d�\}}}}|d kr�d |d< | d kr�|dd| �f }|dd| �f }|r�|jd d�}||ks�||kr�tg | �}|j| dd�}|j| dd�}|j| dd�}||�||�||fS )a= 1506 Return the least-squares solution to a linear matrix equation. 1507 1508 Computes the vector `x` that approximately solves the equation 1509 ``a @ x = b``. The equation may be under-, well-, or over-determined 1510 (i.e., the number of linearly independent rows of `a` can be less than, 1511 equal to, or greater than its number of linearly independent columns). 1512 If `a` is square and of full rank, then `x` (but for round-off error) 1513 is the "exact" solution of the equation. Else, `x` minimizes the 1514 Euclidean 2-norm :math:`||b - ax||`. If there are multiple minimizing 1515 solutions, the one with the smallest 2-norm :math:`||x||` is returned. 1516 1517 Parameters 1518 ---------- 1519 a : (M, N) array_like 1520 "Coefficient" matrix. 1521 b : {(M,), (M, K)} array_like 1522 Ordinate or "dependent variable" values. If `b` is two-dimensional, 1523 the least-squares solution is calculated for each of the `K` columns 1524 of `b`. 1525 rcond : float, optional 1526 Cut-off ratio for small singular values of `a`. 1527 For the purposes of rank determination, singular values are treated 1528 as zero if they are smaller than `rcond` times the largest singular 1529 value of `a`. 1530 1531 .. versionchanged:: 1.14.0 1532 If not set, a FutureWarning is given. The previous default 1533 of ``-1`` will use the machine precision as `rcond` parameter, 1534 the new default will use the machine precision times `max(M, N)`. 1535 To silence the warning and use the new default, use ``rcond=None``, 1536 to keep using the old behavior, use ``rcond=-1``. 1537 1538 Returns 1539 ------- 1540 x : {(N,), (N, K)} ndarray 1541 Least-squares solution. If `b` is two-dimensional, 1542 the solutions are in the `K` columns of `x`. 1543 residuals : {(1,), (K,), (0,)} ndarray 1544 Sums of squared residuals: Squared Euclidean 2-norm for each column in 1545 ``b - a @ x``. 1546 If the rank of `a` is < N or M <= N, this is an empty array. 1547 If `b` is 1-dimensional, this is a (1,) shape array. 1548 Otherwise the shape is (K,). 1549 rank : int 1550 Rank of matrix `a`. 1551 s : (min(M, N),) ndarray 1552 Singular values of `a`. 1553 1554 Raises 1555 ------ 1556 LinAlgError 1557 If computation does not converge. 1558 1559 See Also 1560 -------- 1561 scipy.linalg.lstsq : Similar function in SciPy. 1562 1563 Notes 1564 ----- 1565 If `b` is a matrix, then all array results are returned as matrices. 1566 1567 Examples 1568 -------- 1569 Fit a line, ``y = mx + c``, through some noisy data-points: 1570 1571 >>> x = np.array([0, 1, 2, 3]) 1572 >>> y = np.array([-1, 0.2, 0.9, 2.1]) 1573 1574 By examining the coefficients, we see that the line should have a 1575 gradient of roughly 1 and cut the y-axis at, more or less, -1. 1576 1577 We can rewrite the line equation as ``y = Ap``, where ``A = [[x 1]]`` 1578 and ``p = [[m], [c]]``. Now use `lstsq` to solve for `p`: 1579 1580 >>> A = np.vstack([x, np.ones(len(x))]).T 1581 >>> A 1582 array([[ 0., 1.], 1583 [ 1., 1.], 1584 [ 2., 1.], 1585 [ 3., 1.]]) 1586 1587 >>> m, c = np.linalg.lstsq(A, y, rcond=None)[0] 1588 >>> m, c 1589 (1.0 -0.95) # may vary 1590 1591 Plot the data along with the fitted line: 1592 1593 >>> import matplotlib.pyplot as plt 1594 >>> _ = plt.plot(x, y, 'o', label='Original data', markersize=10) 1595 >>> _ = plt.plot(x, m*x + c, 'r', label='Fitted line') 1596 >>> _ = plt.legend() 1597 >>> plt.show() 1598 1599 rS Nr� zIncompatible dimensionsr� a 1600 `rcond` parameter will change to the default of machine precision times ``max(M, N)`` where M and N are the input matrix dimensions. 1601 To use the future default and silence this warning we advise to pass `rcond=None`, to keep using the old, explicitly pass `rcond=-1`.r� r� r� z DDd->Ddidz ddd->ddidr r� r� .r� Fr� T)rn r� r# r� r� r r� rx r� r� � FutureWarningr, r r rF Zlstsq_mZlstsq_nrr rg r` r r| �squeezer r� )rk r� r r� rm Zis_1dr� r� �m2�n_rhsrq r� Z result_real_tr� r� rf r �resids�rankr� rL rL rM r f sP a 1602 1603 �$ 1604 r c C s( t | ||fd�}|t|dd�dd�}|S )a� Compute a function of the singular values of the 2-D matrices in `x`. 1605 1606 This is a private utility function used by `numpy.linalg.norm()`. 1607 1608 Parameters 1609 ---------- 1610 x : ndarray 1611 row_axis, col_axis : int 1612 The axes of `x` that hold the 2-D matrices. 1613 op : callable 1614 This should be either numpy.amin or `numpy.amax` or `numpy.sum`. 1615 1616 Returns 1617 ------- 1618 result : float or ndarray 1619 If `x` is 2-D, the return values is a float. 1620 Otherwise, it is an array with ``x.ndim - 2`` dimensions. 1621 The return values are either the minimum or maximum or sum of the 1622 singular values of the matrices, depending on whether `op` 1623 is `numpy.amin` or `numpy.amax` or `numpy.sum`. 1624 1625 r Fr r� r� )r/ r )r �row_axis�col_axis�op�yr� rL rL rM �_multi_svd_norm s r( c C r� ro rL )r �ordr� r rL rL rM �_norm_dispatcher" r� r* c 1626 C s� t | �} t| jjttf�s| �t�} |du r_| j}|du s-|dv r%|dks-|dkr_|dkr_| j dd�} t 1627 | jj�rJ| j }| j }|� |�|� |� }n| � | �}t|�}|r]|�|dg �}|S | j} |du rmtt| ��}n t|t�s�zt|�}W n ty� } 1628 ztd�| 1629 �d} 1630 ~ 1631 ww |f}t|�dk�r|tkr�t| �j||d�S |t kr�t| �j||d�S |d kr�| d k�| j j�j||d�S |dkr�t j t| �||d�S |du s�|dkr�| � � | j } tt j | ||d��S t|t �r�t d 1632 |� d ���t| �} | |C } t j | ||d�}|t!||jd �C }|S t|�dk�r�|\} }t"| | �} t"|| �}| |k�r.t d ��|dk�r;t#| | |t$�}n�|dk�rHt#| | |t%�}n�|dk�rd|| k�rV|d8 }t j t| �| d�j|d�}nz|tk�r�| |k�rr| d8 } t j t| �|d�j| d�}n^|dk�r�|| k�r�|d8 }t j t| �| d�j|d�}nB|t k�r�| |k�r�| d8 } t j t| �|d�j| d�}n%|dv �r�tt j | � � | j |d��}n|dk�r�t#| | |t�}nt d��|�r�t&| j'�}d||d < d||d < |�|�}|S t d��)a� 1633 Matrix or vector norm. 1634 1635 This function is able to return one of eight different matrix norms, 1636 or one of an infinite number of vector norms (described below), depending 1637 on the value of the ``ord`` parameter. 1638 1639 Parameters 1640 ---------- 1641 x : array_like 1642 Input array. If `axis` is None, `x` must be 1-D or 2-D, unless `ord` 1643 is None. If both `axis` and `ord` are None, the 2-norm of 1644 ``x.ravel`` will be returned. 1645 ord : {non-zero int, inf, -inf, 'fro', 'nuc'}, optional 1646 Order of the norm (see table under ``Notes``). inf means numpy's 1647 `inf` object. The default is None. 1648 axis : {None, int, 2-tuple of ints}, optional. 1649 If `axis` is an integer, it specifies the axis of `x` along which to 1650 compute the vector norms. If `axis` is a 2-tuple, it specifies the 1651 axes that hold 2-D matrices, and the matrix norms of these matrices 1652 are computed. If `axis` is None then either a vector norm (when `x` 1653 is 1-D) or a matrix norm (when `x` is 2-D) is returned. The default 1654 is None. 1655 1656 .. versionadded:: 1.8.0 1657 1658 keepdims : bool, optional 1659 If this is set to True, the axes which are normed over are left in the 1660 result as dimensions with size one. With this option the result will 1661 broadcast correctly against the original `x`. 1662 1663 .. versionadded:: 1.10.0 1664 1665 Returns 1666 ------- 1667 n : float or ndarray 1668 Norm of the matrix or vector(s). 1669 1670 See Also 1671 -------- 1672 scipy.linalg.norm : Similar function in SciPy. 1673 1674 Notes 1675 ----- 1676 For values of ``ord < 1``, the result is, strictly speaking, not a 1677 mathematical 'norm', but it may still be useful for various numerical 1678 purposes. 1679 1680 The following norms can be calculated: 1681 1682 ===== ============================ ========================== 1683 ord norm for matrices norm for vectors 1684 ===== ============================ ========================== 1685 None Frobenius norm 2-norm 1686 'fro' Frobenius norm -- 1687 'nuc' nuclear norm -- 1688 inf max(sum(abs(x), axis=1)) max(abs(x)) 1689 -inf min(sum(abs(x), axis=1)) min(abs(x)) 1690 0 -- sum(x != 0) 1691 1 max(sum(abs(x), axis=0)) as below 1692 -1 min(sum(abs(x), axis=0)) as below 1693 2 2-norm (largest sing. value) as below 1694 -2 smallest singular value as below 1695 other -- sum(abs(x)**ord)**(1./ord) 1696 ===== ============================ ========================== 1697 1698 The Frobenius norm is given by [1]_: 1699 1700 :math:`||A||_F = [\sum_{i,j} abs(a_{i,j})^2]^{1/2}` 1701 1702 The nuclear norm is the sum of the singular values. 1703 1704 Both the Frobenius and nuclear norm orders are only defined for 1705 matrices and raise a ValueError when ``x.ndim != 2``. 1706 1707 References 1708 ---------- 1709 .. [1] G. H. Golub and C. F. Van Loan, *Matrix Computations*, 1710 Baltimore, MD, Johns Hopkins University Press, 1985, pg. 15 1711 1712 Examples 1713 -------- 1714 >>> from numpy import linalg as LA 1715 >>> a = np.arange(9) - 4 1716 >>> a 1717 array([-4, -3, -2, ..., 2, 3, 4]) 1718 >>> b = a.reshape((3, 3)) 1719 >>> b 1720 array([[-4, -3, -2], 1721 [-1, 0, 1], 1722 [ 2, 3, 4]]) 1723 1724 >>> LA.norm(a) 1725 7.745966692414834 1726 >>> LA.norm(b) 1727 7.745966692414834 1728 >>> LA.norm(b, 'fro') 1729 7.745966692414834 1730 >>> LA.norm(a, np.inf) 1731 4.0 1732 >>> LA.norm(b, np.inf) 1733 9.0 1734 >>> LA.norm(a, -np.inf) 1735 0.0 1736 >>> LA.norm(b, -np.inf) 1737 2.0 1738 1739 >>> LA.norm(a, 1) 1740 20.0 1741 >>> LA.norm(b, 1) 1742 7.0 1743 >>> LA.norm(a, -1) 1744 -4.6566128774142013e-010 1745 >>> LA.norm(b, -1) 1746 6.0 1747 >>> LA.norm(a, 2) 1748 7.745966692414834 1749 >>> LA.norm(b, 2) 1750 7.3484692283495345 1751 1752 >>> LA.norm(a, -2) 1753 0.0 1754 >>> LA.norm(b, -2) 1755 1.8570331885190563e-016 # may vary 1756 >>> LA.norm(a, 3) 1757 5.8480354764257312 # may vary 1758 >>> LA.norm(a, -3) 1759 0.0 1760 1761 Using the `axis` argument to compute vector norms: 1762 1763 >>> c = np.array([[ 1, 2, 3], 1764 ... [-1, 1, 4]]) 1765 >>> LA.norm(c, axis=0) 1766 array([ 1.41421356, 2.23606798, 5. ]) 1767 >>> LA.norm(c, axis=1) 1768 array([ 3.74165739, 4.24264069]) 1769 >>> LA.norm(c, ord=1, axis=1) 1770 array([ 6., 6.]) 1771 1772 Using the `axis` argument to compute matrix norms: 1773 1774 >>> m = np.arange(8).reshape(2,2,2) 1775 >>> LA.norm(m, axis=(1,2)) 1776 array([ 3.74165739, 11.22497216]) 1777 >>> LA.norm(m[0, :, :]), LA.norm(m[1, :, :]) 1778 (3.7416573867739413, 11.224972160321824) 1779 1780 N)r� �frorb rS �K)�orderz6'axis' must be None, an integer or a tuple of integersr r zInvalid norm order 'z ' for vectorsr� zDuplicate axes given.r� r� r� )Nr+ r� �nucz Invalid norm order for matrices.z&Improper number of dimensions to norm.)(r rp r| r} r! r7 r� �floatr� r� rr r� r� r& r) r� �tupler� � 1781 isinstancer � Exceptionr~ r� r% r3 r r� r* r' �reduce�conj�strr� r@ rA r( r1 r0 rc r� )r r) r� r r� Zx_realZx_imagZsqnormr� �ndr� r� Zabsxr$ r% Z ret_shaperL rL rM r & s� 1782 1783 1784 1785 �� 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 r �r c c s � | E d H |V d S ro rL )r� r rL rL rM �_multidot_dispatcher% 1804 s � 1805 1806 r8 c C s t | �}|dk r td��|dkrt| d | d |d�S dd� | D �} | d j| d j}}| d jdkr<t| d �| d< | d jdkrLt| d �j| d< t| � |d krct| d | d | d |d�}nt| �}t | |d|d |d�}|dkr~|dkr~|d 1807 S |dks�|dkr�|� 1808 � S |S ) aa 1809 1810 Compute the dot product of two or more arrays in a single function call, 1811 while automatically selecting the fastest evaluation order. 1812 1813 `multi_dot` chains `numpy.dot` and uses optimal parenthesization 1814 of the matrices [1]_ [2]_. Depending on the shapes of the matrices, 1815 this can speed up the multiplication a lot. 1816 1817 If the first argument is 1-D it is treated as a row vector. 1818 If the last argument is 1-D it is treated as a column vector. 1819 The other arguments must be 2-D. 1820 1821 Think of `multi_dot` as:: 1822 1823 def multi_dot(arrays): return functools.reduce(np.dot, arrays) 1824 1825 1826 Parameters 1827 ---------- 1828 arrays : sequence of array_like 1829 If the first argument is 1-D it is treated as row vector. 1830 If the last argument is 1-D it is treated as column vector. 1831 The other arguments must be 2-D. 1832 out : ndarray, optional 1833 Output argument. This must have the exact kind that would be returned 1834 if it was not used. In particular, it must have the right type, must be 1835 C-contiguous, and its dtype must be the dtype that would be returned 1836 for `dot(a, b)`. This is a performance feature. Therefore, if these 1837 conditions are not met, an exception is raised, instead of attempting 1838 to be flexible. 1839 1840 .. versionadded:: 1.19.0 1841 1842 Returns 1843 ------- 1844 output : ndarray 1845 Returns the dot product of the supplied arrays. 1846 1847 See Also 1848 -------- 1849 numpy.dot : dot multiplication with two arguments. 1850 1851 References 1852 ---------- 1853 1854 .. [1] Cormen, "Introduction to Algorithms", Chapter 15.2, p. 370-378 1855 .. [2] https://en.wikipedia.org/wiki/Matrix_chain_multiplication 1856 1857 Examples 1858 -------- 1859 `multi_dot` allows you to write:: 1860 1861 >>> from numpy.linalg import multi_dot 1862 >>> # Prepare some data 1863 >>> A = np.random.random((10000, 100)) 1864 >>> B = np.random.random((100, 1000)) 1865 >>> C = np.random.random((1000, 5)) 1866 >>> D = np.random.random((5, 333)) 1867 >>> # the actual dot multiplication 1868 >>> _ = multi_dot([A, B, C, D]) 1869 1870 instead of:: 1871 1872 >>> _ = np.dot(np.dot(np.dot(A, B), C), D) 1873 >>> # or 1874 >>> _ = A.dot(B).dot(C).dot(D) 1875 1876 Notes 1877 ----- 1878 The cost for a matrix multiplication can be calculated with the 1879 following function:: 1880 1881 def cost(A, B): 1882 return A.shape[0] * A.shape[1] * B.shape[1] 1883 1884 Assume we have three matrices 1885 :math:`A_{10x100}, B_{100x5}, C_{5x50}`. 1886 1887 The costs for the two different parenthesizations are as follows:: 1888 1889 cost((AB)C) = 10*100*5 + 10*5*50 = 5000 + 2500 = 7500 1890 cost(A(BC)) = 10*100*50 + 100*5*50 = 50000 + 25000 = 75000 1891 1892 rb z Expecting at least two arrays.r rS r7 c S s g | ]}t |��qS rL )r6 ��.0rk rL rL rM � 1893 <listcomp>� 1894 s z multi_dot.<locals>.<listcomp>r� r� )r r ) r� r� r& r� r4 r� r� �_multi_dot_three� _multi_dot_matrix_chain_order� 1895 _multi_dotr� )r� r r� Z 1896 ndim_firstZ ndim_lastr� r- rL rL rM r * 1897 s* V r c 1898 C sd | j \}}|j \}}|| || }|| || } || k r(tt| |�||d�S t| t||�|d�S )z� 1899 Find the best order for three arrays and do the multiplication. 1900 1901 For three arguments `_multi_dot_three` is approximately 15 times faster 1902 than `_multi_dot_matrix_chain_order` 1903 1904 r7 )r� r& ) 1905 r �B�Cr �a0Za1b0Zb1c0�c1Zcost1Zcost2rL rL rM r< � 1906 s 1907 1908 r< c C s t | �}dd� | D �| d jd g }t||ftd�}t||ftd�}td|�D ]O}t|| �D ]F}|| }t|||f< t||�D ]4} ||| f || d |f || || d ||d } 1909 | 1910 |||f k ru| 1911 |||f< | |||f< qAq0q(|r~||fS |S )a� 1912 Return a np.array that encodes the optimal order of mutiplications. 1913 1914 The optimal order array is then used by `_multi_dot()` to do the 1915 multiplication. 1916 1917 Also return the cost matrix if `return_costs` is `True` 1918 1919 The implementation CLOSELY follows Cormen, "Introduction to Algorithms", 1920 Chapter 15.2, p. 370-378. Note that Cormen uses 1-based indices. 1921 1922 cost[i, j] = min([ 1923 cost[prefix] + cost[suffix] + cost_mult(prefix, suffix) 1924 for k in range(i, j)]) 1925 1926 c S s g | ]}|j d �qS )r )r� r9 rL rL rM r; � 1927 s z1_multi_dot_matrix_chain_order.<locals>.<listcomp>r� rS r� )r� r� r r r r5 r� r% ) r� � return_costsr� r r� r� �l�i�jr� r� rL rL rM r= � 1928 s" < ��� r= c C sR ||kr|du s 1929 J �| | S t t| |||||f �t| ||||f d |�|d�S )z4Actually do the multiplication with the given order.NrS r7 )r& r> )r� r- rE rF r rL rL rM r> � 1930 s �r> ro )rb )r� )r� )NNN)TTF)NN)NF)r F)r� )NNF)F)}rK �__all__� functoolsr� r� � 1931 numpy.corer r r r r r r r r r r! r" r# r$ r% r& r' r( r) r* r+ r, r- r. r/ r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r: r; r< r= r> r? r@ �numpy.core.multiarrayrA �numpy.core.overridesrB rC �numpy.lib.twodim_baserD rE � numpy.linalgrF �partial�array_function_dispatch� fortran_intr2 r rU rd r[ r] r^ r_ r` ra rg rn rr rt rz rx 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 r� r r r� r r r r r r r r 1932 r r r r( r* r r8 r r< r= r> rL rL rL rM �<module> s� � � �� 1933 L 1934 1935 T E 1936 H 1937 v 1938 1939 ` K 1940 1941 [ ] 1942 1943 1944 D 1945 v 1946 j d 1947 V 1948 1949 < 1950 1951 x 1952 )