#LINEAR-ALGEBRA

#v0.2.11 - Performance, Benchmarks & API Alignment

#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.

#What Defines v0.2.11

• Matrix Views: mutable now exposes RowView and ColView for repeated structured row/column work without materializing copies.
• Unified Flattened Storage: mutable.Matrix now uses a shared flat Array[T] storage model across backends, instead of documenting backend-specific layout differences.
• Cross-Package Consistency Checks: Added dedicated consistency tests to keep shared immut / mutable algebraic behavior aligned.
• Numerical Fixes: Hardened mutable LU-based routines, including pivot-permutation handling and broader numerical corner-case behavior.
• Immutable Core Alignment: immut.Vector continues to build on the optimized core immutable vector implementation, which makes the flattened storage direction practical across the library.
• Dedicated Wasm GC Backend: mutable now includes a dedicated wasm-gc backend rather than treating it as a thin variation of earlier backend code paths.
• Numeric Trait Cleanup: Mutable numerical APIs now align more directly with Field / Num / Tolerance style constraints, while immutable determinant constraints were simplified.
• Symmetric Eigen Performance: The symmetric real eigenpath has been accelerated as part of the current release line.
• Kernel-Level Mutable Optimizations: Follow-up backend kernel work reduced overhead in repeated matrix operations after the original storage unification pass.
• Dependency Upgrade: The current repository depends on Luna-Flow/luna-generic 0.3.0 and moonbitlang/quickcheck 0.14.0.
• Modern Moon Package Metadata: The repository now carries moon.mod as the canonical package manifest format for the current toolchain generation.
• Release Workflow Confirmation: The publish workflow now reads the release version directly from moon.mod, keeping release metadata aligned with the canonical manifest.
• Benchmark Harness & Dashboard: The repository now ships a fixture-driven benchmark harness, runtime fixture loading, richer reporting, a local web dashboard, and an optional Rust baseline for local or ad hoc comparison runs.

#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.
• 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.
• 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.

#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

let imm = @immut.Matrix::from_2d_array([[1, 2], [3, 4]])
let imm_updated = imm.set(0, 1, 9)

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

let det = m.determinant()
let maybe_inv = m.inverse()
let row0 = m.row_view(0).to_array()

#Documentation

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

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

#Version History

#Current Repository Highlights

• Current Release Narrative (0.2.11):
  • mutable.Matrix now combines the shared flat storage model from 0.2.10 with follow-up backend kernel optimizations and a dedicated wasm-gc implementation.
  • Public numerical signatures are aligned around Field / Num / Tolerance, and immutable determinant documentation matches the simplified post-0.2.10 constraint set.
  • The benchmark stack now includes runtime-loaded fixtures, expanded case metadata, richer summary reporting, a local dashboard, optional Rust comparison runs, and diagnostic replay via perf_runner.
  • The release checklist, benchmark docs, package overview, and localized READMEs are aligned to the 0.2.11 release story.

• Algorithms & Stability (0.2.8):
  • Added LU- and QR-related decomposition support used by determinant, inverse, rank, and eigen routines.
  • Shifted determinant and rank behavior toward more stable elimination-based implementations.

• Native Optimization (0.2.7):
  • Implemented transposition + dot-product strategy for Native matrix multiplication, outperforming naive implementations by more than 2x.
  • Optimized make, new, and transpose to remove expensive integer division in hot loops.

• Performance Overhaul (0.2.4):
  • Optimized secondary utilities such as mapi and each_row_col.
  • Improved hybrid matrix multiplication and vector linear-combination performance.

• Other Fixes & Renames:
  • map_row() / map_col() -> map_row_inplace() / map_col_inplace()
  • eachij() -> each_row_col()
  • Corrected determinant behavior for 0x0 matrices.
  • Fixed copy-on-conversion behavior between vectors and matrices.

#Development

moon fmt
moon check
moon test --enable-coverage
./run_test.sh

#Release Checklist

1. Bump moon.mod to the intended next release version before publishing.
2. Update README.md so the release notes and version history match the package contents.
3. Run moon check and ./run_test.sh.
4. Trigger publish-package; it will publish the version currently declared in moon.mod.