0
# Linear Algebra
1

2
High-performance linear algebra operations leveraging cuBLAS and cuSOLVER libraries for matrix operations, decompositions, and solving linear systems. CuPy provides comprehensive GPU-accelerated linear algebra functionality with NVIDIA's optimized libraries.
3

4
## Capabilities
5

6
### Matrix Operations
7

8
Core matrix multiplication and transformation operations.
9

10
```python { .api }
11
def dot(a, b, out=None):
12
    """Dot product of two arrays.
13
    
14
    Args:
15
        a: First input array
16
        b: Second input array  
17
        out: Output array
18
        
19
    Returns:
20
        cupy.ndarray: Dot product result
21
    """
22

23
def matmul(x1, x2, out=None, **kwargs):
24
    """Matrix product of two arrays.
25
    
26
    Args:
27
        x1, x2: Input arrays
28
        out: Output array
29
        **kwargs: Additional arguments
30
        
31
    Returns:
32
        cupy.ndarray: Matrix product
33
    """
34

35
def inner(a, b):
36
    """Inner product of two arrays."""
37

38
def outer(a, b, out=None):
39
    """Compute outer product of two vectors."""
40

41
def tensordot(a, b, axes=2):
42
    """Compute tensor dot product along specified axes."""
43

44
def kron(a, b):
45
    """Kronecker product of two arrays."""
46
```
47

48
### Matrix Properties and Norms
49

50
Calculate matrix properties and various norms.
51

52
```python { .api }
53
def norm(x, ord=None, axis=None, keepdims=False):
54
    """Matrix or vector norm.
55
    
56
    Args:
57
        x: Input array
58
        ord: Order of norm (None, 'fro', 'nuc', inf, -inf, 1, -1, 2, -2)
59
        axis: Axis for norm calculation
60
        keepdims: Keep reduced dimensions
61
        
62
    Returns:
63
        cupy.ndarray or float: Norm value(s)
64
    """
65

66
def trace(a, offset=0, axis1=0, axis2=1, dtype=None, out=None):
67
    """Return sum along diagonals of array.
68
    
69
    Args:
70
        a: Input array
71
        offset: Diagonal offset
72
        axis1, axis2: Axes to take diagonal from
73
        dtype: Output data type
74
        out: Output array
75
        
76
    Returns:
77
        cupy.ndarray: Sum of diagonal elements
78
    """
79

80
def det(a):
81
    """Compute determinant of array.
82
    
83
    Args:
84
        a: Input array
85
        
86
    Returns:
87
        cupy.ndarray: Determinant
88
    """
89

90
def slogdet(a):
91
    """Compute sign and logarithm of determinant.
92
    
93
    Args:
94
        a: Input array
95
        
96
    Returns:
97
        tuple: (sign, logdet) arrays
98
    """
99

100
def matrix_rank(M, tol=None, hermitian=False):
101
    """Return matrix rank of array using SVD."""
102
```
103

104
### Linear System Solving
105

106
Solve linear systems and matrix equations.
107

108
```python { .api }
109
def solve(a, b):
110
    """Solve linear matrix equation ax = b.
111
    
112
    Args:
113
        a: Coefficient matrix
114
        b: Ordinate values
115
        
116
    Returns:
117
        cupy.ndarray: Solution to system
118
    """
119

120
def lstsq(a, b, rcond=None):
121
    """Return least-squares solution to linear matrix equation.
122
    
123
    Args:
124
        a: Coefficient matrix
125
        b: Ordinate values
126
        rcond: Cutoff for small singular values
127
        
128
    Returns:
129
        tuple: (solution, residuals, rank, singular_values)
130
    """
131

132
def solve_triangular(a, b, lower=False, unit_diagonal=False, overwrite_b=False, debug=None):
133
    """Solve triangular system of equations."""
134

135
def tensorsolve(a, b, axes=None):
136
    """Solve tensor equation a x = b for x."""
137
```
138

139
### Matrix Inversion and Pseudo-inverse
140

141
Compute matrix inverses and pseudo-inverses.
142

143
```python { .api }
144
def inv(a):
145
    """Compute multiplicative inverse of matrix.
146
    
147
    Args:
148
        a: Matrix to invert
149
        
150
    Returns:
151
        cupy.ndarray: Inverse matrix
152
    """
153

154
def pinv(a, rcond=1e-15, hermitian=False):
155
    """Compute Moore-Penrose pseudo-inverse.
156
    
157
    Args:
158
        a: Matrix to pseudo-invert
159
        rcond: Cutoff for small singular values
160
        hermitian: Whether matrix is Hermitian
161
        
162
    Returns:
163
        cupy.ndarray: Pseudo-inverse matrix
164
    """
165

166
def tensorinv(a, ind=2):
167
    """Compute 'inverse' of N-dimensional array."""
168
```
169

170
### Eigenvalues and Eigenvectors  
171

172
Compute eigenvalues and eigenvectors of matrices.
173

174
```python { .api }
175
def eigh(a, UPLO='L'):
176
    """Return eigenvalues and eigenvectors of Hermitian matrix.
177
    
178
    Args:
179
        a: Hermitian matrix
180
        UPLO: Whether to use upper ('U') or lower ('L') triangle
181
        
182
    Returns:
183
        tuple: (eigenvalues, eigenvectors)
184
    """
185

186
def eigvalsh(a, UPLO='L'):
187
    """Compute eigenvalues of Hermitian matrix."""
188
```
189

190
### Matrix Decompositions
191

192
Various matrix factorizations and decompositions.
193

194
```python { .api }
195
def svd(a, full_matrices=True, compute_uv=True):
196
    """Singular Value Decomposition.
197
    
198
    Args:
199
        a: Input matrix
200
        full_matrices: Whether to compute full or reduced SVD
201
        compute_uv: Whether to compute U and Vh matrices
202
        
203
    Returns:
204
        tuple: (U, s, Vh) or just s if compute_uv=False
205
    """
206

207
def qr(a, mode='reduced'):
208
    """Compute QR decomposition of matrix.
209
    
210
    Args:
211
        a: Input matrix
212
        mode: Decomposition mode ('reduced', 'complete', 'r', 'raw')
213
        
214
    Returns:
215
        tuple: (Q, R) matrices or modified based on mode
216
    """
217

218
def cholesky(a):
219
    """Cholesky decomposition of positive-definite matrix.
220
    
221
    Args:
222
        a: Positive-definite matrix
223
        
224
    Returns:
225
        cupy.ndarray: Lower triangular Cholesky factor
226
    """
227
228
```
229

230
### Specialized Matrix Functions
231

232
Specialized operations for specific matrix types.
233

234
```python { .api }
235
def matrix_power(a, n):
236
    """Raise square matrix to integer power.
237
    
238
    Args:
239
        a: Square matrix
240
        n: Integer power
241
        
242
    Returns:
243
        cupy.ndarray: Matrix power a^n
244
    """
245
246
```
247

248
### Vector Operations
249

250
Operations specific to vectors and 1D arrays.
251

252
```python { .api }
253
def cross(a, b, axisa=-1, axisb=-1, axisc=-1, axis=None):
254
    """Return cross product of two vectors.
255
    
256
    Args:
257
        a, b: Input vectors
258
        axisa, axisb, axisc: Axis specifications
259
        axis: Axis of vectors
260
        
261
    Returns:
262
        cupy.ndarray: Cross product
263
    """
264

265
def vdot(a, b):
266
    """Return dot product of two vectors."""
267
```
268

269
## Usage Examples
270

271
### Basic Matrix Operations
272

273
```python
274
import cupy as cp
275

276
# Create matrices
277
A = cp.random.random((3, 3))
278
B = cp.random.random((3, 3))
279
x = cp.random.random(3)
280

281
# Matrix multiplication
282
C = cp.dot(A, B)          # Matrix-matrix multiplication
283
y = cp.dot(A, x)          # Matrix-vector multiplication
284
C_alt = cp.matmul(A, B)   # Alternative matrix multiplication
285

286
# Matrix properties
287
trace_A = cp.trace(A)     # Sum of diagonal elements
288
det_A = cp.det(A)         # Determinant
289
norm_A = cp.norm(A)       # Frobenius norm
290
norm_2 = cp.norm(A, ord=2) # 2-norm (spectral norm)
291
```
292

293
### Solving Linear Systems
294

295
```python
296
# Solve Ax = b
297
A = cp.array([[3, 1], [1, 2]], dtype=cp.float32)
298
b = cp.array([9, 8], dtype=cp.float32)
299

300
# Direct solution
301
x = cp.solve(A, b)  # x = [2, 3]
302

303
# Least squares solution for overdetermined systems
304
A_over = cp.random.random((10, 3))  # 10 equations, 3 unknowns
305
b_over = cp.random.random(10)
306
x_ls, residuals, rank, s = cp.lstsq(A_over, b_over)
307

308
# Matrix inversion
309
A_inv = cp.inv(A)
310
x_inv = cp.dot(A_inv, b)  # Alternative solution method
311
```
312

313
### Eigenvalue Problems
314

315
```python
316
# Symmetric matrix eigenvalues
317
symmetric_matrix = cp.array([[4, -2], [-2, 1]], dtype=cp.float32)
318
eigenvals, eigenvecs = cp.eigh(symmetric_matrix)
319

320
# Note: CuPy only supports eigenvalue computation for Hermitian matrices
321
# For general matrices, use NumPy on CPU or specialized libraries
322
```
323

324
### Matrix Decompositions
325

326
```python
327
# SVD decomposition
328
matrix = cp.random.random((4, 3))
329
U, s, Vh = cp.svd(matrix, full_matrices=False)
330
reconstructed = cp.dot(U * s, Vh)  # Reconstruction
331

332
# QR decomposition
333
tall_matrix = cp.random.random((5, 3))
334
Q, R = cp.qr(tall_matrix)
335

336
# Cholesky decomposition for positive definite matrix
337
pos_def = cp.dot(matrix.T, matrix)  # Ensure positive definite
338
L = cp.cholesky(pos_def)
339
```
340

341
### Advanced Linear Algebra
342

343
```python
344
# Matrix functions
345
matrix = cp.array([[1, 2], [3, 4]], dtype=cp.float32)
346

347
# Matrix powers
348
matrix_squared = cp.matrix_power(matrix, 2)
349
# Vector operations
350
v1 = cp.array([1, 2, 3])
351
v2 = cp.array([4, 5, 6])
352

353
cross_product = cp.cross(v1, v2)  # Cross product
354
dot_product = cp.vdot(v1, v2)     # Dot product
355

356
# Multi-matrix dot product
357
matrices = [cp.random.random((3, 4)), 
358
           cp.random.random((4, 5)), 
359
           cp.random.random((5, 2))]
360
# Chain multiplication using matmul
361
result = cp.matmul(cp.matmul(matrices[0], matrices[1]), matrices[2])
362
```
363

364
### Performance Optimization Tips
365

366
```python
367
# Use appropriate data types for better performance
368
A_f32 = cp.array(A, dtype=cp.float32)  # Single precision
369
A_f64 = cp.array(A, dtype=cp.float64)  # Double precision
370

371
# Prefer matmul over dot for matrix multiplication
372
result = cp.matmul(A, B)  # Preferred for matrix operations
373

374
# Use in-place operations when possible
375
cp.dot(A, B, out=C)  # Write result directly to C
376

377
# For large matrices, consider blocked algorithms
378
# CuPy automatically uses optimized BLAS routines
379
```
380

381
### Specialized Applications
382

383
```python
384
# Solving multiple systems with same coefficient matrix
385
A = cp.random.random((100, 100))
386
multiple_b = cp.random.random((100, 50))  # 50 different RHS vectors
387

388
# Efficient solution for multiple RHS
389
solutions = cp.solve(A, multiple_b)
390

391
# Rank analysis
392
rank = cp.matrix_rank(A)
393
if rank < A.shape[0]:
394
    print("Matrix is rank deficient")
395
```