#LINEAR-ALGEBRA

#v0.4.7 - Storage-Independent Container Capabilities

#Release Notes

• The new container layer exposes read, build, persistent-edit, and mutable-edit operation dictionaries without requiring a concrete storage representation.
• Generic vector/matrix map and conversion algorithms, plus matrix transpose, can now operate through container capabilities and adapters.
• Algebra integration guidance now documents shape, additive, transpose, Hadamard, and matrix-multiplication capability levels for external types.
• immut no longer exposes runtime backend-selection APIs. Backend choice is now expressed by the concrete type you use, not by a runtime ADT.
• backends/default now provides backend methods scale, dot, axpy, and matvec on its dense vector and matrix wrappers.
• backends/openblas now exposes both BlasMatrix[T] and BlasVector[T] for Float and Double, using OpenBLAS GEMM for matrix multiplication plus BLAS-backed dot, scal, axpy, and gemv for vector and matrix-vector work.
• Scalar-valued vector products and BLAS-style linear combinations remain backend methods. They were not promoted into new @algebra traits in this release.
• The default test gate now exercises the container packages and default backend across Wasm GC, JavaScript, native, and Wasm targets.

#Layered Architecture

Experimental features: The algebra and container capability layers are available for integration experiments and ecosystem feedback, but their trait hierarchy, operation dictionaries, error contracts, and function signatures are not yet stable. Downstream libraries should not treat these packages as compatibility-stable public boundaries until they graduate from experimental status. The concrete immut, mutable, and backend APIs are not covered by this experimental designation solely because they implement or provide adapters for these layers.

• arithmetic: Linear-algebra-facing operation capabilities. It reuses scalar operation traits from Luna-Flow/luna-generic and Luna-Flow/arithmetic, and adds small operation-only traits such as ApproxEq, Abs, CheckedDiv, CheckedSqrt, and CheckedCompare.
• algebra: Semantic mathematical structure capabilities. It defines only the linear-algebra-owned structure traits such as MatrixShape, AdditiveVector, TransposeMatrix, and MatMulMatrix.
• container: Storage-independent read, build, persistent-edit, and mutable-edit operation dictionaries, plus generic map, conversion, and transpose algorithms. Concrete adapters live in container/adapters.
• backends/default: The reference dense backend layer. It exposes wrapper types DenseVector / DenseMatrix over mutable, and ImmutableDenseVector / ImmutableDenseMatrix over immut, plus backend methods for scaling, dot products, AXPY-style combinations, and matrix-vector multiplication.
• backends/openblas: A native-only OpenBLAS backend. It exposes the owned BlasMatrix[T] and BlasVector[T] wrappers for Float and Double, uses OpenBLAS GEMM for matrix multiplication, BLAS vector kernels for backend methods like dot / axpy, and keeps backend choice explicit through the concrete type rather than a runtime selector.
• Trait-driven algorithms: New backend-independent algorithms should depend on the smallest capability they need, such as MatrixShape, AdditiveVector, VecMulVector, TransposeMatrix, or MatMulMatrix, not directly on one concrete matrix or vector type.

#Package Positioning

• immut: Immutable, value-oriented Matrix, Vector, and MatrixFn types for persistent data and explicit copy-on-update semantics.
• mutable: Execution-oriented Matrix and Vector types with in-place updates, Transpose views, RowView / ColView, and backend-specific implementations for js, wasm, wasm-gc, and native.
• Shared Core, Different Execution Model: Constructors and core algebraic operators remain aligned across packages, but mutation and access semantics are intentionally different.

#Trait-Oriented Setup

moon add Luna-Flow/linear-algebra@0.4.7
moon add Luna-Flow/luna-generic@0.3.3
moon add Luna-Flow/arithmetic@0.2.2

import {
  "Luna-Flow/linear-algebra/algebra",
  "Luna-Flow/linear-algebra/arithmetic" @la_arithmetic,
  "Luna-Flow/luna-generic" @lf_alg,
  "Luna-Flow/arithmetic" @lf_arith,
}

#Checked Contracts

• Checked Matrix Contracts: Shape, exponent, empty-matrix, and singular matrix failures are now represented by LinearAlgebraError on the checked matrix APIs.
• Legacy Behavior Is Explicit: unchecked_* methods preserve the previous aborting behavior, and unchecked_inverse preserves the previous Option-returning inverse contract.
• Public Error Package: linear-algebra/error exposes LinearAlgebraError, LinearAlgebraErrorKind, constructors, and is_* predicates for callers that need structured error handling.
• Shared Square-Root Capability: Numerical matrix APIs now use Luna-Flow/arithmetic.Sqrt instead of a package-local trait. mutable re-exports the shared trait for source-level discoverability.
• Target-Side Integral Embedding: Generic integer conversions use IntegralHomomorphism::from_integral, matching the current Luna-Flow/luna-generic algebraic model.
• Ecosystem-Oriented Constraints: Custom scalar types can implement the shared Luna Flow traits once and use them across compatible ecosystem packages.
• Backend Consistency: Native, JS, Wasm, and Wasm GC matrix implementations use the same arithmetic capability identity and explicit trait invocation.
• Compatibility Boundary: Tolerance remains a mutable package trait in this release; it has not yet moved to arithmetic.
• Backend Choice: @immut.Matrix does not expose a runtime backend selector. Choose backends/default for the repository dense wrappers or backends/openblas for the native-only OpenBLAS matrix wrapper.

#API Guidance & Performance

• Core Algebraic API: Shared operations such as make, transpose, +, -, *, trace, and matrix/vector conversions are intended to stay semantically aligned across immut and mutable.
• Checked vs. Unchecked: Prefer checked methods in user-facing code. Use unchecked_* only when shape and domain preconditions are already enforced by surrounding logic.
• Random Access: In mutable, for high-performance random access, prefer .get(i, j) and .set(i, j, val) directly.
• Structured Views: For repeated row or column work in mutable, prefer row_view() / col_view() instead of relying on matrix[row] convenience syntax.
• Strict Bounds: Public matrix, view, and transpose accessors consistently reject out-of-bounds indices, including 0xN and Nx0 edge cases.
• MatrixFn Alignment: immut.MatrixFn now shares the same non-negative dimension and empty-matrix semantics as the concrete matrix implementations.
• Public Surface: Internal decomposition helpers remain implementation details. Package users should rely on the documented public matrix methods instead.

#Key Features

• Mutable & Immutable Support: Full Matrix and Vector suites with distinct semantics for value-oriented and execution-oriented workloads.
• Advanced Operations: Includes determinant, inverse, rank, Cholesky decomposition, eigen-related routines, row elimination, transpose views, and matrix/vector conversions.
• Shared Data Model, Backend-Tuned Kernels: mutable still ships backend-tuned execution paths for Native, Wasm, JS, and Wasm GC targets, but the core matrix storage model is now unified.
• Benchmark Infrastructure: bench/, src/perf_support, and src/perf_runner now form a full steady-state benchmarking subsystem for backend comparison and diagnostic replay.
• Correctness First: Coverage now includes immutable laws, cross-package consistency checks, determinant/rank/inverse alignment, and regression tests for numerical behavior.
• Auditable Public Contracts: Bounds behavior, swap semantics, benchmark fixtures, and documentation are now tracked more explicitly as part of the repository’s correctness story.

#Benchmark Packages

• perf: Benchmark entry package used by moon bench for the steady-state matrix suite.
• perf_support: Public fixture metadata, case registry, runtime loaders, and checksum-oriented execution helpers for benchmark cases.
• perf_runner: Single-case diagnostic and sampling runner used for replay, local investigation, and richer benchmark artifact generation.

#Quick Start

///|
test "linear-algebra basic workflow" {
  let imm = @immut.Matrix::from_2d_array([[1, 2], [3, 4]])
  let imm_updated = imm.set(0, 1, 9)
  inspect(imm_updated, content="|1, 9|\n|3, 4|")

  let m = @mutable.Matrix::from_2d_array([[1.0, 2.0], [3.0, 4.0]])
  m.set(0, 1, 9.0)

  inspect(m.determinant().unwrap(), content="-23")
  inspect(m.inverse() is Ok(_), content="true")
  inspect(m.row_view(0)[1], content="9")
}

#Reader Guide

• General application developers: Start with mutable and immut. These are the concrete APIs for application code such as business tools, utilities, numeric processing, small games, and visualization logic.
• Math library / general algorithm developers: Read in this order: arithmetic -> algebra -> container -> backends/default -> backends/openblas -> immut / mutable. Start from operation capabilities, then structure capabilities, then the default backend wrappers, then the optional OpenBLAS native wrapper, and finally the concrete implementations. This is the intended entry path if you are building a higher-level linear-algebra application library, geometry package, or solver-style library on top of this repository.

#Documentation Entry Points

• immut concrete API: immut.Matrix API, immut.Matrix tutorial, immut.Vector API, immut.Vector tutorial
• mutable concrete API: mutable.Matrix API, mutable.Matrix tutorial, mutable.Vector API, mutable.Vector tutorial
• Capability and backend layers: arithmetic API, algebra API, algebra ecosystem integration, algebra tutorial, container API, container tutorial, container ecosystem integration, backends/default API, backends/openblas API, backends/openblas tutorial, error API

#Used In

• Luna-Flow/geometry3d: a compact MoonBit 3D geometry foundation built on Luna-Flow/linear-algebra, with core geometry, camera/view math, backend-neutral frontend rendering, and TUI / Canvas / GSAP backends. See its English docs for a concrete downstream package layout built on this repository.

#Documentation

• 🇺🇸 English (doc/en_US)
• 🇨🇳 简体中文 (doc/zh_CN)
• 🇯🇵 日本語 (doc/ja_JP)

• 🇺🇸 README.md
• 🇨🇳 README.md
• 🇯🇵 README.md

#Changelog

#Development

moon fmt
moon info
moon check
moon test -p perf_support
moon test -p perf_runner
moon test --enable-coverage
./run_test.sh
LINEAR_ALGEBRA_TEST_BENCH=1 ./run_test.sh

# This repository is primarily a library, so use an explicit package target.
moon run src/perf_runner mul_baseline_dense_64

# Optional: materialize benchmark fixtures ahead of time.
python3 bench/generate_fixtures.py

# Full benchmark flow.
just bench

#Release Checklist

1. Bump moon.mod to the intended next release version before publishing.
2. Update README.md and CHANGELOG.md so the current release notes and historical version notes match the package contents.
3. Run moon check --target all and ./run_test.sh; both are required before publishing.
4. If the change touches benchmark fixtures, fixture recovery, or diagnostic runners, also run LINEAR_ALGEBRA_TEST_BENCH=1 ./run_test.sh.
5. Trigger publish-package; it will publish the version currently declared in moon.mod.