0
# Linear Algebra
1

2
Comprehensive linear algebra library with dense and sparse vectors, matrices, and BLAS operations. Essential for numerical computations in ML algorithms with high-performance native integration.
3

4
## Capabilities
5

6
### Vector Classes
7

8
Base vector abstraction with dense and sparse implementations for efficient numerical operations.
9

10
#### Vector Abstract Class
11

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

81
#### DenseVector Class
82

83
```java { .api }
84
/**
85
 * Dense vector implementation storing all elements in array
86
 */
87
public class DenseVector extends Vector {
88
    
89
    /** Create zero vector of size n */
90
    public DenseVector(int n);
91
    
92
    /** Create vector from data array */
93
    public DenseVector(double[] data);
94
    
95
    /** Get underlying data array */
96
    public double[] getData();
97
    
98
    /** Set underlying data array */
99
    public void setData(double[] data);
100
    
101
    /** Copy data from another dense vector */
102
    public void setEqual(DenseVector other);
103
    
104
    /** Add another vector in-place */
105
    public void plusEqual(Vector other);
106
    
107
    /** Subtract another vector in-place */
108
    public void minusEqual(Vector other);
109
    
110
    /** Add scaled vector in-place: this += alpha * other */
111
    public void plusScaleEqual(Vector other, double alpha);
112
    
113
    /** Compute outer product with another dense vector */
114
    public DenseMatrix outer(DenseVector other);
115
    
116
    /** Create deep copy */
117
    public DenseVector clone();
118
    
119
    // Static factory methods
120
    /** Create vector of all ones */
121
    public static DenseVector ones(int n);
122
    
123
    /** Create vector of all zeros */
124
    public static DenseVector zeros(int n);
125
    
126
    /** Create random vector with uniform distribution */
127
    public static DenseVector rand(int n);
128
}
129
```
130

131
**Usage Examples:**
132

133
```java
134
import org.apache.flink.ml.common.linalg.DenseVector;
135

136
// Create vectors
137
DenseVector v1 = new DenseVector(new double[]{1.0, 2.0, 3.0});
138
DenseVector v2 = DenseVector.ones(3);
139
DenseVector zeros = DenseVector.zeros(5);
140

141
// Basic operations
142
double dot = v1.dot(v2);                    // 6.0
143
double norm = v1.normL2();                  // 3.741...
144
DenseVector scaled = v1.scale(2.0);         // [2.0, 4.0, 6.0]
145

146
// In-place operations
147
v1.plusEqual(v2);                           // v1 becomes [2.0, 3.0, 4.0]
148
v1.scaleEqual(0.5);                         // v1 becomes [1.0, 1.5, 2.0]
149

150
// Vector algebra
151
DenseVector v3 = v1.plus(v2);               // Element-wise addition
152
DenseVector v4 = v1.minus(v2);              // Element-wise subtraction
153
```
154

155
#### SparseVector Class
156

157
```java { .api }
158
/**
159
 * Sparse vector implementation storing only non-zero elements
160
 * Efficient for vectors with many zero elements
161
 */
162
public class SparseVector extends Vector {
163
    
164
    /** Create empty sparse vector with undetermined size */
165
    public SparseVector();
166
    
167
    /** Create empty sparse vector with determined size */
168
    public SparseVector(int n);
169
    
170
    /** Create sparse vector from indices and values arrays */
171
    public SparseVector(int n, int[] indices, double[] values);
172
    
173
    /** Create sparse vector from map of index->value pairs */
174
    public SparseVector(int n, Map<Integer, Double> kv);
175
    
176
    /** Get indices of non-zero elements */
177
    public int[] getIndices();
178
    
179
    /** Get values of non-zero elements */
180
    public double[] getValues();
181
    
182
    /** Set vector size */
183
    public void setSize(int n);
184
    
185
    /** Get number of non-zero values stored */
186
    public int numberOfValues();
187
    
188
    /** Remove elements that are zero */
189
    public void removeZeroValues();
190
    
191
    /** Convert to dense vector representation */
192
    public DenseVector toDenseVector();
193
    
194
    /** Compute outer product with another sparse vector */
195
    public DenseMatrix outer(SparseVector other);
196
    
197
    /** Create deep copy */
198
    public SparseVector clone();
199
}
200
```
201

202
**Usage Examples:**
203

204
```java
205
import org.apache.flink.ml.common.linalg.SparseVector;
206
import java.util.HashMap;
207
import java.util.Map;
208

209
// Create sparse vector from indices/values
210
int[] indices = {0, 2, 4};
211
double[] values = {1.0, 3.0, 5.0};
212
SparseVector sparse1 = new SparseVector(5, indices, values);
213

214
// Create from map
215
Map<Integer, Double> map = new HashMap<>();
216
map.put(1, 2.0);
217
map.put(3, 4.0);
218
SparseVector sparse2 = new SparseVector(5, map);
219

220
// Inspect sparse structure
221
int nonZeros = sparse1.numberOfValues();    // 3
222
int[] idx = sparse1.getIndices();           // [0, 2, 4]
223
double[] vals = sparse1.getValues();        // [1.0, 3.0, 5.0]
224

225
// Convert to dense if needed
226
DenseVector dense = sparse1.toDenseVector(); // [1.0, 0.0, 3.0, 0.0, 5.0]
227
```
228

229
### Matrix Classes
230

231
Dense matrix implementation with comprehensive linear algebra operations.
232

233
#### DenseMatrix Class
234

235
```java { .api }
236
/**
237
 * Dense matrix implementation with column-major storage
238
 * Provides comprehensive linear algebra operations
239
 */
240
public class DenseMatrix implements Serializable {
241
    
242
    /** Create zero matrix of size m x n */
243
    public DenseMatrix(int m, int n);
244
    
245
    /** Create matrix from data array in column-major order */
246
    public DenseMatrix(int m, int n, double[] data);
247
    
248
    /** Create matrix from data array with specified layout */
249
    public DenseMatrix(int m, int n, double[] data, boolean inRowMajor);
250
    
251
    /** Create matrix from 2D array */
252
    public DenseMatrix(double[][] data);
253
    
254
    // Element access
255
    /** Get element at (i, j) */
256
    public double get(int i, int j);
257
    
258
    /** Set element at (i, j) */
259
    public void set(int i, int j, double s);
260
    
261
    /** Add value to element at (i, j) */
262
    public void add(int i, int j, double s);
263
    
264
    // Data access
265
    /** Get underlying data array (column-major) */
266
    public double[] getData();
267
    
268
    /** Get copy as 2D array */
269
    public double[][] getArrayCopy2D();
270
    
271
    /** Get copy as 1D array with specified layout */
272
    public double[] getArrayCopy1D(boolean inRowMajor);
273
    
274
    /** Get copy of specific row */
275
    public double[] getRow(int row);
276
    
277
    /** Get copy of specific column */
278
    public double[] getColumn(int col);
279
    
280
    // Matrix operations
281
    /** Create transpose of matrix */
282
    public DenseMatrix transpose();
283
    
284
    /** Scale matrix by scalar (immutable) */
285
    public DenseMatrix scale(double v);
286
    
287
    /** Scale matrix by scalar (mutable) */
288
    public void scaleEqual(double v);
289
    
290
    /** Add matrices */
291
    public DenseMatrix plus(DenseMatrix mat);
292
    
293
    /** Add scalar to all elements */
294
    public DenseMatrix plus(double alpha);
295
    
296
    /** Add matrix in-place */
297
    public void plusEquals(DenseMatrix mat);
298
    
299
    /** Add scalar to all elements in-place */
300
    public void plusEquals(double alpha);
301
    
302
    /** Subtract matrices */
303
    public DenseMatrix minus(DenseMatrix mat);
304
    
305
    /** Subtract matrix in-place */
306
    public void minusEquals(DenseMatrix mat);
307
    
308
    /** Matrix multiplication */
309
    public DenseMatrix multiplies(DenseMatrix mat);
310
    
311
    /** Matrix-vector multiplication */
312
    public DenseVector multiplies(DenseVector x);
313
    
314
    /** Matrix-sparse vector multiplication */
315
    public DenseVector multiplies(SparseVector x);
316
    
317
    // Matrix properties
318
    /** Check if matrix is square */
319
    public boolean isSquare();
320
    
321
    /** Check if matrix is symmetric */
322
    public boolean isSymmetric();
323
    
324
    /** Get number of rows */
325
    public int numRows();
326
    
327
    /** Get number of columns */
328
    public int numCols();
329
    
330
    /** Sum all elements */
331
    public double sum();
332
    
333
    // Submatrix operations
334
    /** Select specific rows */
335
    public DenseMatrix selectRows(int[] rows);
336
    
337
    /** Get submatrix */
338
    public DenseMatrix getSubMatrix(int m0, int m1, int n0, int n1);
339
    
340
    /** Set submatrix */
341
    public void setSubMatrix(DenseMatrix sub, int m0, int m1, int n0, int n1);
342
    
343
    /** Create deep copy */
344
    public DenseMatrix clone();
345
    
346
    // Static factory methods
347
    /** Create identity matrix */
348
    public static DenseMatrix eye(int n);
349
    
350
    /** Create identity-like matrix (m x n) */
351
    public static DenseMatrix eye(int m, int n);
352
    
353
    /** Create zero matrix */
354
    public static DenseMatrix zeros(int m, int n);
355
    
356
    /** Create matrix of all ones */
357
    public static DenseMatrix ones(int m, int n);
358
    
359
    /** Create random matrix */
360
    public static DenseMatrix rand(int m, int n);
361
    
362
    /** Create random symmetric matrix */
363
    public static DenseMatrix randSymmetric(int n);
364
}
365
```
366

367
**Usage Examples:**
368

369
```java
370
import org.apache.flink.ml.common.linalg.DenseMatrix;
371
import org.apache.flink.ml.common.linalg.DenseVector;
372

373
// Create matrices
374
DenseMatrix A = new DenseMatrix(new double[][]{
375
    {1.0, 2.0, 3.0},
376
    {4.0, 5.0, 6.0}
377
}); // 2x3 matrix
378

379
DenseMatrix I = DenseMatrix.eye(3);      // 3x3 identity
380
DenseMatrix zeros = DenseMatrix.zeros(2, 4);
381
DenseMatrix random = DenseMatrix.rand(3, 3);
382

383
// Basic operations
384
double element = A.get(0, 1);            // 2.0
385
A.set(1, 2, 10.0);                       // Set element to 10.0
386
DenseMatrix At = A.transpose();          // Transpose
387

388
// Matrix arithmetic
389
DenseMatrix B = DenseMatrix.ones(2, 3);
390
DenseMatrix sum = A.plus(B);             // Matrix addition
391
DenseMatrix scaled = A.scale(2.0);       // Scalar multiplication
392

393
// Matrix-vector multiplication  
394
DenseVector x = new DenseVector(new double[]{1.0, 2.0, 3.0});
395
DenseVector Ax = A.multiplies(x);        // Matrix-vector product
396

397
// Matrix-matrix multiplication
398
DenseMatrix C = DenseMatrix.rand(3, 4);
399
DenseMatrix AC = A.multiplies(C);        // 2x4 result
400

401
// Properties
402
boolean isSquare = A.isSquare();         // false (2x3)
403
int rows = A.numRows();                  // 2
404
int cols = A.numCols();                  // 3
405
double total = A.sum();                  // Sum of all elements
406
```
407

408
### BLAS Operations
409

410
High-performance Basic Linear Algebra Subprograms (BLAS) operations with native library integration.
411

412
```java { .api }
413
/**
414
 * BLAS (Basic Linear Algebra Subprograms) operations
415
 * Provides optimized implementations for common linear algebra operations
416
 */
417
public class BLAS {
418
    
419
    /** Native BLAS instance for best performance */
420
    public static final com.github.fommil.netlib.BLAS NATIVE_BLAS;
421
    
422
    /** Fallback F2J BLAS instance */
423
    public static final com.github.fommil.netlib.BLAS F2J_BLAS;
424
    
425
    // Level-1 BLAS operations (vector-vector)
426
    
427
    /** Sum of absolute values: ||x||_1 */
428
    public static double asum(int n, double[] x, int offset);
429
    public static double asum(DenseVector x);
430
    public static double asum(SparseVector x);
431
    
432
    /** Scaled vector addition: y += a*x */
433
    public static void axpy(double a, double[] x, double[] y);
434
    public static void axpy(double a, DenseVector x, DenseVector y);
435
    public static void axpy(double a, SparseVector x, DenseVector y);
436
    public static void axpy(double a, DenseMatrix x, DenseMatrix y);
437
    
438
    /** Dot product: x^T * y */
439
    public static double dot(double[] x, double[] y);
440
    public static double dot(DenseVector x, DenseVector y);
441
    
442
    /** Scale vector: x *= a */
443
    public static void scal(double a, double[] x);
444
    public static void scal(double a, DenseVector x);
445
    public static void scal(double a, SparseVector x);
446
    public static void scal(double a, DenseMatrix x);
447
    
448
    // Level-2 BLAS operations (matrix-vector)
449
    
450
    /** General matrix-vector multiplication: y = alpha*A*x + beta*y */
451
    public static void gemv(double alpha, DenseMatrix matA, boolean transA, 
452
                           DenseVector x, double beta, DenseVector y);
453
    public static void gemv(double alpha, DenseMatrix matA, boolean transA, 
454
                           SparseVector x, double beta, DenseVector y);
455
    
456
    // Level-3 BLAS operations (matrix-matrix)
457
    
458
    /** General matrix-matrix multiplication: C = alpha*A*B + beta*C */
459
    public static void gemm(double alpha, DenseMatrix matA, boolean transA,
460
                           DenseMatrix matB, boolean transB,
461
                           double beta, DenseMatrix matC);
462
}
463
```
464

465
**Usage Examples:**
466

467
```java
468
import org.apache.flink.ml.common.linalg.BLAS;
469

470
// Vector operations
471
DenseVector x = new DenseVector(new double[]{1.0, 2.0, 3.0});
472
DenseVector y = new DenseVector(new double[]{4.0, 5.0, 6.0});
473

474
// Compute dot product
475
double dotProd = BLAS.dot(x, y);                    // 32.0
476

477
// Scale vector in-place
478
BLAS.scal(2.0, x);                                  // x becomes [2.0, 4.0, 6.0]
479

480
// Scaled vector addition: y += 0.5 * x
481
BLAS.axpy(0.5, x, y);                               // y becomes [5.0, 7.0, 9.0]
482

483
// Matrix-vector multiplication
484
DenseMatrix A = DenseMatrix.rand(3, 3);
485
DenseVector b = DenseVector.zeros(3);
486

487
// b = 1.0 * A * x + 0.0 * b (i.e., b = A * x)
488
BLAS.gemv(1.0, A, false, x, 0.0, b);
489

490
// Matrix-matrix multiplication  
491
DenseMatrix B = DenseMatrix.rand(3, 3);
492
DenseMatrix C = DenseMatrix.zeros(3, 3);
493

494
// C = 1.0 * A * B + 0.0 * C (i.e., C = A * B)
495
BLAS.gemm(1.0, A, false, B, false, 0.0, C);
496
```
497

498
### Vector Utilities
499

500
Additional utilities for vector operations and serialization.
501

502
#### MatVecOp Utility Class
503

504
```java { .api }
505
/**
506
 * Matrix and vector operations utility class
507
 */
508
public class MatVecOp {
509
    
510
    /** Vector addition */
511
    public static Vector plus(Vector vec1, Vector vec2);
512
    
513
    /** Vector subtraction */
514
    public static Vector minus(Vector vec1, Vector vec2);
515
    
516
    /** Dot product */
517
    public static double dot(Vector vec1, Vector vec2);
518
    
519
    /** L1 distance between vectors */
520
    public static double sumAbsDiff(Vector vec1, Vector vec2);
521
    
522
    /** Squared L2 distance between vectors */  
523
    public static double sumSquaredDiff(Vector vec1, Vector vec2);
524
    
525
    // Element-wise operations (various apply methods for matrices and vectors)
526
}
527
```
528

529
#### VectorUtil Utility Class
530

531
```java { .api }
532
/**
533
 * Vector parsing and serialization utilities
534
 */
535
public class VectorUtil {
536
    
537
    /** Element delimiter character */
538
    public static final char ELEMENT_DELIMITER = ' ';
539
    
540
    /** Size header delimiter character */
541
    public static final char HEADER_DELIMITER = '$';
542
    
543
    /** Index-value delimiter for sparse vectors */
544
    public static final char INDEX_VALUE_DELIMITER = ':';
545
    
546
    /** Parse vector from string representation */
547
    public static Vector parse(String str);
548
    
549
    /** Parse dense vector from string */
550
    public static DenseVector parseDense(String str);
551
    
552
    /** Parse sparse vector from string */
553
    public static SparseVector parseSparse(String str);
554
    
555
    /** Serialize vector to string */
556
    public static String toString(Vector vector);
557
    
558
    /** Serialize sparse vector to string */
559
    public static String toString(SparseVector sparseVector);
560
    
561
    /** Serialize dense vector to string */
562
    public static String toString(DenseVector denseVector);
563
}
564
```
565

566
**Usage Examples:**
567

568
```java
569
import org.apache.flink.ml.common.linalg.VectorUtil;
570

571
// Create vectors
572
DenseVector dense = new DenseVector(new double[]{1.0, 2.0, 3.0});
573
SparseVector sparse = new SparseVector(5, new int[]{0, 2, 4}, new double[]{1.0, 3.0, 5.0});
574

575
// Serialize to strings
576
String denseStr = VectorUtil.toString(dense);        // "1.0 2.0 3.0"
577
String sparseStr = VectorUtil.toString(sparse);      // "$5$0:1.0 2:3.0 4:5.0"
578

579
// Parse from strings
580
DenseVector parsedDense = VectorUtil.parseDense(denseStr);
581
SparseVector parsedSparse = VectorUtil.parseSparse(sparseStr);
582
Vector parsed = VectorUtil.parse(denseStr);          // Auto-detects type
583
```
584

585
#### VectorIterator Interface
586

587
```java { .api }
588
/**
589
 * Iterator for efficiently traversing vector elements
590
 */
591
public interface VectorIterator extends Serializable {
592
    
593
    /** Check if more elements available */
594
    boolean hasNext();
595
    
596
    /** Move to next element */
597
    void next();
598
    
599
    /** Get current element index */
600
    int getIndex();
601
    
602
    /** Get current element value */
603
    double getValue();
604
}
605
```
606

607
**Usage Example:**
608

609
```java
610
SparseVector sparse = new SparseVector(10, new int[]{1, 5, 8}, new double[]{2.0, 4.0, 6.0});
611

612
// Iterate over non-zero elements
613
VectorIterator iter = sparse.iterator();
614
while (iter.hasNext()) {
615
    iter.next();
616
    int index = iter.getIndex();
617
    double value = iter.getValue();
618
    System.out.println("sparse[" + index + "] = " + value);
619
}
620
// Output:
621
// sparse[1] = 2.0
622
// sparse[5] = 4.0  
623
// sparse[8] = 6.0
624
```
625

626
### Statistics
627

628
Basic statistical operations for multivariate data.
629

630
#### MultivariateGaussian Class
631

632
```java { .api }
633
/**
634
 * Multivariate Gaussian (Normal) Distribution
635
 * Provides probability density function calculations
636
 */
637
public class MultivariateGaussian {
638
    
639
    /** LAPACK instance for linear algebra */
640
    public static final LAPACK LAPACK_INST;
641
    
642
    /** BLAS instance for basic operations */
643
    public static final com.github.fommil.netlib.BLAS F2J_BLAS_INST;
644
    
645
    /** Machine epsilon for numerical stability */
646
    public static final double EPSILON;
647
    
648
    /** Create multivariate Gaussian with mean and covariance */
649
    public MultivariateGaussian(DenseVector mean, DenseMatrix cov);
650
    
651
    /** Compute probability density function at point x */
652
    public double pdf(Vector x);
653
    
654
    /** Compute log probability density function at point x */
655
    public double logpdf(Vector x);
656
}
657
```
658

659
**Usage Example:**
660

661
```java
662
import org.apache.flink.ml.common.statistics.basicstatistic.MultivariateGaussian;
663

664
// Define 2D Gaussian distribution
665
DenseVector mean = new DenseVector(new double[]{0.0, 0.0});
666
DenseMatrix cov = new DenseMatrix(new double[][]{
667
    {1.0, 0.5},
668
    {0.5, 1.0}
669
});
670

671
MultivariateGaussian gaussian = new MultivariateGaussian(mean, cov);
672

673
// Evaluate probability density
674
DenseVector point = new DenseVector(new double[]{1.0, 1.0});
675
double density = gaussian.pdf(point);
676
double logDensity = gaussian.logpdf(point);
677
```