0
# Linear Algebra Operations
1

2
Comprehensive linear algebra operations including dense and sparse vectors, dense matrices, and BLAS routines for high-performance mathematical computations. The linear algebra package provides the foundation for machine learning algorithms with optimized implementations.
3

4
## Capabilities
5

6
### Vector Base Class
7

8
Abstract base class for all vector types, providing common interface for mathematical operations on both dense and sparse vectors.
9

10
```java { .api }
11
/**
12
 * Base class for dense and sparse vector operations
13
 */
14
public abstract class Vector implements Serializable {
15
    /** Get vector size */
16
    public abstract int size();
17
    
18
    /** Get element at index */
19
    public abstract double get(int i);
20
    
21
    /** Set element at index */
22
    public abstract void set(int i, double val);
23
    
24
    /** Add to element at index */
25
    public abstract void add(int i, double val);
26
    
27
    /** L1 norm (sum of absolute values) */
28
    public abstract double normL1();
29
    
30
    /** Infinity norm (maximum absolute value) */
31
    public abstract double normInf();
32
    
33
    /** L2 norm (Euclidean norm) */
34
    public abstract double normL2();
35
    
36
    /** L2 norm squared */
37
    public abstract double normL2Square();
38
    
39
    /** Scale vector by scalar (immutable) */
40
    public abstract Vector scale(double v);
41
    
42
    /** Scale vector by scalar (mutable) */
43
    public abstract void scaleEqual(double v);
44
    
45
    /** Normalize vector by p-norm (mutable) */
46
    public abstract void normalizeEqual(double p);
47
    
48
    /** Standardize vector with mean and standard deviation (mutable) */
49
    public abstract void standardizeEqual(double mean, double stdvar);
50
    
51
    /** Add element to head of vector */
52
    public abstract Vector prefix(double v);
53
    
54
    /** Add element to tail of vector */
55
    public abstract Vector append(double v);
56
    
57
    /** Add vectors (immutable) */
58
    public abstract Vector plus(Vector vec);
59
    
60
    /** Subtract vectors (immutable) */
61
    public abstract Vector minus(Vector vec);
62
    
63
    /** Dot product */
64
    public abstract double dot(Vector vec);
65
    
66
    /** Get vector iterator */
67
    public abstract VectorIterator iterator();
68
    
69
    /** Extract subvector by indices */
70
    public abstract Vector slice(int[] indexes);
71
    
72
    /** Outer product with itself */
73
    public abstract DenseMatrix outer();
74
}
75
```
76

77
### DenseVector Class
78

79
Dense vector implementation using double array storage for high-performance operations on fully populated vectors.
80

81
```java { .api }
82
/**
83
 * Dense vector implementation with double array storage
84
 */
85
public class DenseVector extends Vector {
86
    /** Double array data storage */
87
    public double[] data;
88
    
89
    /** Empty constructor */
90
    public DenseVector();
91
    
92
    /** Size constructor with zero initialization */
93
    public DenseVector(int n);
94
    
95
    /** Data constructor from array */
96
    public DenseVector(double[] data);
97
    
98
    /** Get data array */
99
    public double[] getData();
100
    
101
    /** Set data array */
102
    public void setData(double[] data);
103
    
104
    /** Create ones vector */
105
    public static DenseVector ones(int n);
106
    
107
    /** Create zeros vector */
108
    public static DenseVector zeros(int n);
109
    
110
    /** Create random vector with uniform distribution [0,1) */
111
    public static DenseVector rand(int n);
112
    
113
    /** Clone vector */
114
    public DenseVector clone();
115
    
116
    /** Copy from another vector (mutable) */
117
    public void setEqual(DenseVector other);
118
    
119
    /** Add vector (mutable) */
120
    public void plusEqual(Vector other);
121
    
122
    /** Subtract vector (mutable) */
123
    public void minusEqual(Vector other);
124
    
125
    /** Add scaled vector: this += alpha * other (mutable) */
126
    public void plusScaleEqual(Vector other, double alpha);
127
    
128
    /** Outer product with another dense vector */
129
    public DenseMatrix outer(DenseVector other);
130
}
131
```
132

133
**Usage Examples:**
134

135
```java
136
import org.apache.flink.ml.common.linalg.DenseVector;
137

138
// Create vectors
139
DenseVector v1 = new DenseVector(new double[]{1.0, 2.0, 3.0});
140
DenseVector v2 = DenseVector.ones(3);
141
DenseVector zeros = DenseVector.zeros(5);
142
DenseVector random = DenseVector.rand(4);
143

144
// Basic operations
145
double norm = v1.normL2();              // L2 norm
146
DenseVector scaled = v1.scale(2.0);     // Scale by 2
147
DenseVector sum = v1.plus(v2);          // Vector addition
148
double dotProduct = v1.dot(v2);         // Dot product
149

150
// Mutable operations
151
v1.scaleEqual(0.5);                     // Scale in-place
152
v1.plusEqual(v2);                       // Add in-place
153
v1.normalizeEqual(2.0);                 // L2 normalize
154

155
// Matrix operations
156
DenseMatrix outer = v1.outer(v2);       // Outer product
157
```
158

159
### SparseVector Class
160

161
Sparse vector implementation using indices and values arrays for memory-efficient storage of vectors with many zero elements.
162

163
```java { .api }
164
/**
165
 * Sparse vector implementation with indices and values arrays
166
 */
167
public class SparseVector extends Vector {
168
    /** Vector size */
169
    public int n;
170
    
171
    /** Non-zero indices */
172
    public int[] indices;
173
    
174
    /** Non-zero values */
175
    public double[] values;
176
    
177
    /** Empty constructor (undetermined size) */
178
    public SparseVector();
179
    
180
    /** Size constructor */
181
    public SparseVector(int n);
182
    
183
    /** Full constructor */
184
    public SparseVector(int n, int[] indices, double[] values);
185
    
186
    /** Map constructor */
187
    public SparseVector(int n, Map<Integer, Double> kv);
188
    
189
    /** Get indices array */
190
    public int[] getIndices();
191
    
192
    /** Get values array */
193
    public double[] getValues();
194
    
195
    /** Set vector size */
196
    public void setSize(int n);
197
    
198
    /** Get number of non-zero values */
199
    public int numberOfValues();
200
    
201
    /** Remove zero entries (cleanup) */
202
    public void removeZeroValues();
203
    
204
    /** Convert to dense vector */
205
    public DenseVector toDenseVector();
206
    
207
    /** Outer product with another sparse vector */
208
    public DenseMatrix outer(SparseVector other);
209
    
210
    /** Clone vector */
211
    public SparseVector clone();
212
}
213
```
214

215
**Usage Examples:**
216

217
```java
218
import org.apache.flink.ml.common.linalg.SparseVector;
219
import java.util.HashMap;
220
import java.util.Map;
221

222
// Create sparse vectors
223
int[] indices = {0, 2, 4};
224
double[] values = {1.0, 3.0, 5.0};
225
SparseVector sparse1 = new SparseVector(10, indices, values);
226

227
// From map
228
Map<Integer, Double> map = new HashMap<>();
229
map.put(1, 2.0);
230
map.put(5, 7.0);
231
SparseVector sparse2 = new SparseVector(10, map);
232

233
// Operations
234
double norm = sparse1.normL2();
235
int nonZeros = sparse1.numberOfValues();
236
DenseVector dense = sparse1.toDenseVector();
237

238
// Cleanup
239
sparse1.removeZeroValues();  // Remove explicit zeros
240
```
241

242
### DenseMatrix Class
243

244
Dense matrix implementation with column-major storage for efficient matrix operations and linear algebra computations.
245

246
```java { .api }
247
/**
248
 * Dense matrix implementation with column-major storage
249
 */
250
public class DenseMatrix implements Serializable {
251
    /** Row dimension */
252
    public int m;
253
    
254
    /** Column dimension */
255
    public int n;
256
    
257
    /** Data array (column-major) */
258
    public double[] data;
259
    
260
    /** Dimensions constructor */
261
    public DenseMatrix(int m, int n);
262
    
263
    /** Data constructor (column-major) */
264
    public DenseMatrix(int m, int n, double[] data);
265
    
266
    /** Data constructor with layout specification */
267
    public DenseMatrix(int m, int n, double[] data, boolean inRowMajor);
268
    
269
    /** 2D array constructor */
270
    public DenseMatrix(double[][] data);
271
    
272
    /** Create identity matrix */
273
    public static DenseMatrix eye(int n);
274
    
275
    /** Create m×n identity matrix */
276
    public static DenseMatrix eye(int m, int n);
277
    
278
    /** Create zero matrix */
279
    public static DenseMatrix zeros(int m, int n);
280
    
281
    /** Create ones matrix */
282
    public static DenseMatrix ones(int m, int n);
283
    
284
    /** Create random matrix with uniform distribution [0,1) */
285
    public static DenseMatrix rand(int m, int n);
286
    
287
    /** Create random symmetric matrix */
288
    public static DenseMatrix randSymmetric(int n);
289
    
290
    /** Get element at (i,j) */
291
    public double get(int i, int j);
292
    
293
    /** Set element at (i,j) */
294
    public void set(int i, int j, double s);
295
    
296
    /** Add to element at (i,j) */
297
    public void add(int i, int j, double s);
298
    
299
    /** Get data array */
300
    public double[] getData();
301
    
302
    /** Get 2D array copy */
303
    public double[][] getArrayCopy2D();
304
    
305
    /** Get 1D array copy with layout specification */
306
    public double[] getArrayCopy1D(boolean inRowMajor);
307
    
308
    /** Get row as array */
309
    public double[] getRow(int row);
310
    
311
    /** Get column as array */
312
    public double[] getColumn(int col);
313
    
314
    /** Select rows by indices */
315
    public DenseMatrix selectRows(int[] rows);
316
    
317
    /** Get sub-matrix */
318
    public DenseMatrix getSubMatrix(int m0, int m1, int n0, int n1);
319
    
320
    /** Set sub-matrix */
321
    public void setSubMatrix(DenseMatrix sub, int m0, int m1, int n0, int n1);
322
    
323
    /** Check if square matrix */
324
    public boolean isSquare();
325
    
326
    /** Check if symmetric matrix */
327
    public boolean isSymmetric();
328
    
329
    /** Get row count */
330
    public int numRows();
331
    
332
    /** Get column count */
333
    public int numCols();
334
    
335
    /** Sum all elements */
336
    public double sum();
337
    
338
    /** Scale matrix by scalar (immutable) */
339
    public DenseMatrix scale(double v);
340
    
341
    /** Scale matrix by scalar (mutable) */
342
    public void scaleEqual(double v);
343
    
344
    /** Add matrices (immutable) */
345
    public DenseMatrix plus(DenseMatrix mat);
346
    
347
    /** Add scalar to all elements (immutable) */
348
    public DenseMatrix plus(double alpha);
349
    
350
    /** Add matrix (mutable) */
351
    public void plusEquals(DenseMatrix mat);
352
    
353
    /** Add scalar to all elements (mutable) */
354
    public void plusEquals(double alpha);
355
    
356
    /** Subtract matrices (immutable) */
357
    public DenseMatrix minus(DenseMatrix mat);
358
    
359
    /** Subtract matrix (mutable) */
360
    public void minusEquals(DenseMatrix mat);
361
    
362
    /** Matrix multiplication */
363
    public DenseMatrix multiplies(DenseMatrix mat);
364
    
365
    /** Matrix-vector multiplication */
366
    public DenseVector multiplies(DenseVector x);
367
    
368
    /** Matrix-sparse vector multiplication */
369
    public DenseVector multiplies(SparseVector x);
370
    
371
    /** Matrix transpose */
372
    public DenseMatrix transpose();
373
    
374
    /** Clone matrix */
375
    public DenseMatrix clone();
376
}
377
```
378

379
**Usage Examples:**
380

381
```java
382
import org.apache.flink.ml.common.linalg.DenseMatrix;
383
import org.apache.flink.ml.common.linalg.DenseVector;
384

385
// Create matrices
386
DenseMatrix identity = DenseMatrix.eye(3);
387
DenseMatrix zeros = DenseMatrix.zeros(3, 4);
388
DenseMatrix random = DenseMatrix.rand(2, 2);
389

390
// From 2D array
391
double[][] array2d = {{1, 2}, {3, 4}};
392
DenseMatrix mat = new DenseMatrix(array2d);
393

394
// Basic operations
395
double element = mat.get(0, 1);          // Get element
396
mat.set(1, 0, 5.0);                      // Set element
397
int rows = mat.numRows();                 // Get dimensions
398
boolean square = mat.isSquare();          // Check properties
399

400
// Matrix operations
401
DenseMatrix scaled = mat.scale(2.0);      // Scale
402
DenseMatrix sum = mat.plus(identity);     // Addition
403
DenseMatrix product = mat.multiplies(identity); // Multiplication
404
DenseMatrix transposed = mat.transpose(); // Transpose
405

406
// Matrix-vector operations
407
DenseVector vector = new DenseVector(new double[]{1, 2});
408
DenseVector result = mat.multiplies(vector);
409
```
410

411
### BLAS Operations
412

413
Basic Linear Algebra Subprograms providing high-performance implementations of common linear algebra operations.
414

415
```java { .api }
416
/**
417
 * BLAS routines for vector and matrix operations
418
 */
419
public class BLAS {
420
    /** Sum of absolute values (L1 norm) */
421
    public static double asum(DenseVector x);
422
    public static double asum(SparseVector x);
423
    
424
    /** y += a*x (AXPY operation) */
425
    public static void axpy(double a, DenseVector x, DenseVector y);
426
    public static void axpy(double a, SparseVector x, DenseVector y);
427
    public static void axpy(double a, DenseMatrix x, DenseMatrix y);
428
    
429
    /** Dot product */
430
    public static double dot(DenseVector x, DenseVector y);
431
    
432
    /** Scale: x = a*x */
433
    public static void scal(double a, DenseVector x);
434
    public static void scal(double a, SparseVector x);
435
    public static void scal(double a, DenseMatrix x);
436
    
437
    /** General matrix multiplication: C = alpha*op(A)*op(B) + beta*C */
438
    public static void gemm(double alpha, DenseMatrix matA, boolean transA,
439
                           DenseMatrix matB, boolean transB, double beta, DenseMatrix matC);
440
    
441
    /** General matrix-vector multiplication: y = alpha*op(A)*x + beta*y */
442
    public static void gemv(double alpha, DenseMatrix matA, boolean transA,
443
                           DenseVector x, double beta, DenseVector y);
444
    public static void gemv(double alpha, DenseMatrix matA, boolean transA,
445
                           SparseVector x, double beta, DenseVector y);
446
}
447
```
448

449
**Usage Examples:**
450

451
```java
452
import org.apache.flink.ml.common.linalg.BLAS;
453

454
// Vector operations
455
double norm1 = BLAS.asum(vector1);           // L1 norm
456
double dotProd = BLAS.dot(vector1, vector2); // Dot product
457
BLAS.scal(2.0, vector1);                     // Scale vector
458
BLAS.axpy(1.5, vector2, vector1);            // vector1 += 1.5 * vector2
459

460
// Matrix operations
461
BLAS.scal(0.5, matrix);                      // Scale matrix
462
BLAS.axpy(2.0, matrixA, matrixB);            // matrixB += 2.0 * matrixA
463

464
// Matrix multiplication: C = 2.0*A*B + 1.0*C
465
BLAS.gemm(2.0, matrixA, false, matrixB, false, 1.0, matrixC);
466

467
// Matrix-vector multiplication: y = 1.0*A*x + 0.0*y
468
BLAS.gemv(1.0, matrix, false, inputVector, 0.0, outputVector);
469
```
470

471
### Vector Utilities
472

473
Utility functions for vector parsing, formatting, and type conversion operations.
474

475
```java { .api }
476
/**
477
 * Utility methods for vector parsing and formatting
478
 */
479
public class VectorUtil {
480
    /** Parse vector from string (auto-detects dense/sparse) */
481
    public static Vector parse(String str);
482
    
483
    /** Parse dense vector from string */
484
    public static DenseVector parseDense(String str);
485
    
486
    /** Parse sparse vector from string */
487
    public static SparseVector parseSparse(String str);
488
    
489
    /** Convert vector to string */
490
    public static String toString(Vector vector);
491
    public static String toString(DenseVector denseVector);
492
    public static String toString(SparseVector sparseVector);
493
}
494

495
/**
496
 * Iterator interface for vector elements
497
 */
498
public interface VectorIterator extends Serializable {
499
    /** Check if more elements available */
500
    boolean hasNext();
501
    
502
    /** Move to next element */
503
    void next();
504
    
505
    /** Get current element index */
506
    int getIndex();
507
    
508
    /** Get current element value */
509
    double getValue();
510
}
511
```
512

513
**Usage Examples:**
514

515
```java
516
import org.apache.flink.ml.common.linalg.VectorUtil;
517
import org.apache.flink.ml.common.linalg.VectorIterator;
518

519
// Parse vectors from strings
520
Vector vec = VectorUtil.parse("1.0 2.0 3.0");           // Dense format
521
Vector sparse = VectorUtil.parse("(10,[1,3],[2.0,4.0])"); // Sparse format
522

523
// Convert to strings
524
String vecStr = VectorUtil.toString(vec);
525

526
// Iterate over vector elements
527
VectorIterator iter = vec.iterator();
528
while (iter.hasNext()) {
529
    iter.next();
530
    int index = iter.getIndex();
531
    double value = iter.getValue();
532
    System.out.println("Index: " + index + ", Value: " + value);
533
}
534
```