0
# Linear Algebra
1

2
CuPy provides comprehensive linear algebra operations for GPU-accelerated computation, offering NumPy-compatible matrix operations, decomposition methods, eigenvalue computation, and linear system solving optimized for CUDA and ROCm platforms.
3

4
## Capabilities
5

6
### Matrix and Vector Products
7

8
Core linear algebra operations for matrix multiplication and vector products optimized for GPU computation.
9

10
```python { .api }
11
def dot(a, b, out=None):
12
    """
13
    Dot product of two arrays.
14
    
15
    Parameters:
16
        a: array_like - First input array
17
        b: array_like - Second input array
18
        out: ndarray, optional - Output argument for the result
19
    """
20

21
def vdot(a, b):
22
    """
23
    Return the dot product of two vectors.
24
    
25
    Parameters:
26
        a: array_like - First input array
27
        b: array_like - Second input array
28
    """
29

30
def inner(a, b):
31
    """
32
    Inner product of two arrays.
33
    
34
    Parameters:
35
        a, b: array_like - Input arrays
36
    """
37

38
def outer(a, b, out=None):
39
    """
40
    Compute the outer product of two vectors.
41
    
42
    Parameters:
43
        a: (M,) array_like - First input vector
44
        b: (N,) array_like - Second input vector
45
        out: (M, N) ndarray, optional - Output array for the result
46
    """
47

48
def matmul(x1, x2, out=None):
49
    """
50
    Matrix product of two arrays.
51
    
52
    Parameters:
53
        x1, x2: array_like - Input arrays, scalars not allowed
54
        out: ndarray, optional - Output array for the result
55
    """
56

57
def tensordot(a, b, axes=2):
58
    """
59
    Compute tensor dot product along specified axes.
60
    
61
    Parameters:
62
        a, b: array_like - Tensors to "dot"
63
        axes: int or (2,) array_like - If an int N, sum over the last N axes of a and the first N axes of b in order
64
    """
65

66
def einsum(subscripts, *operands, out=None, dtype=None, order='K', casting='safe', optimize=False):
67
    """
68
    Evaluates the Einstein summation convention on the operands.
69
    
70
    Parameters:
71
        subscripts: str - Specifies the subscripts for summation as comma separated list of subscript labels
72
        operands: list of array_like - Arrays for the operation
73
        out: ndarray, optional - Output array to store the result
74
        dtype: dtype, optional - Type of the returned array
75
        order: {'C', 'F', 'A', 'K'}, optional - Controls the memory layout of the output
76
        casting: {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional - Controls what kind of data casting may occur
77
        optimize: {False, True, 'greedy', 'optimal'}, optional - Controls if intermediate optimization should occur
78
    """
79

80
def kron(a, b):
81
    """
82
    Kronecker product of two arrays.
83
    
84
    Parameters:
85
        a, b: array_like - Input arrays
86
    """
87

88
def cross(a, b, axisa=-1, axisb=-1, axisc=-1, axis=None):
89
    """
90
    Return the cross product of two (arrays of) vectors.
91
    
92
    Parameters:
93
        a: array_like - Components of the first vector(s)
94
        b: array_like - Components of the second vector(s)
95
        axisa: int, optional - Axis of a that defines the vector(s)
96
        axisb: int, optional - Axis of b that defines the vector(s)
97
        axisc: int, optional - Axis of c containing the cross product vector(s)
98
        axis: int, optional - If defined, the axis of a, b and c that defines the vector(s) and cross product
99
    """
100
```
101

102
### Norms and Matrix Properties
103

104
Functions for computing matrix and vector norms and other numerical properties.
105

106
```python { .api }
107
def trace(a, offset=0, axis1=0, axis2=1, dtype=None, out=None):
108
    """
109
    Return the sum along diagonals of the array.
110
    
111
    Parameters:
112
        a: array_like - Input array, from which the diagonals are taken
113
        offset: int, optional - Offset of the diagonal from the main diagonal
114
        axis1, axis2: int, optional - Axes to be used as the first and second axis of the 2-D sub-arrays
115
        dtype: dtype, optional - Determines the data-type of the returned array
116
        out: ndarray, optional - Array into which the output is placed
117
    """
118
```
119

120
### Advanced Linear Algebra (cupy.linalg)
121

122
Advanced linear algebra operations including decompositions, eigenvalues, and system solving.
123

124
```python { .api }
125
def matrix_power(a, n):
126
    """
127
    Raise a square matrix to the (integer) power n.
128
    
129
    Parameters:
130
        a: (..., M, M) array_like - Matrix to be "powered"
131
        n: int - The exponent can be any integer or long integer, positive, negative, or zero
132
    """
133

134
def cholesky(a):
135
    """
136
    Cholesky decomposition.
137
    
138
    Parameters:
139
        a: (..., M, M) array_like - Hermitian (symmetric if real-valued), positive-definite input matrix
140
    """
141

142
def qr(a, mode='reduced'):
143
    """
144
    Compute the qr factorization of a matrix.
145
    
146
    Parameters:
147
        a: array_like, shape (..., M, N) - Matrix to be factored
148
        mode: {'reduced', 'complete'}, optional - If K = min(M, N), then 'reduced' returns Q, R with dimensions (..., M, K), (..., K, N)
149
    """
150

151
def svd(a, full_matrices=True, compute_uv=True, hermitian=False):
152
    """
153
    Singular Value Decomposition.
154
    
155
    Parameters:
156
        a: (..., M, N) array_like - Input array with a.ndim >= 2
157
        full_matrices: bool, optional - If True (default), u and vh have the shapes (..., M, M) and (..., N, N)
158
        compute_uv: bool, optional - Whether or not to compute u and vh in addition to s (default is True)
159
        hermitian: bool, optional - If True, a is assumed to be Hermitian (symmetric if real-valued)
160
    """
161

162
def eigh(a, UPLO='L'):
163
    """
164
    Return the eigenvalues and eigenvectors of a complex Hermitian (conjugate symmetric) or a real symmetric matrix.
165
    
166
    Parameters:
167
        a: (..., M, M) array - Hermitian or real symmetric matrices whose eigenvalues and eigenvectors are to be computed
168
        UPLO: {'L', 'U'}, optional - Whether the calculation is done with the lower triangular part of a ('L', default) or the upper triangular part ('U')
169
    """
170

171
def eigvalsh(a, UPLO='L'):
172
    """
173
    Compute the eigenvalues of a complex Hermitian or real symmetric matrix.
174
    
175
    Parameters:
176
        a: (..., M, M) array_like - Hermitian or real symmetric matrices whose eigenvalues are to be computed
177
        UPLO: {'L', 'U'}, optional - Whether the calculation is done with the lower triangular part of a ('L', default) or the upper triangular part ('U')
178
    """
179

180
def norm(x, ord=None, axis=None, keepdims=False):
181
    """
182
    Matrix or vector norm.
183
    
184
    Parameters:
185
        x: array_like - Input array
186
        ord: {non-zero int, inf, -inf, 'fro', 'nuc'}, optional - Order of the norm
187
        axis: {None, int, 2-tuple of ints}, optional - If axis is an integer, it specifies the axis of x along which to compute the vector norms
188
        keepdims: bool, optional - If this is set to True, the axes which are normed over are left in the result as dimensions with size one
189
    """
190

191
def det(a):
192
    """
193
    Compute the determinant of an array.
194
    
195
    Parameters:
196
        a: (..., M, M) array_like - Input array to compute determinants for
197
    """
198

199
def matrix_rank(M, tol=None, hermitian=False):
200
    """
201
    Return matrix rank of array using SVD method.
202
    
203
    Parameters:
204
        M: {(M,), (..., M, N)} array_like - Input vector or stack of matrices
205
        tol: (...) array_like, float, optional - Threshold below which SVD values are considered zero
206
        hermitian: bool, optional - If True, M is assumed to be Hermitian (symmetric if real-valued)
207
    """
208

209
def slogdet(a):
210
    """
211
    Compute the sign and (natural) logarithm of the determinant of an array.
212
    
213
    Parameters:
214
        a: (..., M, M) array_like - Input array, has to be a square 2-D array
215
    """
216

217
def solve(a, b):
218
    """
219
    Solve a linear matrix equation, or system of linear scalar equations.
220
    
221
    Parameters:
222
        a: (..., M, M) array_like - Coefficient matrix
223
        b: {(..., M,), (..., M, K)}, array_like - Ordinate or "dependent variable" values
224
    """
225

226
def tensorsolve(a, b, axes=None):
227
    """
228
    Solve the tensor equation a x = b for x.
229
    
230
    Parameters:
231
        a: array_like - Coefficient tensor, of shape b.shape + Q
232
        b: array_like - Right-hand tensor, which can be of any shape
233
        axes: tuple of ints, optional - Axes in a to reorder to the right, before inversion
234
    """
235

236
def lstsq(a, b, rcond=None):
237
    """
238
    Return the least-squares solution to a linear matrix equation.
239
    
240
    Parameters:
241
        a: (M, N) array_like - "Coefficient" matrix
242
        b: array_like - Ordinate or "dependent variable" values
243
        rcond: float, optional - Cut-off ratio for small singular values of a
244
    """
245

246
def inv(a):
247
    """
248
    Compute the (multiplicative) inverse of a matrix.
249
    
250
    Parameters:
251
        a: (..., M, M) array_like - Matrix to be inverted
252
    """
253

254
def pinv(a, rcond=1e-15, hermitian=False):
255
    """
256
    Compute the (Moore-Penrose) pseudo-inverse of a matrix.
257
    
258
    Parameters:
259
        a: (..., M, N) array_like - Matrix or stack of matrices to be pseudo-inverted
260
        rcond: (...) array_like of float - Cutoff for small singular values
261
        hermitian: bool, optional - If True, a is assumed to be Hermitian (symmetric if real-valued)
262
    """
263

264
def tensorinv(a, ind=2):
265
    """
266
    Compute the 'inverse' of an N-dimensional array.
267
    
268
    Parameters:
269
        a: array_like - Tensor to 'invert'. Its shape must be 'square', i.e., prod(a.shape[:ind]) == prod(a.shape[ind:])
270
        ind: int, optional - Number of first indices that are involved in the inverse sum
271
    """
272
```
273

274
### Linear Algebra Exceptions
275

276
Exception classes for linear algebra errors.
277

278
```python { .api }
279
class LinAlgError(Exception):
280
    """
281
    Generic Python-exception-derived object raised by linalg functions.
282
    
283
    General purpose exception class, derived from Python's exception.Exception
284
    class, programmatically raised in linalg functions when a Linear
285
    Algebra-related condition would prevent further correct execution of the
286
    function.
287
    """
288
```
289

290
### Extended Linear Algebra (cupyx.linalg)
291

292
Extended linear algebra functions not available in standard NumPy.
293

294
```python { .api }
295
def invh(a):
296
    """
297
    Compute the inverse of a Hermitian positive-definite matrix.
298
    
299
    Parameters:
300
        a: (..., M, M) array_like - Hermitian positive-definite matrix to be inverted
301
    """
302
```
303

304
## Usage Examples
305

306
```python
307
import cupy as cp
308
import cupy.linalg as la
309

310
# Matrix operations
311
A = cp.random.rand(1000, 1000)
312
B = cp.random.rand(1000, 1000)
313

314
# Basic matrix multiplication
315
C = cp.dot(A, B)
316
D = cp.matmul(A, B)
317

318
# Matrix decompositions
319
Q, R = la.qr(A)
320
U, s, Vt = la.svd(A)
321
L = la.cholesky(A @ A.T + cp.eye(1000))  # Make positive definite
322

323
# Eigenvalue decomposition (for symmetric matrices)
324
symmetric_A = A + A.T
325
eigenvals, eigenvecs = la.eigh(symmetric_A)
326

327
# Solving linear systems
328
x = la.solve(A, cp.random.rand(1000))
329
x_lstsq, residuals, rank, s = la.lstsq(A, cp.random.rand(1000))
330

331
# Matrix properties
332
det_A = la.det(A)
333
norm_A = la.norm(A)
334
trace_A = cp.trace(A)
335
rank_A = la.matrix_rank(A)
336

337
# Matrix inverse and pseudo-inverse
338
A_inv = la.inv(A)
339
A_pinv = la.pinv(A)
340

341
# Vector operations
342
v1 = cp.array([1, 2, 3])
343
v2 = cp.array([4, 5, 6])
344
dot_product = cp.dot(v1, v2)
345
cross_product = cp.cross(v1, v2)
346
outer_product = cp.outer(v1, v2)
347

348
# Einstein summation
349
# Matrix multiplication using einsum
350
result = cp.einsum('ij,jk->ik', A[:10, :10], B[:10, :10])
351

352
# Batch operations on multiple matrices
353
batch_A = cp.random.rand(10, 100, 100)
354
batch_det = la.det(batch_A)
355
batch_inv = la.inv(batch_A)
356
```
357

358
Linear algebra operations in CuPy provide high-performance matrix computation capabilities optimized for GPU acceleration, enabling efficient numerical linear algebra with familiar NumPy interfaces while leveraging the parallel processing power of modern GPUs for scientific computing and machine learning applications.