0
# Linear Algebra
1

2
GPU-accelerated linear algebra operations powered by cuBLAS and cuSOLVER libraries. Provides high-performance matrix operations, decompositions, and equation solving with full NumPy compatibility.
3

4
## Capabilities
5

6
### Matrix and Vector Products
7

8
Fundamental linear algebra operations for matrix and vector multiplication.
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: cupy.ndarray, output array
19
    
20
    Returns:
21
    cupy.ndarray: Dot product result
22
    - 1D x 1D: inner product
23
    - 2D x 2D: matrix multiplication
24
    - 1D x 2D or 2D x 1D: matrix-vector product
25
    """
26

27
def matmul(x1, x2, out=None):
28
    """
29
    Matrix product of two arrays following broadcasting rules.
30
    
31
    Parameters:
32
    - x1: array-like, first input array
33
    - x2: array-like, second input array
34
    - out: cupy.ndarray, output array
35
    
36
    Returns:
37
    cupy.ndarray: Matrix product with proper broadcasting
38
    """
39

40
def inner(a, b):
41
    """
42
    Inner product of two arrays.
43
    
44
    Parameters:
45
    - a, b: array-like, input arrays
46
    
47
    Returns:
48
    cupy.ndarray: Inner product over last axis
49
    """
50

51
def outer(a, b, out=None):
52
    """
53
    Compute outer product of two vectors.
54
    
55
    Parameters:
56
    - a: array-like, first input vector (M,)
57
    - b: array-like, second input vector (N,)
58
    - out: cupy.ndarray, output array
59
    
60
    Returns:
61
    cupy.ndarray: Outer product (M, N)
62
    """
63

64
def tensordot(a, b, axes=2):
65
    """
66
    Compute tensor dot product along specified axes.
67
    
68
    Parameters:
69
    - a, b: array-like, input arrays
70
    - axes: int or (2,) array-like, axes to sum over
71
    
72
    Returns:
73
    cupy.ndarray: Tensor dot product
74
    """
75

76
def kron(a, b):
77
    """
78
    Kronecker product of two arrays.
79
    
80
    Parameters:
81
    - a, b: array-like, input arrays
82
    
83
    Returns:
84
    cupy.ndarray: Kronecker product
85
    """
86

87
def cross(a, b, axisa=-1, axisb=-1, axisc=-1, axis=None):
88
    """
89
    Cross product of two (arrays of) vectors.
90
    
91
    Parameters:
92
    - a, b: array-like, input arrays
93
    - axisa, axisb: int, axis of a and b containing vectors
94
    - axisc: int, axis of output containing cross product
95
    - axis: int, if specified, defines vector axis for all arguments
96
    
97
    Returns:
98
    cupy.ndarray: Cross product
99
    """
100

101
def vdot(a, b):
102
    """
103
    Return dot product of two vectors (flattens arrays first).
104
    
105
    Parameters:
106
    - a, b: array-like, input arrays
107
    
108
    Returns:
109
    scalar: Dot product of flattened arrays
110
    """
111
```
112

113
### Matrix Decompositions
114

115
Matrix factorizations for solving linear systems and analyzing matrix properties.
116

117
```python { .api }
118
def cholesky(a):
119
    """
120
    Cholesky decomposition of positive definite matrix.
121
    
122
    Parameters:
123
    - a: array-like, positive definite matrix (..., M, M)
124
    
125
    Returns:
126
    cupy.ndarray: Lower triangular Cholesky factor L where a = L @ L.T
127
    
128
    Raises:
129
    cupy.linalg.LinAlgError: If matrix is not positive definite
130
    """
131

132
def qr(a, mode='reduced'):
133
    """
134
    Compute QR decomposition of matrix.
135
    
136
    Parameters:
137
    - a: array-like, input matrix (..., M, N)
138
    - mode: {'reduced', 'complete'}, decomposition mode
139
    
140
    Returns:
141
    tuple: (Q, R) where a = Q @ R
142
    - Q: orthogonal matrix (..., M, K)
143
    - R: upper triangular matrix (..., K, N)
144
    - K = min(M, N) for reduced mode, K = M for complete mode
145
    """
146

147
def svd(a, full_matrices=True, compute_uv=True, hermitian=False):
148
    """
149
    Singular Value Decomposition.
150
    
151
    Parameters:
152
    - a: array-like, input matrix (..., M, N)
153
    - full_matrices: bool, whether to compute full U and V matrices
154
    - compute_uv: bool, whether to compute U and V in addition to s
155
    - hermitian: bool, if True, a is assumed Hermitian
156
    
157
    Returns:
158
    tuple or cupy.ndarray:
159
    - If compute_uv=True: (U, s, Vh) where a = U @ diag(s) @ Vh
160
    - If compute_uv=False: s (singular values only)
161
    """
162
```
163

164
### Eigenvalues and Eigenvectors
165

166
Compute eigenvalues and eigenvectors for symmetric/Hermitian matrices.
167

168
```python { .api }
169
def eigh(a, UPLO='L'):
170
    """
171
    Eigenvalues and eigenvectors of Hermitian/symmetric matrix.
172
    
173
    Parameters:
174
    - a: array-like, Hermitian/symmetric matrix (..., M, M)
175
    - UPLO: {'L', 'U'}, use lower or upper triangle
176
    
177
    Returns:
178
    tuple: (eigenvalues, eigenvectors)
179
    - eigenvalues: (..., M) real-valued eigenvalues in ascending order
180
    - eigenvectors: (..., M, M) normalized eigenvectors as columns
181
    """
182

183
def eigvalsh(a, UPLO='L'):
184
    """
185
    Eigenvalues of Hermitian/symmetric matrix.
186
    
187
    Parameters:
188
    - a: array-like, Hermitian/symmetric matrix (..., M, M)
189
    - UPLO: {'L', 'U'}, use lower or upper triangle
190
    
191
    Returns:
192
    cupy.ndarray: Eigenvalues (..., M) in ascending order
193
    """
194
```
195

196
### Matrix Properties
197

198
Functions to compute matrix norms, determinants, and ranks.
199

200
```python { .api }
201
def norm(x, ord=None, axis=None, keepdims=False):
202
    """
203
    Matrix or vector norm.
204
    
205
    Parameters:
206
    - x: array-like, input array
207
    - ord: {None, 'fro', 'nuc', int, float}, norm type
208
    - axis: None or int or 2-tuple of ints, axes for norm computation
209
    - keepdims: bool, whether to keep reduced dimensions
210
    
211
    Returns:
212
    cupy.ndarray: Norm of x
213
    """
214

215
def det(a):
216
    """
217
    Compute determinant of array.
218
    
219
    Parameters:
220
    - a: array-like, square matrix (..., M, M)
221
    
222
    Returns:
223
    cupy.ndarray: Determinant of a
224
    """
225

226
def slogdet(a):
227
    """
228
    Compute sign and natural logarithm of determinant.
229
    
230
    Parameters:
231
    - a: array-like, square matrix (..., M, M)
232
    
233
    Returns:
234
    tuple: (sign, logdet)
235
    - sign: sign of determinant
236
    - logdet: natural log of absolute value of determinant
237
    """
238

239
def matrix_rank(M, tol=None, hermitian=False):
240
    """
241
    Return matrix rank using SVD method.
242
    
243
    Parameters:
244
    - M: array-like, input matrix
245
    - tol: float, threshold for singular values
246
    - hermitian: bool, if True, M is assumed Hermitian
247
    
248
    Returns:
249
    int: Rank of matrix
250
    """
251

252
def trace(a, offset=0, axis1=0, axis2=1, dtype=None, out=None):
253
    """
254
    Return sum along diagonals of array.
255
    
256
    Parameters:
257
    - a: array-like, input array
258
    - offset: int, offset from main diagonal
259
    - axis1, axis2: int, axes to take diagonal from
260
    - dtype: data type, type of returned array
261
    - out: cupy.ndarray, output array
262
    
263
    Returns:
264
    cupy.ndarray: Sum along diagonal
265
    """
266
```
267

268
### Solving Linear Systems
269

270
Solve linear equations and compute matrix inverses.
271

272
```python { .api }
273
def solve(a, b):
274
    """
275
    Solve linear matrix equation ax = b.
276
    
277
    Parameters:
278
    - a: array-like, coefficient matrix (..., M, M)
279
    - b: array-like, ordinate values (..., M) or (..., M, K)
280
    
281
    Returns:
282
    cupy.ndarray: Solution x to ax = b
283
    
284
    Raises:
285
    cupy.linalg.LinAlgError: If a is singular
286
    """
287

288
def lstsq(a, b, rcond=None):
289
    """
290
    Compute least-squares solution to linear matrix equation.
291
    
292
    Parameters:
293
    - a: array-like, coefficient matrix (M, N)
294
    - b: array-like, ordinate values (M,) or (M, K)
295
    - rcond: float, cutoff for singular values
296
    
297
    Returns:
298
    tuple: (x, residuals, rank, s)
299
    - x: least-squares solution
300
    - residuals: sum of squared residuals
301
    - rank: rank of a
302
    - s: singular values of a
303
    """
304

305
def inv(a):
306
    """
307
    Compute multiplicative inverse of matrix.
308
    
309
    Parameters:
310
    - a: array-like, square matrix (..., M, M)
311
    
312
    Returns:
313
    cupy.ndarray: Multiplicative inverse of a
314
    
315
    Raises:
316
    cupy.linalg.LinAlgError: If a is singular
317
    """
318

319
def pinv(a, rcond=1e-15, hermitian=False):
320
    """
321
    Compute Moore-Penrose pseudoinverse of matrix.
322
    
323
    Parameters:
324
    - a: array-like, matrix to invert (..., M, N)
325
    - rcond: float, cutoff for singular values
326
    - hermitian: bool, if True, a is assumed Hermitian
327
    
328
    Returns:
329
    cupy.ndarray: Pseudoinverse of a (..., N, M)
330
    """
331

332
def tensorsolve(a, b, axes=None):
333
    """
334
    Solve tensor equation a x = b for x.
335
    
336
    Parameters:
337
    - a: array-like, coefficient tensor
338
    - b: array-like, right-hand side tensor
339
    - axes: list of ints, axes in a to reorder to right
340
    
341
    Returns:
342
    cupy.ndarray: Solution tensor x
343
    """
344

345
def tensorinv(a, ind=2):
346
    """
347
    Compute inverse of N-dimensional array.
348
    
349
    Parameters:
350
    - a: array-like, tensor to invert
351
    - ind: int, number of first indices that are involved in inverse
352
    
353
    Returns:
354
    cupy.ndarray: Inverse of a
355
    """
356
```
357

358
### Matrix Powers
359

360
Compute integer powers of square matrices.
361

362
```python { .api }
363
def matrix_power(a, n):
364
    """
365
    Raise square matrix to integer power.
366
    
367
    Parameters:
368
    - a: array-like, square matrix (..., M, M)
369
    - n: int, exponent (can be negative)
370
    
371
    Returns:
372
    cupy.ndarray: a raised to power n
373
    
374
    Raises:
375
    cupy.linalg.LinAlgError: If n < 0 and a is singular
376
    """
377
```
378

379
### Einstein Summation
380

381
Advanced tensor operations using Einstein summation notation.
382

383
```python { .api }
384
def einsum(subscripts, *operands, out=None, dtype=None, order='K', casting='safe', optimize=False):
385
    """
386
    Evaluates Einstein summation convention on operands.
387
    
388
    Parameters:
389
    - subscripts: str, specifies subscripts for summation
390
    - operands: list of array-like, arrays for operation
391
    - out: cupy.ndarray, output array
392
    - dtype: data type, output data type
393
    - order: {'C', 'F', 'A', 'K'}, memory layout
394
    - casting: {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, casting rule
395
    - optimize: {False, True, 'greedy', 'optimal'}, path optimization
396
    
397
    Returns:
398
    cupy.ndarray: Calculation based on Einstein summation convention
399
    """
400
```
401

402
## Usage Examples
403

404
### Basic Linear Algebra Operations
405

406
```python
407
import cupy as cp
408

409
# Matrix multiplication
410
A = cp.random.rand(1000, 500)
411
B = cp.random.rand(500, 800)
412
C = cp.dot(A, B)  # or cp.matmul(A, B)
413

414
# Vector operations
415
x = cp.array([1, 2, 3])
416
y = cp.array([4, 5, 6])
417
dot_product = cp.dot(x, y)
418
cross_product = cp.cross(x, y)
419

420
# Matrix decompositions
421
symmetric_matrix = A @ A.T
422
eigenvals, eigenvecs = cp.linalg.eigh(symmetric_matrix)
423

424
U, s, Vh = cp.linalg.svd(A)
425
Q, R = cp.linalg.qr(A)
426

427
# Solving linear systems
428
x = cp.linalg.solve(symmetric_matrix, cp.random.rand(1000))
429
x_lstsq = cp.linalg.lstsq(A, cp.random.rand(1000))[0]
430

431
# Matrix properties
432
det_A = cp.linalg.det(symmetric_matrix)
433
norm_A = cp.linalg.norm(A)
434
rank_A = cp.linalg.matrix_rank(A)
435
```
436

437
### Advanced Operations
438

439
```python
440
import cupy as cp
441

442
# Einstein summation for complex tensor operations
443
a = cp.random.rand(3, 4, 5)
444
b = cp.random.rand(4, 5, 6)
445

446
# Matrix multiplication using einsum
447
result = cp.einsum('ijk,jkl->il', a, b)
448

449
# Batch operations
450
batch_matrices = cp.random.rand(10, 100, 100)
451
batch_vectors = cp.random.rand(10, 100)
452

453
# Solve multiple systems simultaneously
454
solutions = cp.linalg.solve(batch_matrices, batch_vectors)
455

456
# Compute eigenvalues for multiple matrices
457
eigenvalues = cp.linalg.eigvalsh(batch_matrices)
458
```
459

460
## Exception Handling
461

462
```python { .api }
463
class LinAlgError(Exception):
464
    """
465
    Exception raised for linear algebra errors.
466
    
467
    Raised when:
468
    - Matrix is singular (not invertible)
469
    - Matrix is not positive definite (for Cholesky)
470
    - Convergence fails in iterative algorithms
471
    """
472
```