Luna Flow

简体中文

English
日本語

简体中文

English
日本語

Appearance

Luna-Flow/linear-algebra ​

这份 README 对应当前仓库的 v0.4.7 文档基线。

mutable 数值 API 现在使用共享的 Luna-Flow/arithmetic.Sqrt 能力； 整数嵌入遵循 Luna-Flow/luna-generic.IntegralHomomorphism。在当前版本中， Tolerance 仍保留在 mutable 包内。凡是可能在运行时失败的矩阵操作， 现在都使用带检查的 Result[..., LinearAlgebraError] API；旧的 abort 行为 和 Option 返回语义则通过显式的 unchecked_* 方法保留。

0.4.7 这一基线新增了与存储无关的 container 能力层、通用向量与矩阵 算法、面向具体存储表示的适配器，以及供外部类型采用的 algebra 集成层级。

更早的版本说明和仓库历史请参见 CHANGELOG.md。

分层架构 ​

实验性功能： algebra 与 container 能力层目前用于接入试验和收集生态反馈； 它们的 trait 层级、操作字典、错误契约和函数签名尚未承诺兼容性稳定。下游库暂时不应 把这两个包作为稳定的公开兼容边界。immut、mutable 和各后端仅仅因为实现或适配 这些能力，并不会因此整体变成实验性 API。

  • arithmetic：面向线性代数的操作能力层。它复用 Luna-Flow/luna-generic 和 Luna-Flow/arithmetic 中的标量操作 trait， 并在需要时补充只表达“可进行某类操作”的 trait。
  • algebra：数学结构能力层。它只定义线性代数自己拥有的结构 trait。
  • container：与存储无关的 read/build、持久编辑和可变编辑操作字典，以及 map、转换和转置算法。具体适配器位于 container/adapters。
  • backends/default：参考稠密后端层。它公开可变稠密包装类型 DenseVector / DenseMatrix，以及不可变稠密包装类型 ImmutableDenseVector / ImmutableDenseMatrix。
  • backends/openblas：仅支持 native 的 OpenBLAS 后端。它公开仓库自有的 BlasMatrix[T] 与 BlasVector[T] 包装类型，支持 Float 与 Double， 矩阵乘法使用 OpenBLAS GEMM，向量与矩阵-向量交互则使用对应的 BLAS 核心， 后端选择通过具体类型表达，而不是通过运行时 selector 表达。
  • error：带检查线性代数 API 共用的错误词汇层，覆盖形状、指数、空矩阵、 奇异矩阵、非收敛以及底层算术错误。
  • trait 驱动算法：后端无关代码应依赖最小必要能力，例如 MatrixShape、AdditiveVector、VecMulVector、TransposeMatrix 或 MatMulMatrix。

把向量或矩阵映射为标量范畴的能力，例如内积或范数，属于具体后端或算法细节； 它们不属于核心结构 trait 层。

默认稠密实现只是一个后端，不是整个生态的中心。算法应依赖最小的线性代数 trait， 而不是依赖具体的稠密矩阵或向量类型。

这个仓库的定位，是给更上层的数学库、几何库和 solver 风格库提供线性代数基础层。 领域特定的求解、回归或优化工作流，应放在基于这些 trait、后端包装类型和具体 矩阵/向量类型构建的下游包中。

具体的 immut / mutable 矩阵与向量类型，就是 backends/default 包装层所使用的 底层实现。DenseVector 和 DenseMatrix 包装 @mutable.Vector 与 @mutable.Matrix；ImmutableDenseVector 和 ImmutableDenseMatrix 包装 @immut.Vector 与 @immut.Matrix。 如果需要 OpenBLAS 支持的 native 矩阵乘法与向量 BLAS 核心，请显式选择 backends/openblas。它是独立的具体后端， 不是 @immut.Matrix 内部的运行时后端选项。

导览指南 ​

  • 一般应用开发者： 从 mutable 和 immut 开始。它们是面向应用代码的具体 API，适合业务工具、实用程序、数值处理、 小型游戏和可视化逻辑等场景。
  • 数学库 / 通用算法开发者： 建议按这个顺序阅读： arithmetic -> algebra -> container -> backends/default -> backends/openblas -> immut / mutable。 先看操作能力，再看结构能力，再看默认后端包装层，再看可选的 OpenBLAS native 包装层，最后落到具体实现。 如果你准备在这个仓库之上构建更高层的应用库、几何包或 solver 风格包， 这就是推荐的入口路径。

文档入口 ​

下游使用示例 ​

  • Luna-Flow/geometry3d： 一个建立在 Luna-Flow/linear-algebra 之上的 MoonBit 3D 几何基础库。 它在此基础上继续提供核心几何、camera/view 数学、后端无关渲染，以及 TUI / Canvas / GSAP 后端。 它的 英文文档 可以作为一个具体的下游示例入口。

抽象层项目配置 ​

如果你想使用抽象能力层来编写后端无关代码，请显式安装它所依赖的上游抽象包：

sh
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

推荐的 moon.pkg 导入写法：

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

使用 @algebra 表示线性代数结构 trait，@la_arithmetic 表示面向线性代数的 操作 trait，@lf_alg 表示共享的上游代数抽象，@lf_arith 表示共享的上游算术 类型。

仓库定位 ​

同时提供可变与不可变执行模型的矩阵/向量基础设施。

文档布局 ​

  • README.md 用于说明仓库叙事和当前版本基线。
  • doc_standard.md 用于记录文档契约。
  • 各模块或子系统目录下包含 api.md、tutorial.md 和 design.md。
  • doc/* 是手写正文事实源；src/doc_* 包通过软链接把这些文件暴露给 MoonBit 包文档系统。

模块概览 ​

  • immut/matrix：实现位于 src/immut
  • immut/vector：实现位于 src/immut
  • mutable/matrix：实现位于 src/mutable
  • mutable/vector：实现位于 src/mutable
  • arithmetic：实现位于 src/arithmetic
  • algebra：实现位于 src/algebra
  • backends/default：实现位于 src/backends/default
  • backends/openblas：实现位于 src/backends/openblas
  • error：实现位于 src/error