# gizai/tensor/linalg

dense linear algebra over Tensor<f64> matrices, as numpy.linalg over ndarray: Cholesky, the symmetric eigendecomposition (cyclic Jacobi), solves, least squares through the pseudo-inverse and the principal components; and sparse matrices in compressed rows, whose symmetric positive definite systems conjugate gradients solve. A product is Tensor.matmul (xᵀx is `x.transpose().matmul(x)`). A matrix may be any view; a right-hand side is n × t, or a vector of n.

```gizlang
import * as Linalg from "gizai/tensor/linalg";
```

## Types

### `Eigen`

```gizlang
type Eigen = { values: Tensor<f64>; vectors: Tensor<f64>; }
```

The eigenvalues in descending order (n), and the unit eigenvector of each as a row of `vectors` (n × n).

- `values`: `_gizlang_lib_ai__tensor__storage.Tensor<f64>`
- `vectors`: `_gizlang_lib_ai__tensor__storage.Tensor<f64>`

### `Components`

```gizlang
type Components = { mean: Tensor<f64>; components: Tensor<f64>; variance: Tensor<f64>; total: f64; }
```

Principal components: the column means (d), the directions as rows (d × d) with the sign that makes the largest
entry of each positive (scikit-learn's svd_flip on Vᵀ), the variance along each (d), largest first, and their sum
before any is clipped at 0.

- `mean`: `_gizlang_lib_ai__tensor__storage.Tensor<f64>`
- `components`: `_gizlang_lib_ai__tensor__storage.Tensor<f64>`
- `variance`: `_gizlang_lib_ai__tensor__storage.Tensor<f64>`
- `total`: `f64`

### `Sparse`

```gizlang
type Sparse = { rows: i64; cols: i64; start: Vec<i64>; index: Vec<i64>; value: Vec<f64>; }
```

A rows × cols matrix in compressed sparse rows: row r's entries are index[start[r] .. start[r + 1]] (their columns,
ascending) and value[same]. Storage is the entries, not rows × cols.

- `rows`: `i64`
- `cols`: `i64`
- `start`: `Vec<i64>`
- `index`: `Vec<i64>`
- `value`: `Vec<f64>`

### `Solved`

```gizlang
type Solved = { x: Tensor<f64>; residual: f64; steps: i64; }
```

An iterative solution, the norm of its residual B - A x, and the steps it took.

- `x`: `_gizlang_lib_ai__tensor__storage.Tensor<f64>`
- `residual`: `f64`
- `steps`: `i64`

## Methods

### `Tensor.cholesky`

```gizlang
function Tensor.cholesky(self: Tensor<f64>): Option<Tensor<f64>>
```

The lower Cholesky factor L of a symmetric positive definite matrix (a = L Lᵀ), or none.

Effects: fail, read, write, io, alloc.

### `Tensor.choleskySolve`

```gizlang
function Tensor.choleskySolve(self: Tensor<f64>, b: Tensor<f64>): Tensor<f64>
```

X of L Lᵀ X = B, where this is the Cholesky factor L, for each column of B (n × t, or n).

Effects: fail, read, write, io, alloc.

### `Tensor.eigh`

```gizlang
function Tensor.eigh(self: Tensor<f64>): Eigen
```

The eigendecomposition of a symmetric matrix by cyclic Jacobi rotations, to machine precision.

Effects: fail, read, write, io, alloc.

### `Tensor.solveSymmetric`

```gizlang
function Tensor.solveSymmetric(self: Tensor<f64>, b: Tensor<f64>): Tensor<f64>
```

The minimum-norm X of A X = B for this symmetric positive semidefinite A and B (n × t, or n): Cholesky, else the
pseudo-inverse with eigenvalues below 1e-12 × the largest dropped, as LAPACK's lstsq drops singular values.

Effects: fail, read, write, io, alloc.

### `Tensor.pseudoSolve`

```gizlang
function Tensor.pseudoSolve(self: Tensor<f64>, b: Tensor<f64>, rcond: f64): Tensor<f64>
```

The least-squares X of A X = B for this symmetric A and B (n × t, or n), through the pseudo-inverse: eigenvalues
below RCOND times the largest count as zero.

Effects: fail, read, write, io, alloc.

### `Tensor.principalComponents`

```gizlang
function Tensor.principalComponents(self: Tensor<f64>): Components
```

The principal components of an n × d matrix whose rows are samples.

Effects: fail, read, write, console, io, alloc.

### `Sparse.of`

```gizlang
function Sparse.of(rows: i64, cols: i64, i: Vec<i64>, j: Vec<i64>, v: Vec<f64>): Sparse
```

The rows × cols matrix whose entry (I[k], J[k]) is the sum of every V[k] there (duplicates add, as a finite element
assembly writes them); zeros are kept out.

Effects: fail, alloc.

### `Sparse.matmul`

```gizlang
function Sparse.matmul(self: Sparse, x: Tensor<f64>): Tensor<f64>
```

This matrix times the vector X (of cols).

Effects: fail, read, write, io, alloc.

### `Sparse.conjugateGradient`

```gizlang
function Sparse.conjugateGradient(self: Sparse, rhs: Tensor<f64>, tolerance: f64, limit: i64): Solved
```

X of A X = B for this symmetric positive definite A, by conjugate gradients with A's diagonal as the
preconditioner, until |B - A x| is at most TOLERANCE |B| or after LIMIT steps. Each step is one product by A, so a
sparse system costs its entries per step, not n^2.

Effects: fail, read, write, io, alloc.

