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 バックエンドです。 Float と Double に対応するリポジトリ所有の BlasMatrix[T] と BlasVector[T] ラッパーを公開し、行列乗算には OpenBLAS GEMM を、ベクトルと 行列-ベクトル相互作用には対応する BLAS カーネルを使います。バックエンド選択は runtime selector ではなく具体型で表します。
  • error: 検査付き線形代数 API の共有エラー語彙です。形状、指数、空行列、 特異行列、非収束、下位の算術エラーを扱います。
  • trait 駆動アルゴリズム: バックエンド非依存コードは、 MatrixShape、AdditiveVector、VecMulVector、TransposeMatrix、 MatMulMatrix のような最小限の必要能力に依存するべきです。

内積やノルムのように、ベクトルや行列をスカラー的な量へ写す能力は、 バックエンドまたはアルゴリズムの詳細です。中核の構造 trait 層には含めません。

既定の密実装はあくまで 1 つのバックエンドであり、エコシステムの中心ではありません。 アルゴリズムは具体的な密行列・密ベクトル型ではなく、最小限の線形代数 trait に 依存するべきです。

このリポジトリは、より上位の数学ライブラリ、幾何ライブラリ、solver 風 ライブラリのための線形代数基盤として位置付けています。分野固有の solve、 回帰、最適化ワークフローは、これらの trait、バックエンドラッパー、 具体的な行列/ベクトル型の上に作る下流パッケージへ置く想定です。

具体的な immut / mutable の行列・ベクトル型は、 backends/default が包む実装本体です。DenseVector と DenseMatrix は @mutable.Vector と @mutable.Matrix を包み、ImmutableDenseVector と ImmutableDenseMatrix は @immut.Vector と @immut.Matrix を包みます。 OpenBLAS による native 行列乗算やベクトル BLAS カーネルが必要な場合は、 backends/openblas を明示的に選びます。これは独立した 具体バックエンドであり、@immut.Matrix 内の runtime backend option ではありません。

読者ガイド ​

  • 一般的なアプリケーション開発者: mutable と immut から 読み始めてください。これらは業務ツール、ユーティリティ、数値処理、 小さなゲーム、可視化ロジックのようなアプリケーションコード向けの具体 API です。
  • 数学ライブラリ / 汎用アルゴリズム開発者: 次の順番で読むのがおすすめです。 arithmetic -> algebra -> container -> backends/default -> backends/openblas -> immut / mutable。 まず操作能力、次に構造能力、その次に既定バックエンドのラッパー、さらに任意の OpenBLAS native ラッパー、最後に具体実装へ進みます。より上位のアプリケーションライブラリ、幾何パッケージ、 solver 系パッケージをこの上に構築する場合の推奨入口でもあります。

ドキュメント入口 ​

下流での利用例 ​

  • Luna-Flow/geometry3d: Luna-Flow/linear-algebra の上に構築された、MoonBit 用のコンパクトな 3D 幾何基盤です。その上で core 幾何、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 の import 例:

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 パッケージ ドキュメント向けに、それらのファイルを symlink で公開します。

モジュール概要 ​

  • 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