Luna Flow

English

简体中文
日本語

English

简体中文
日本語

Appearance

@mutable.Matrix ​

API baseline for @mutable.Matrix in the current 0.4.7 repository state. Square-root-dependent APIs use Luna-Flow/arithmetic.Sqrt; Tolerance remains defined by mutable.

Overview ​

  • @mutable.Matrix is the repository's execution-oriented matrix type.
  • set, swap_rows, swap_cols, map_inplace, row/column view updates, and transpose updates modify the underlying matrix in place.
  • Public storage is a flat row-major Array[T] across backends. Backend-specific files differ in execution tuning, not in the public matrix model.
  • Public access is strict about bounds. get, set, m[row][col], row_view, col_view, extraction helpers, iterators, and transpose-view access reject out-of-range indices consistently, including zero-row and zero-column edge shapes.
  • swap_rows(i, i) and swap_cols(i, i) leave the matrix unchanged. Out-of-range row or column indices abort explicitly instead of relying on accidental storage access.

Core Matrix API ​

  • Matrix::make(row, col, f) Builds a matrix from a generator function. Negative dimensions abort.
  • Matrix::new(row, col, elem) Builds a matrix filled with elem. Negative dimensions abort.
  • Matrix::from_2d_array(arr) Creates a matrix from a rectangular 2D array. Ragged input aborts.
  • Matrix::from_array(row, col, data) Uses a flat row-major array as matrix storage. Negative dimensions or wrong element count abort.
  • row() / col() Return the stored shape.
  • get(row, col) / set(row, col, elem) Fast random access with explicit bounds checks.
  • m[row][col] Convenience syntax backed by Lens[T]. It is valid for read and write, but repeated bulk work should prefer row_view, col_view, or the dedicated row/column helpers.
  • copy() Deep-copies the matrix.
  • map, mapi Return a transformed matrix.
  • map_inplace, map_row_inplace, map_col_inplace Apply in-place transforms.
  • each, eachi, each_row_col, each_row, each_col, eachi_row, eachi_col Traversal helpers.
  • iter, iter_row, iter_col Iterators with checked row/column bounds.
  • row_to_array, col_to_array, row_to_vector, col_to_vector, to_array, to_2d_array, to_vector Materialization helpers with checked indices where applicable.
  • transpose() Returns a materialized transpose.
  • to_transpose() Returns a live transpose view.
  • horizontal_combine, vertical_combine Concatenate compatible matrices.

Views And Transpose ​

  • row_view(row) / col_view(col) Return live views into the underlying matrix.
  • RowView and ColView Expose get, set, iter, each, eachi, map_inplace, to_array, and to_vector.
  • Transpose Exposes the same matrix-like surface over a live transposed view.
  • Transpose::swap_rows and Transpose::swap_cols Delegate to the underlying matrix with the same strict bounds semantics.

Algebraic And Numeric API ​

  • +, -, * Matrix addition, subtraction, and multiplication.
  • scale(cst), add_constant(cst), unary - Element-wise scalar transforms.
  • identity(size) Identity matrix constructor. Negative size aborts.
  • pow(power) Checked square-matrix exponentiation for non-negative integer powers.
  • matrix_power(n) Checked public wrapper around pow(n).
  • trace() Checked sum of diagonal entries. Requires a square matrix and returns Result[..., LinearAlgebraError].
  • determinant() Checked determinant of a square matrix.
  • inverse(), is_invertible() Checked inversion helpers for square matrices. Singular inverse returns Err.
  • mul_vec(vector) Checked matrix-vector multiplication. Shape mismatch returns Err.
  • mean(), variance(), std_dev(), max_element(), min_element() Checked aggregate helpers. Empty matrices return Err.
  • unchecked_trace(), unchecked_determinant(), unchecked_inverse(), unchecked_is_invertible(), unchecked_pow(), unchecked_matrix_power(), unchecked_mul_vec(), unchecked_mean(), unchecked_variance(), unchecked_std_dev(), unchecked_max_element(), unchecked_min_element() Preserve the old aborting or Option-returning behavior.
  • rank() Rank computed through the current repository algorithm.
  • reduce_row_elimination() In-place-style row reduction on the mutable matrix value.
  • cholesky_decomposition() Cholesky factorization for supported numeric inputs.
  • eigen(), power_method() Public eigen-related APIs for supported numeric cases. The specialized 2x2 helper used by the implementation is not part of the public package interface.
  • is_square(), null(), is_symmetric(), is_positive_definite() Structural and numeric predicates.
  • frobenius_norm() Non-checked aggregate numeric helper for supported element types.

Guidance ​

  • Backends are expected to expose the same public semantics. The repository currently keeps separate kernel files for native, js, wasm, and wasm-gc, so tests and documentation should be read as backend-invariant unless a note says otherwise.
  • For code shared across immut and mutable, rely on the common algebraic surface and not on identical mutation semantics.
  • backends/default.DenseMatrix is a wrapper around this concrete implementation. If you want the trait-oriented default backend entry point, see the backends/default API.