0
# Linear Algebra
1

2
GPU-accelerated linear algebra operations providing high-performance matrix computations, decompositions, eigenvalue analysis, and equation solving using cuBLAS, cuSOLVER, and custom CUDA implementations.
3

4
## Capabilities
5

6
### Matrix Products
7

8
High-performance matrix multiplication and tensor operations.
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 array
19
    
20
    Returns:
21
    cupy.ndarray, dot product result
22
    """
23

24
def matmul(x1, x2, out=None):
25
    """
26
    Matrix product of two arrays.
27
    
28
    Parameters:
29
    - x1: array-like, first input array
30
    - x2: array-like, second input array
31
    - out: ndarray, optional output array
32
    
33
    Returns:
34
    cupy.ndarray, matrix product
35
    """
36

37
def inner(a, b):
38
    """
39
    Inner product of two arrays.
40
    
41
    Parameters:
42
    - a: array-like, first input array
43
    - b: array-like, second input array
44
    
45
    Returns:
46
    cupy.ndarray, inner product
47
    """
48

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

62
def kron(a, b):
63
    """
64
    Kronecker product of two arrays.
65
    
66
    Parameters:
67
    - a: array-like, first input array
68
    - b: array-like, second input array
69
    
70
    Returns:
71
    cupy.ndarray, Kronecker product
72
    """
73

74
def cross(a, b, axisa=-1, axisb=-1, axisc=-1, axis=None):
75
    """
76
    Cross product of two arrays.
77
    
78
    Parameters:
79
    - a: array-like, first input array
80
    - b: array-like, second input array
81
    - axisa: int, axis of a along which to take cross product
82
    - axisb: int, axis of b along which to take cross product
83
    - axisc: int, axis of output along which cross product is computed
84
    - axis: int, unified axis specification
85
    
86
    Returns:
87
    cupy.ndarray, cross product
88
    """
89

90
def tensordot(a, b, axes=2):
91
    """
92
    Compute tensor dot product along specified axes.
93
    
94
    Parameters:
95
    - a: array-like, first tensor
96
    - b: array-like, second tensor
97
    - axes: int or array-like, axes to sum over
98
    
99
    Returns:
100
    cupy.ndarray, tensor dot product
101
    """
102

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

115
def einsum(subscripts, *operands, out=None, dtype=None, order='K', casting='safe', optimize=False):
116
    """
117
    Evaluate Einstein summation convention on operands.
118
    
119
    Parameters:
120
    - subscripts: str, Einstein summation subscripts
121
    - operands: sequence of arrays
122
    - out: ndarray, optional output array
123
    - dtype: data type, optional
124
    - order: memory layout
125
    - casting: casting mode
126
    - optimize: bool or str, optimization strategy
127
    
128
    Returns:
129
    cupy.ndarray, Einstein sum result
130
    """
131
```
132

133
### Matrix Decompositions
134

135
Advanced matrix factorizations for numerical analysis and solving linear systems.
136

137
```python { .api }
138
def linalg.svd(a, full_matrices=True, compute_uv=True, hermitian=False):
139
    """
140
    Singular Value Decomposition.
141
    
142
    Parameters:
143
    - a: array-like, input matrix
144
    - full_matrices: bool, return full-sized U and V matrices
145
    - compute_uv: bool, compute U and V in addition to s
146
    - hermitian: bool, assume input is Hermitian
147
    
148
    Returns:
149
    tuple, (U, s, Vh) where a = U @ diag(s) @ Vh
150
    """
151

152
def linalg.qr(a, mode='reduced'):
153
    """
154
    QR decomposition of matrix.
155
    
156
    Parameters:
157
    - a: array-like, input matrix
158
    - mode: str, decomposition mode ('reduced', 'complete', 'economic', 'raw')
159
    
160
    Returns:
161
    tuple, (Q, R) where a = Q @ R
162
    """
163

164
def linalg.cholesky(a):
165
    """
166
    Cholesky decomposition of positive-definite matrix.
167
    
168
    Parameters:
169
    - a: array-like, positive-definite matrix
170
    
171
    Returns:
172
    cupy.ndarray, lower triangular Cholesky factor L where a = L @ L.T
173
    """
174
```
175

176
### Eigenvalues and Eigenvectors
177

178
Eigenvalue computations for symmetric and Hermitian matrices.
179

180
```python { .api }
181
def linalg.eigh(a, UPLO='L'):
182
    """
183
    Eigenvalues and eigenvectors of symmetric/Hermitian matrix.
184
    
185
    Parameters:
186
    - a: array-like, symmetric or Hermitian matrix
187
    - UPLO: str, use upper ('U') or lower ('L') triangle
188
    
189
    Returns:
190
    tuple, (eigenvalues, eigenvectors)
191
    """
192

193
def linalg.eigvalsh(a, UPLO='L'):
194
    """
195
    Eigenvalues of symmetric/Hermitian matrix.
196
    
197
    Parameters:
198
    - a: array-like, symmetric or Hermitian matrix
199
    - UPLO: str, use upper ('U') or lower ('L') triangle
200
    
201
    Returns:
202
    cupy.ndarray, eigenvalues in ascending order
203
    """
204
```
205

206
### Matrix Norms and Properties
207

208
Functions for computing matrix norms, determinants, and other matrix properties.
209

210
```python { .api }
211
def linalg.norm(x, ord=None, axis=None, keepdims=False):
212
    """
213
    Matrix or vector norm.
214
    
215
    Parameters:
216
    - x: array-like, input array
217
    - ord: order of norm (None, int, inf, -inf, 'fro', 'nuc')
218
    - axis: int or tuple of ints, axis along which to compute norm
219
    - keepdims: bool, keep reduced dimensions
220
    
221
    Returns:
222
    cupy.ndarray, norm of input
223
    """
224

225
def linalg.det(a):
226
    """
227
    Compute determinant of array.
228
    
229
    Parameters:
230
    - a: array-like, square matrix
231
    
232
    Returns:
233
    cupy.ndarray, determinant of input matrix
234
    """
235

236
def linalg.slogdet(a):
237
    """
238
    Compute sign and logarithm of determinant.
239
    
240
    Parameters:
241
    - a: array-like, square matrix
242
    
243
    Returns:
244
    tuple, (sign, logdet) where det = sign * exp(logdet)
245
    """
246

247
def linalg.matrix_rank(M, tol=None, hermitian=False):
248
    """
249
    Return matrix rank using SVD method.
250
    
251
    Parameters:
252
    - M: array-like, input matrix
253
    - tol: float, threshold for small singular values
254
    - hermitian: bool, assume M is Hermitian
255
    
256
    Returns:
257
    int, rank of matrix
258
    """
259

260
def trace(a, offset=0, axis1=0, axis2=1, dtype=None, out=None):
261
    """
262
    Return sum along diagonals of array.
263
    
264
    Parameters:
265
    - a: array-like, input array
266
    - offset: int, diagonal offset
267
    - axis1: int, first axis for 2-D sub-arrays
268
    - axis2: int, second axis for 2-D sub-arrays
269
    - dtype: data type of output
270
    - out: ndarray, optional output array
271
    
272
    Returns:
273
    cupy.ndarray, sum of diagonal elements
274
    """
275
```
276

277
### Solving Linear Equations
278

279
Functions for solving linear systems and matrix inversions.
280

281
```python { .api }
282
def linalg.solve(a, b):
283
    """
284
    Solve linear matrix equation ax = b.
285
    
286
    Parameters:
287
    - a: array-like, coefficient matrix
288
    - b: array-like, dependent variable values
289
    
290
    Returns:
291
    cupy.ndarray, solution to system ax = b
292
    """
293

294
def linalg.lstsq(a, b, rcond=None):
295
    """
296
    Return least-squares solution to linear matrix equation.
297
    
298
    Parameters:
299
    - a: array-like, coefficient matrix
300
    - b: array-like, dependent variable values
301
    - rcond: float, cutoff for small singular values
302
    
303
    Returns:
304
    tuple, (solution, residuals, rank, singular_values)
305
    """
306

307
def linalg.inv(a):
308
    """
309
    Compute multiplicative inverse of matrix.
310
    
311
    Parameters:
312
    - a: array-like, square matrix to invert
313
    
314
    Returns:
315
    cupy.ndarray, multiplicative inverse of input
316
    """
317

318
def linalg.pinv(a, rcond=1e-15, hermitian=False):
319
    """
320
    Compute Moore-Penrose pseudoinverse.
321
    
322
    Parameters:
323
    - a: array-like, matrix to pseudoinvert
324
    - rcond: float, cutoff for small singular values
325
    - hermitian: bool, assume a is Hermitian
326
    
327
    Returns:
328
    cupy.ndarray, pseudoinverse of input
329
    """
330

331
def linalg.tensorsolve(a, b, axes=None):
332
    """
333
    Solve tensor equation a x = b for x.
334
    
335
    Parameters:
336
    - a: array-like, coefficient tensor
337
    - b: array-like, dependent variable tensor
338
    - axes: tuple of ints, axes to reorder in a
339
    
340
    Returns:
341
    cupy.ndarray, solution tensor
342
    """
343

344
def linalg.tensorinv(a, ind=2):
345
    """
346
    Compute inverse of N-dimensional array.
347
    
348
    Parameters:
349
    - a: array-like, tensor to invert
350
    - ind: int, number of first indices forming square matrix
351
    
352
    Returns:
353
    cupy.ndarray, inverse of input tensor
354
    """
355
```
356

357
### Matrix Power Operations
358

359
Functions for computing matrix powers and related operations.
360

361
```python { .api }
362
def linalg.matrix_power(a, n):
363
    """
364
    Raise square matrix to integer power.
365
    
366
    Parameters:
367
    - a: array-like, square matrix
368
    - n: int, power to raise matrix to
369
    
370
    Returns:
371
    cupy.ndarray, a raised to power n
372
    """
373
```
374

375
## Usage Examples
376

377
### Basic Matrix Operations
378

379
```python
380
import cupy as cp
381

382
# Create matrices
383
A = cp.random.random((1000, 1000))
384
B = cp.random.random((1000, 1000))
385
x = cp.random.random(1000)
386

387
# Matrix multiplication
388
C = cp.dot(A, B)  # or A @ B
389
y = cp.dot(A, x)  # Matrix-vector product
390

391
# Matrix operations
392
At = A.T  # Transpose
393
trace_A = cp.trace(A)
394
norm_A = cp.linalg.norm(A)
395
det_A = cp.linalg.det(A)
396
```
397

398
### Solving Linear Systems
399

400
```python
401
import cupy as cp
402

403
# Solve Ax = b
404
A = cp.random.random((100, 100))
405
b = cp.random.random(100)
406

407
# Direct solution
408
x = cp.linalg.solve(A, b)
409

410
# Least squares solution for overdetermined system
411
A_over = cp.random.random((150, 100))
412
b_over = cp.random.random(150)
413
x_ls, residuals, rank, s = cp.linalg.lstsq(A_over, b_over, rcond=None)
414

415
# Matrix inversion
416
A_inv = cp.linalg.inv(A)
417
A_pinv = cp.linalg.pinv(A_over)  # Pseudoinverse
418
```
419

420
### Matrix Decompositions
421

422
```python
423
import cupy as cp
424

425
# Create symmetric positive definite matrix
426
A = cp.random.random((100, 100))
427
A = A @ A.T + cp.eye(100)  # Ensure positive definite
428

429
# Cholesky decomposition
430
L = cp.linalg.cholesky(A)
431
# Verify: A ≈ L @ L.T
432

433
# SVD decomposition
434
U, s, Vh = cp.linalg.svd(A, full_matrices=False)
435
# Verify: A ≈ U @ cp.diag(s) @ Vh
436

437
# QR decomposition
438
Q, R = cp.linalg.qr(A)
439
# Verify: A ≈ Q @ R
440

441
# Eigenvalue decomposition
442
eigenvals, eigenvecs = cp.linalg.eigh(A)
443
```
444

445
### Advanced Linear Algebra
446

447
```python
448
import cupy as cp
449

450
# Einstein summation
451
A = cp.random.random((10, 20))
452
B = cp.random.random((20, 30))
453
C = cp.random.random((30, 10))
454

455
# Matrix chain multiplication using einsum
456
result = cp.einsum('ij,jk,kl->il', A, B, C)
457

458
# Tensor operations
459
T1 = cp.random.random((5, 4, 3))
460
T2 = cp.random.random((3, 2))
461

462
# Tensor contraction
463
contracted = cp.tensordot(T1, T2, axes=([2], [0]))
464

465
# Kronecker product
466
small_A = cp.array([[1, 2], [3, 4]])
467
small_B = cp.array([[5, 6], [7, 8]])
468
kron_product = cp.kron(small_A, small_B)
469
```
470

471
### Performance Optimization
472

473
```python
474
import cupy as cp
475

476
# Use appropriate data types
477
A_float32 = cp.random.random((2000, 2000), dtype=cp.float32)
478
B_float32 = cp.random.random((2000, 2000), dtype=cp.float32)
479

480
# Preallocate output arrays
481
C = cp.empty((2000, 2000), dtype=cp.float32)
482
cp.dot(A_float32, B_float32, out=C)
483

484
# Use in-place operations when possible
485
A_float32 *= 2.0  # In-place scaling
486

487
# Optimize memory layout
488
A_fortran = cp.asfortranarray(A_float32)  # For column-major operations
489
```