#2552 公開 API 文法:実装指示書
この文書は、#2552 で決まった公開 API の文法を実装する人(人間とエージェント)への指示書です。何を作り、何を消し、どの順で進め、何をもって完了とするかを、迷わずに作業できる粒度で書きます。
- 設計の理由と全体像は 提案書 を読んでください。この文書は理由を繰り返しません。
- ここに書いた判断は、#2552 の決定を実装の言葉に直したものです。スレッドで決まっていなかった点は、本書が [本書で決定] として決めています。異論があれば実装前に #2552 で議論し、この文書を直してから進めてください。黙って別の形で実装しないでください。
- 基準は
origin/mainの90348dc0です。行番号は目安で、作業時に必ず読み直してください。
0. 作業を始める前に
0.1 必ず読むもの
| 順 | 文書 | 読む理由 |
|---|---|---|
| 1 | AGENTS.md、tensor4all 共有ルール(rules/index.md) |
リポジトリ全体の作法 |
| 2 | REPOSITORY_RULES.md |
実装前・PR 作成前に読み直す(AGENTS.md の指示)。ただし「Public API Convention」節は本作業で書き換える対象(§8) |
| 3 | PERFORMANCE_TIPS.md 全文 |
実行経路に触るため。特に「Materialization And Copies」 |
| 4 | api-consolidation-policy.md の R3 と R8 |
レイアウト変換の扱い。実体化ポリシーは撤回済み |
| 5 | #2552 の決定コメント群 | 下の §0.3 |
| 6 | プロトタイプブランチ prototype/2552-api-grammar の ext/api-grammar-proof/ |
各試作の実装と findings/p1.md〜p7.md。新しい形の動く見本。P7(借用エンジンとレーン)は crates/tenferro-cpu/src/borrowed_engine.rs にフックがある |
0.2 ツールチェーン
- ワークスペースは
rust-version = "1.96"を要求します。1.96 以上の stable で作業してください。 - プロトタイプは 1.93 nightly に
RUSTFLAGS="-Zcrate-attr=feature(atomic_try_update)"と--ignore-rust-versionを付けて動かしました。この回避策を PR の検証に使ってはいけません。 cargo public-apiは nightly の rustdoc JSON を使います。CI のplacementジョブが既にインストールしているものと同じ版を使ってください。
0.3 決定事項の出典
| 項目 | 出典(#2552 のコメント) |
|---|---|
| 文法・7 ルール・決定 1〜6 | 6760660549(Decision: one call grammar) |
| 結果型、エラー、einsum の出力先、FFT、例外の考え方 | 6762219245(inventory v0.1) |
v0.1 への修正(policy の位置、Svd<V, R> など) |
6762266144(review of v0.1) |
| 例外表 E01〜E09、エラー supertrait の見送り、プランとキャッシュ所有者 | 6762340249(inventory v0.2) |
| プロトタイプの結果 | 6763055062 |
| 借用エンジンとレーン(P7) | プロトタイプブランチの ext/api-grammar-proof/findings/p7.md(#2552 へはまだ投稿していない) |
| 実体化ポリシーの撤回、公開カウンタを要件にしない | 6763124519、6764423689(後者が最終) |
MaterializationPolicy、InputMaterializationForbidden、公開の正規化カウンタは 作りません。設計資料やプロトタイプにこれらが出てきても、実装しないでください。
1. 作業の進め方
1.1 ブランチと PR
- 文法の移行は、
origin/mainから切った作業ブランチapi-grammar-0.121 本に積みます(AGENTS.md「Working Branches For Multi-Commit Work」)。 - main への PR はバッチが終わってから 1 回だけ出します。ファミリーごとに main へ PR を出してはいけません。理由は次の2つです。
- 文法の変更と規約ファイルの書き換えは同じ PR に入れる決まりです(提案書ルール 7)。途中で main に入れると、新旧どちらの文法も通る期間ができます。
- CI のコストを抑えるためです。
- 作業ブランチの中では、下の段階ごとにコミットを分け、各段階の終わりで
cargo test --workspaceが通る状態にします。 - 例外として、§9 の独立した修正(#2565 の共役バグ、隠れたコピーの削減)は、それぞれ main から切った別ブランチで、通常の PR にします。文法の変更を待つ必要はありません。
- この移行は破壊的変更で、0.12 で 1 回だけ出します。旧 API を非推奨として残すことも、互換シムを置くこともしません(REPOSITORY_RULES.md「No compatibility shims」)。
1.2 段階
| 段階 | 内容 | 節 | 前提 |
|---|---|---|---|
| S0 | 現行の公開 API スナップショットを記録し、CI に入れる | §2 | なし。main への単独 PR にしてよい |
| S1 | 共通の型を追加する(Dest、軸、制御用の列挙型、結果構造体) |
§3 | S0 |
| S2 | 演算レジストリと生成マクロ、例外表を作る | §4 | S1 |
| S2b | レーン(CpuEngine::with_lanes)と、レーン用の借用エンジンを入れる |
§5.6 | S1 |
| S3 | linalg を移行する(*_with_exec の削除を含む) |
§5 | S2、S2b |
| S4 | einsum を移行する | §6 | S2。#2565 の修正が main に入っていること |
| S5 | FFT を移行する | §7.1 | S2 |
| S6 | core 演算を移行する(runtime と ad) | §7.2 | S2 |
| S7 | 規約・仕様・ガイド・スキルを書き換え、旧チェッカーを整理する | §8 | S3〜S6 |
| S8 | スナップショットを更新し、PR を出す | §10 | S7 |
S3〜S6 は互いに独立しているので、作業ブランチから枝を切って並行して進め、終わったら作業ブランチへマージしてかまいません。ただし同じファイルを触る場合は順番に進めてください(tenferro-tensor の共通型は S1 で確定させておく)。
2. S0:現行 API の基準スナップショット
目的。 移行前の公開 API を記録し、移行中と移行後の差分を、レビューで必ず目に入るようにします。新しい設計の承認ではありません。
作るもの
api/ディレクトリをリポジトリ直下に作ります。scripts/api-snapshot.shを作ります。--write:公開クレートごとにcargo public-api -p <crate> --features <固定の組み合わせ>を実行し、api/<crate>.txtに書き出します。--check:同じ出力を作り、api/のファイルとdiffします。差分があれば終了コード 1 です。- 対象クレートは workspace の公開クレート全部です(
publish = falseは除く)。ext の独立マニフェスト(ext/tropical、ext/sparse)は--manifest-pathで別に扱います。 - feature の組み合わせはクレートごとにスクリプトの中で固定し、そのことを
api/README.mdに書きます。最低限、既定の feature と、autodiff/nativeのように公開面を増やす feature を有効にした組み合わせの2つを取ります。
.github/workflows/ci.ymlのplacementジョブ(cargo-public-apiと nightly を既にインストールしている)に、scripts/api-snapshot.sh --checkを実行するステップを足します。api/README.mdに、スナップショットの更新方法(--writeを実行して差分をコミットする)と、「スナップショットはレビューの証拠であって、振る舞いの証明ではない」ことを書きます。
完了条件 - main で --check が成功し、CI の placement ジョブが緑になること。 - わざと公開関数を 1 つ足すと --check が失敗すること。これは PR の Verification 節に出力を貼って示します。
3. S1:共通の型
置き場所の原則は次のとおりです。 - 複数ファミリーが使う型は tenferro-tensor に置きます。 - 1 つのファミリーだけが使う型は、そのファミリーのクレートに置きます。
新しい公開型には、どれも /// # Examples を付け、doctest が実際に実行されるようにします(ignore と no_run は使わない)。
3.1 出力先 Dest(tenferro-tensor)
/// Where an `_into` operation writes, and how it combines with what is there.
#[derive(Debug)]
#[non_exhaustive]
pub enum Dest<W> {
/// out = op(...); the previous contents are never read.
Overwrite(W),
/// out = op(...) + out.
Accumulate(W),
/// out = alpha * op(...) + beta * out; with beta == 0 the previous
/// contents are never read (NaN or -0 in out does not leak).
Scaled { out: W, alpha: ContractionScalar, beta: ContractionScalar },
}
impl<W> Dest<W> {
pub fn overwrite(out: impl Into<W>) -> Self;
pub fn accumulate(out: impl Into<W>) -> Self;
pub fn scaled(out: impl Into<W>, alpha: impl Into<ContractionScalar>,
beta: impl Into<ContractionScalar>) -> Self;
}Wは erased ではTensorWrite<'a>、typed ではTypedTensorWrite<'a, T>です。どちらも&mut Tensorや&mut TypedTensor<T>からのFromが既にあります。Destは「どこに、どう書くか」だけを表します。共役は演算の意味なので、Destには入れずXxxOptionsに入れます(v0.1 の合意)。- 既存の
DotGeneralAccumulation { lhs_conj, rhs_conj, alpha, beta }(crates/tenferro-tensor/src/backend.rs:387)との対応は次のとおりです。OverwriteはDotGeneralAccumulation::overwrite(dtype)に当たります。Accumulateはadd_to(dtype)に当たります。Scaledはscaled(alpha, beta)に当たります。lhs_conj/rhs_conjは演算の options から埋めます。- この変換は
Destの非公開ヘルパー 1 か所に書きます。プロトタイプ P2 のp2_einsum_dest.rsに動く見本があります。
DotGeneralAccumulation自体はバックエンドのフック(TensorDot::dot_general_read_into_accumなど)の引数として残します。公開の演算シグネチャからは消します。[本書で決定] バックエンド trait は公開面の op 文法の対象外です(例外 E10。§4.3 で表に追加する)。AccumulateとScaledを受け付けるのは、レジストリでinto: [overwrite, accumulate, scaled]と宣言した演算だけです。宣言していないモードは、実行前にError::Unsupportedを返します。
3.2 軸(tenferro-tensor-core に関数、型は isize)
公開シグネチャの軸はすべて
isizeにします。負の値は末尾から数えます(-1が最後の軸)。長さ、次元、形状、IR の識別子は
usizeのままです。対象は「軸を指す引数」だけです。名前で言えばaxis、axes、axis_a/axis_b、dim(軸の意味のもの)、perm(転置の置換)です。正規化は 1 か所に書きます。
pub fn normalize_axis(axis: isize, rank: usize) -> Result<usize, ValidationError>; pub fn normalize_axes(axes: &[isize], rank: usize) -> Result<AxisVec, ValidationError>;範囲外は既存の
ValidationError::AxisOutOfBoundsを返します。AxisOutOfBounds { axis: usize, .. }は元のisizeを保持できないので、axis: isizeに変えます。重複はDuplicateAxisを返します。FFT は既に
isizeなので、そのまま使えます。移行対象は runtime(約 77 シグネチャ)、linalg のnorm(dim引数)、ad のEagerSessionの固有メソッドです。数は棚卸しのスクリプトで数えた概数なので、作業時に grep で数え直してください。
3.3 制御フラグの列挙型(bool を置き換える)
公開シグネチャの制御用 bool は、次の列挙型に置き換えます。真偽値のデータ(TypedTensor<bool>、述語、マスク)は対象外です。
| 旧 | 新(置き場所) |
|---|---|
triangular_solve(b, left_side, lower, transpose_a, unit_diagonal) |
TriangularSolveOptions { side: Side, uplo: Uplo, op: MatOp, diag: Diag }(linalg) |
norm(ord, dim, keepdim) |
NormOptions { ord: NormOrd, axes: Option<AxisVec>, keep_dims: KeepDims }(linalg) |
svd_with_exec(.., full: bool) |
関数ごと削除し、レーンの中で view.svd_with(&SvdOptions::default().shape(SvdShape::Full), lane) を使う(§5.6) |
dot_general_with_conj(rhs, config, lhs_conj, rhs_conj) |
dot_general_with(&rhs, config, &DotGeneralOptions { lhs: Conj, rhs: Conj }, exec)(tensor) |
LinalgBackend::full_piv_lu_solve(.., transpose_a) |
バックエンド trait なので E10 として対象外 |
pub enum Side { Left, Right }
pub enum Uplo { Lower, Upper }
pub enum MatOp { None, Transpose, Adjoint } // 既存の transpose_a は None/Transpose に写す
pub enum Diag { NonUnit, Unit }
pub enum Conj { No, Yes }
pub enum KeepDims { No, Yes }- どれも
Clone, Copy, Debug, PartialEq, Eq, Hashを derive し、#[non_exhaustive]は付けません(値が増える見込みがないため)。 - 既定値は
Defaultで明示します。現行の暗黙の既定に合わせて、Side::Left、Uplo::Lower、MatOp::None、Diag::NonUnit、Conj::No、KeepDims::Noとします。 MatOp::Adjointは現行の4つの bool では表せません。[本書で決定] 複素入力でAdjointが来た場合は、実装できていなければError::Unsupportedを返します。黙ってTransposeとして扱ってはいけません。
3.4 Options の形
意味のある設定項目を持つ演算にだけ XxxOptions を 1 つ置き、op_with を生成します。設定項目のない演算には Options 型も op_with も置きません(#2552 Q14 の決定。決定 2 を改める)。あとから最初の設定項目が必要になったら、レジストリに options: XxxOptions を書き、op_with を生成します。名前は文法で決まり、既存の呼び出しは壊れません。空の Options を先に公開すると、後で消すことが破壊的変更になるため置きません。
#[derive(Clone, Debug, Default, PartialEq)]
#[non_exhaustive]
pub struct SvdOptions {
pub shape: SvdShape, // Thin / Full
pub gauge: SvdGauge,
pub driver: SvdDriver,
pub derivative_eps: f64,
}
impl SvdOptions {
pub fn shape(mut self, v: SvdShape) -> Self { self.shape = v; self }
// 1 フィールドにつき 1 セッター。名前はフィールド名と同じ。
}#[non_exhaustive]を付けるので、利用者は構造体リテラルで作れず、Default::default()とセッターで作ることになります。- セッターの名前はフィールド名と同じにし、
with_は付けません。現行のSvdOptions::gauge()などがこの形なので、それに合わせます。 Copyは付けられる場合だけ付けます。EinsumOptionsはツリーを持つのでCloneだけです(§6.2)。- 意味の違いはすべてここに入れます。実行器、出力先、入力は入れません。
3.5 結果構造体(linalg)
crates/tenferro-linalg/src/results.rs を新設し、次の構造体を定義します。
pub struct Svd<V, R = V> { pub u: V, pub s: R, pub vh: V }
pub struct Qr<V> { pub q: V, pub r: V }
pub struct Lu<V, R = V> { pub p: V, pub l: V, pub u: V, pub parity: R }
pub struct FullPivLu<V, R = V> { pub p: V, pub l: V, pub u: V, pub q: V, pub parity: R }
pub struct Eig<C> { pub values: C, pub vectors: C }
pub struct Eigh<V, R = V> { pub values: R, pub vectors: V }
pub struct Slogdet<V, R = V> { pub sign: V, pub log_abs_det: R }
// 既存のものはそのまま使う
pub use crate::rank_revealing_qr::RankRevealingQrResult; // <V, I = V>
pub use crate::householder::HouseholderQr;- フィールドはすべて
pubにします。分解して受け取るlet Svd { u, s, vh } = ...を主な使い方とするためです。derive はClone, Debugだけにします。 - フィールドの順序と意味は、現行のタプルの順序と一致させます。現行のタプル別名は
TypedSvd<T>=(U, S, Vh)、TypedLu<T>=(P, L, U, parity)、TypedFullPivLu<T>=(P, L, U, Q, parity)、TypedEig<T>=(values, vectors)です(tensor_ext.rs:272-329)。eighは現行(values, vectors)の順です。移行時に、タプルの順序から構造体のフィールドへの対応をテストで固定してください。 - LU の
pは、現行どおり置換行列のテンソルです。ピボットの添字ベクトルに変えてはいけません(v0.1)。 - 型パラメータは次のように決まります。
- erased の層では、
V、R、CはどれもTensor(traced はTracedTensor、eager はEagerTensor)です。 - typed の層では、たとえば
Svd<TypedTensor<T>, TypedTensor<T::Real>>、Eig<TypedTensor<T::Complex>>になります。T::RealとT::ComplexはLinalgScalarの関連型で、既にあります。
- erased の層では、
- タプル別名
TypedSvd、TypedLu、TypedFullPivLu、TypedEig、TypedRankRevealingQrResultと、privateモジュール内のSvd<T>は削除します。
4. S2:演算レジストリ、生成マクロ、例外表
4.1 形
[本書で決定] レジストリは Rust の宣言マクロ呼び出しとして書き、それ自体を唯一の出典にします。TOML などの別ファイルは作りません。理由は、別ファイルにすると、宣言と生成されたコードの一致を確かめる仕組みがもう 1 つ必要になるからです。
- マクロの定義は既存の
tenferro-internal-extension-macrosにapi_ops!として置きます。 - 呼び出しは、ファミリーごとに
crates/<family>/src/api/registry.rsに 1 つ書きます。core はtenferro-runtimeに置きます。 - core の
primitive_ops!(crates/tenferro-core-ops/src/catalog.rs:81)は IR プリミティブの一覧で、公開 API の一覧ではありません。流用せず、そのまま残します。公開 API のレジストリとは別物です。
1 エントリの形は次のとおりです(項目は v0.1 と v0.2 が求めたもの)。
api_ops! {
family: linalg,
op svd {
operands: (a), // 受け手のあとに続く必須の入力。受け手を含む
options: SvdOptions,
output: Svd<V, R>, // V/R/C/I の対応で書く
dtypes: floating_or_complex, // 入力 dtype と出力 dtype の関係
layers: [concrete, eager, traced],
into: [], // 空なら _into を生成しない
layout: "Strided rank-2 read directly; negative strides and \
non-compact batches of rank >= 3 are gathered once \
(same placement and dtype).", // R3 の文書化
errors: [Validation, NumericalFailure(NonConvergence), Unsupported],
omissions: [], // 層やバックエンドで未対応のもの(理由つき)
}
op solve {
operands: (a, b),
options: none, // 設定項目のない演算。Options 型も _with も置かない
output: V,
dtypes: floating_or_complex,
layers: [concrete, eager, traced],
into: [overwrite],
layout: "...",
errors: [Validation, NumericalFailure(Singular)],
omissions: [],
}
}4.2 マクロが生成するもの(と生成しないもの)
生成するもの - 各層のトレイトのメソッド宣言と、本体への転送。op、op_with、op_into(into が空でないときだけ)の3形です。op は op_with(&Default::default(), ..) に転送するだけのものにします。 - rustdoc。これには次が含まれます。 - 1 行の説明 - layout の文 - errors の一覧 - レジストリのエントリに書いた例を使った # Examples - テスト用のメタデータ定数 pub(crate) const API_OPS: &[ApiOpDescriptor]。
生成しないもの - 数値計算の本体。本体は手で書いた非公開関数 fn svd_impl(view: TensorRead<'_>, opts: &SvdOptions, exec: &mut dyn Engine) -> Result<Svd<Tensor>> などで、マクロはそこへ転送するだけです(v0.2 D)。 - Dest を書き込みの形に変える処理。これは §3.1 の共通ヘルパーで行います。
REPOSITORY_RULES.md「Wrapper DRY And Codegen」が求めることも守ります。 - 生成された名前、ドキュメント、feature gate、エラーの振る舞いが、呼び出し側から見て分かること。 - 生成された転送のどれかが壊れたら失敗するテストを置くこと。具体的には §4.4 のテストです。
4.3 例外表
レジストリと同じマクロ呼び出しの中に exceptions { ... } 節を置きます。v0.2 の形 id, scope, category, owner_module, reason, verification, exit_condition をそのまま使います。
| ID | 範囲 | 今回の扱い |
|---|---|---|
| E01 | 消費型 FFT(fft_in_place / ifft_in_place) |
存続。受け手を session に移す(§7.1) |
| E02 | FftExecutor(キャッシュ所有者) |
存続。引数順だけ文法に合わせる(§7.1) |
| E03 | ConcreteEinsumPlan::clear_cpu_cache / cpu_cache_stats |
存続。名前は変えない |
| E04 | TraceContext / compile / prepare / run のライフサイクル | 文法の対象外。別スナップショットで固定 |
| E05 | 記述子だけの操作とメタデータ問い合わせ(shape、dtype、into_dynamic、ビュー作成など) |
文法の対象外。データをコピーしないことをテストする |
| E06 | 承認した外部型(num_complex::Complex など)と bridge |
シンボル単位の許可リスト。api/allowlist.txt |
| E07 | TraceValue の einsum 入口 |
退役(§6.4)。表には履歴として残す |
| E08 | *_with_exec 自由関数 6 本 |
退役。P7 で4条件を確かめた。レーンと借用エンジンに置き換える(§5.6)。表には履歴として残す |
| E09 | パーサーとプランナーの領域エラー、所有権を返す失敗 | 存続 |
| E10 | [本書で決定・追加] バックエンド trait(Engine、TensorDot、LinalgBackend、FftBackend など)と、その *_read_into_accum フック |
op 文法の対象外。provider 向けの契約として別に扱う |
例外表のエントリは、モジュール単位ではなく、具体的なシンボルの名前で書きます。
4.4 生成物を守るテスト
crates/<family>/src/api/tests/registry.rs に、少なくとも次のテストを置きます。
- 転送のテスト:
API_OPSの全エントリ × 全層について、opとop_with(&Default::default())が同じ結果を返すこと。数値は固定の小さな入力で比べ、bit 一致を要求します。 - 入力の形のテスト(ルール 2): 1 つの演算について、次の5種類の入力が同じ結果を返すこと。数値計算の契約が違う場合は、許容誤差を明記します。
- 所有テンソル
- コンパクトな借用ビュー
- 転置したビュー
- 負ストライドのビュー
- typed のテンソル
_intoのテスト:intoを宣言した演算で、次の3点を確かめること。Overwriteは、NaN で埋めた出力先を読まない。Accumulateは加算になる。Scaled { beta: 0 }は、NaN や-0を漏らさない。
- 宣言どおりのテスト: 宣言していない
intoモードとomissionsに書いた組み合わせが、実行前にUnsupportedを返し、出力先を変えないこと。
4.5 生成するドキュメント
docs/spec/generated/api-ops.md に、次の3つを書き出します。 - 演算 × 層の表 - 接尾辞の一覧 - 例外表
書き出しは cargo test -p <family> api_docs_are_current が行います。テストは生成した内容とコミット済みのファイルを比べ、違えば失敗し、UPDATE_API_DOCS=1 で上書きします。docs/_quarto.yml の Specification 節に、このファイルを追加します。
5. S3:linalg
5.1 消すもの
- トレイト:
TensorLinalgExt、TensorReadLinalgExt、TypedTensorLinalgExt、TracedTensorLinalgExt、TraceContextLinalgExt、EagerSessionLinalgExt、EagerTensorLinalgExt。 - 名前:
*_read、svd_full、svd_with_options、qr_with_options、eigh_with_options、pinv_with_rtol、solve_read_into。 - タプル別名(§3.5)と
prelude内の旧トレイト。
5.2 作るもの
| 層 | トレイト | 受け手 | 形 |
|---|---|---|---|
| concrete | LinalgOps |
AsView を実装するすべての型(§5.3) |
a.svd(exec)、a.svd_with(&opts, exec)、a.solve_into(&b, &opts, exec, dest) |
| traced | TracedLinalgOps |
TracedTensor |
t.svd()、t.svd_with(&opts) |
| eager | EagerLinalgOps |
EagerSession<'_> |
sess.svd(&x)、sess.svd_with(&x, &opts) |
execは&mut dyn Engineで、最後の引数です。_intoのときだけ、そのあとにdestが来ます。演算の一覧は次のとおりです。21 演算で、どの層も同じ集合にします。
svd, svdvals, qr, householder_qr, rank_revealing_qr, lu, full_piv_lu, full_piv_lu_solve, solve, lstsq, triangular_solve, cholesky, eig, eigvals, eigh, eigvalsh, slogdet, det, inv, pinv, norm
現行は層ごとに集合が違います(concrete に
lstsqがない、traced と eager にsvdvalsがない、typed にhouseholder_qrがない)。実装できるものは実装します。すぐに実装できないものは、レジストリのomissionsに理由つきで書きます。黙って抜けたままにしてはいけません。戻り値のエラー型は次のとおりです。
- concrete は
tenferro_tensor::Result。 - traced と eager は
tenferro_runtime::Result。tenferro_ad::Resultは同じ型の再エクスポートです。 tenferro_linalg::Error(NonConvergence、NonFinite、Singular、UnsupportedDType)は、外側エラーのsource()からdowncast_refで取り出せるようにします(§5.5)。tenferro_linalg::Result別名は、linalg 固有の補助関数のために残します。
- concrete は
5.3 入力アダプタ AsView
pub trait AsView {
type Repr: LinalgRepr; // erased か typed<T> かを表す
fn as_read(&self) -> TensorRead<'_>; // メタデータだけの変換。コピーしない
}
pub trait LinalgRepr {
type Value; type Real; type Complex; type Index;
fn wrap_value(t: Tensor) -> Result<Self::Value>; // typed は検査つきダウンキャスト
fn wrap_real(t: Tensor) -> Result<Self::Real>;
/* ... */
}
impl AsView for Tensor { type Repr = Erased; /* ... */ }
impl AsView for TensorRead<'_> { type Repr = Erased; /* ... */ }
impl<T: LinalgScalar> AsView for TypedTensor<T> { type Repr = Typed<T>; /* ... */ }
impl<T: LinalgScalar> AsView for TypedTensorView<'_, T> { type Repr = Typed<T>; /* ... */ }- 本体は erased の
TensorReadの上に 1 つだけ書きます。typed は、結果を検査つきのダウンキャストで typed に戻します。現行のTypedTensorLinalgExtの実装(tensor_ext.rs:2361)が既にこの形なので、それを一般化します。プロトタイプ P1 で、これで1つの実装を共有できることを確かめています。 - 検査つきダウンキャストが失敗したら、内部エラーとして
Error::Internalを返します。unsafe なキャストやunwrapを使ってはいけません。 LinalgOpsはimpl<X: AsView> LinalgOps for Xという blanket impl で与えます。利用者がOutの型を書かなくてよいことを、doctest で確かめます。
[本書で決定] 負ストライドの扱いをそろえます。現行の typed の借用入口(svd_with_exec)は負ストライドを拒否し、erased の経路は gather して受け付けます(P1)。新しい入口は erased と同じく受け付け、そのことをレジストリの layout に書きます。
5.4 Options の対応
| 演算 | Options | 中身(旧からの対応) |
|---|---|---|
| svd | SvdOptions |
shape: SvdShape::{Thin, Full}(旧 svd_full)、gauge、driver、derivative_eps |
| svdvals | SvdvalsOptions |
driver |
| qr | QrOptions |
gauge(既存) |
| householder_qr | なし | 設定項目がないので Options 型も _with も置かない |
| rank_revealing_qr | RankRevealingQrOptions |
既存(gauge、rtol、atol) |
| lu / full_piv_lu | なし | 同上 |
| full_piv_lu_solve | なし | 同上 |
| solve / lstsq | なし | 同上 |
| triangular_solve | TriangularSolveOptions |
§3.3 |
| cholesky | CholeskyOptions |
uplo(現行は下三角固定なので、既定を Lower にし、Upper は未対応なら Unsupported) |
| eig / eigvals | なし | 同上 |
| eigh / eigvalsh | EighOptions / EigvalshOptions |
既存(gauge、driver、derivative_eps) |
| slogdet / det / inv | なし | 同上 |
| pinv | PinvOptions |
rtol: Option<f64>(旧 pinv_with_rtol) |
| norm | NormOptions |
§3.3 |
二点、注意があります(どちらもプロトタイプ P1 で分かったこと)。 - SvdShape::Full と gauge の組み合わせ: 今は実装がありません。svd_with_options* は thin のみで、apply_svd_gauge は pub(crate) です。full と既定以外の gauge の組み合わせは、実装するまで Unsupported を返し、そのことをレジストリの omissions に書きます。 - SvdDriver: 指定しても結果が bit 単位で変わりません。[本書で決定] フィールドは残します。ドキュメントには「provider が driver を選べる場合のヒントで、現行の CPU provider では効果がない」と書きます。効果が出るまで、テストで「受け付けること」だけを確かめます。
5.5 エラー原因の保存
プロトタイプ P5 で、次のことが分かっています。 - tenferro_ad::Error は tenferro_runtime::Error と同じ型です。外側のエラー型は2つです。 - transparent なラッパーは source() を素通しするので、source() をたどっても、包まれた tenferro_tensor::Error そのものが見つかりません。 - traced の einsum では、kind() と、たどれる原因が食い違うことがあります。
やることは次の4つです。 1. linalg の数値的な失敗は、tenferro_tensor::Error::Extension { op, family, kind, source } に、source が tenferro_linalg::Error になる形で入れます。kind は source.kind() から作ります。現在の作り方を確認し、直接埋めている箇所があれば source から導く形に直します。 2. runtime と eager の層で包むときに source を保ち、err.source() の連鎖から tenferro_linalg::Error へ downcast_ref できることを、3 層それぞれでテストします。P5 の p5_error_causes.rs をテストの見本にしてください。 3. #[error(transparent)] の variant は、source() で包んだエラーそのものを返さず、その原因を返します。tenferro_tensor::Error そのものをたどって見つけたい場合のために、[本書で決定] runtime 側の TensorRuntime(#[from] tenferro_tensor::Error) から #[error(transparent)] を外し、#[error("{0}")] TensorRuntime(#[from] tenferro_tensor::Error) にします(#[from] が #[source] を兼ねる)。表示される文字列は変わりませんが、source() が包んだエラー自身を返すようになります。 4. 新しい公開エラートレイト(TensorError など)は追加しません(v0.2)。
5.6 *_with_exec の退役と、レーン(S2b)
背景
svd_with_exec、svd_values_with_exec、qr_with_exec、eigh_with_exec、eigh_values_with_exec、eig_values_with_exec(with_exec.rs)は、#2462 の要望で足されたものです。1 つの Engine に入ったまま、スレッドをレーンに分け、レーンごとに別の分解を同時に走らせるための入口です。Engine の入口は Engine 全体を &mut で占有するので、この使い方ができませんでした。そこで、Engine が中で組み立てる部品(そのレーンのトークンの束 Exec と、そのレーン専用の BufferPool)を、直接引数で受け取る形になっています。
v0.1 と v0.2 は、これらを消す条件として、借用エンジンの試作で4点(ライフタイム、バッファの再利用、入れ子と並行の実行、呼び出し後に保持しないこと)を確かめることを求めていました。P7 でこの4点をすべて確かめました(findings/p7.md)。
| 条件 | P7 の結果 |
|---|---|
| ライフタイム | 借用エンジンが、スタック上の Exec と BufferPool を借りたまま &mut dyn Engine として使える。'static は不要 |
| 再利用と割り当て 0 | 定常状態の割り当てが、svd(thin と full)、svdvals、qr、eigh、eigvalsh、eigvals、complex64 の svd、rank 8 の qr のすべてで 0。*_with_exec と同じ。バッファはすべて呼び出し側のプールから出て、Engine のプールは増えない |
| 入れ子と並行 | with_exec と with_contraction_exec の中で動く。4 スレッドのチームを [3, 1] と [2, 2] に分け、2 つの分解を同時に実行して、結果が基準と bit 一致した。デッドロックしない。レーンで panic すると、外側の Engine が with_exec のときと同じく broken になる |
| 保持しない | プールを先に捨てる、Exec より長く生かす、の2つがコンパイルエラーになる(compile_fail の doctest)。出力が Engine とプールより長生きしても、ただの所有ストレージになるだけ |
作るもの(tenferro-cpu)
CpuEngine::with_lanes(公開)pub fn with_lanes<R: Send>( &mut self, shares: &[usize], // レーンごとのスレッドの取り分。合計は Engine の予算以下 pools: &mut [BufferPool], // レーンごとのプール。呼び出し側が持ち、呼び出しをまたいで再利用する f: impl Fn(usize, &mut dyn Engine) -> R + Sync, ) -> Result<Vec<R>>;- 内部では
with_execに入ります。そこでexec.token().fork_sized_slots(shares, ..)によりトークンを分け、各レーンでtcontract_exec::Exec::from_tokenから束を作ります。 - 各レーンには、その束とプールを借りた借用エンジンを
&mut dyn Engineとして渡します。 - 次の3つは、実行前に検証エラーを返し、Engine を使える状態のまま残します。
sharesの合計が予算を超えるsharesに 0 があるsharesとpoolsの長さが違う
- プールを呼び出し側に持たせるのは、プールを呼び出しをまたいで温めておくためです。割り当て 0 は、同じプールを使い続けることで成り立つ性質です(P7)。
- Rayon を直接使ってはいけません。分割は threadteam の fork だけで行います(
PERFORMANCE_TIPS.md)。
- 内部では
BorrowedCpuEngine<'a, 'e>(非公開、pub(crate))&'a mut Exec<'e>と&'a mut BufferPoolを持ち、Engineを実装します。native_engine()は、crate 内だけで使うマーカーで自分を指します。P7 のcrates/tenferro-cpu/src/borrowed_engine.rsをそのまま出発点にしてください。- 公開型にはしません。 この型は
Engineの必須メソッド 48 個をすべてUnsupportedで返すので、利用者に Engine として見せられる型ではありません(P7 の F3)。利用者が触れるのは、with_lanesの中で渡される&mut dyn Engineだけです。
with_borrowed_cpu_engine(engine, |exec, pool| ..)(#[doc(hidden)] pub、所有者はtenferro-cpu)- linalg の分岐(下の 4.)から呼ぶための橋です。所有者を明記した bridge として、例外表の E06 に、シンボル単位で載せます。
- 中に
unsafeのキャストが 1 つあります。既存のwith_cpu_engineと同じ形です。PR では、このキャストの安全性の説明をレビューに出し、Miri でテストを実行してください。P7 では Miri を実行していません。
linalg の分岐
tensor_ext.rsのwith_linalg_backend(CPU と CUDA の分岐がある関数)に、借用エンジンのマーカーを見分ける分岐を足します。分岐の先では、今のSealed::*_with_execの型付き本体を呼びます。- P7 ではこの振り分けをアダプタの側でやっていました。本実装では linalg の側に置きます。
- これで、レーンの中でも普通の文法(
view.svd_with(&opts, lane))が、今の*_with_execと同じ本体に届きます。
消すもの
- 公開関数
*_with_execの6本、lib.rsの「Borrowed-Execfactorization entries」節、with_exec.rsの公開 re-export。 - 型付き本体(
Sealedトレイトの中にある*_with_exec)は、crate 内の実装として残します。 docs/guides/cpu-execution.mdの「Lanes and the vendor provider」節は、手でトークンを fork して束を作る説明から、with_lanesの説明に書き換えます。BLAS プロバイダについての注意(BLAS はレーンの予算を守れない)はそのまま残します。
決めておくこと(P7 で見つかった点)
- F1 負ストライド: §5.3 の決定どおり、すべての入口で負ストライドを受け付けて gather します。レーンの中でも同じです。gather のバッファはレーンのプールから借ります。割り当て 0 の保証は、負ストライドでない入力についてだけ約束します。レジストリの
layoutにも、そう書きます。gather がレーンのプールから出ることを、テストで確かめてください。 - F2 gauge: 今の借用経路には gauge がありません。レーンでも Engine と同じ
SvdOptionsを受け付けるよう、linalg の分岐の中でapply_svd_gauge(pub(crate))を適用します。実装するまでは、既定以外の gauge はUnsupportedを返し、omissionsに書きます。 - F4 レーンで使える演算: レーンの中で使えるのは linalg の6演算(svd、svdvals、qr、eigh、eigvalsh、eigvals)だけです。それ以外の演算(einsum、core など)は
Unsupportedを返します。各演算のレジストリのomissionsに「レーン(with_lanes)では未対応」と書き、docs/guides/cpu-execution.mdにも書きます。
この作業に含めないもの
[本書で決定] レーンを完全な Engine にすること(P7 の設計 B)は、0.12 の範囲外とします。これは、CpuEngine の内部を「Exec と BufferPool をどこから得るか」について汎用にする変更で、次の規模になります。
resourcesとparts()の利用箇所、約 37 か所Engineの実装 12 個- 借用した束を運ぶ型へのライフタイムの追加
これが入れば、レーンで einsum や core も使えるようになり、BorrowedCpuEngine は不要になります。0.12 が出たら、別の Issue として起こしてください。with_lanes のシグネチャは、設計 B に移っても変わりません。
完了条件
5.7 EagerTensor::solve
EagerTensorLinalgExt::solve(&self, engine, b)(eager_ext.rs:75)は削除し、sess.solve(&x, &b)に一本化します(決定 3)。- 現行の
solveが保っている「呼び出しスレッドのno_gradを尊重する」振る舞いは、EagerSessionの経路で同じになることをテストで確かめてから削除します。同じにならない場合は、削除せずに #2552 で報告してください。
6. S4:einsum
6.1 前提
#2565(N 入力の einsum が共役の指定を黙って捨てる)の修正が先に main に入っている必要があります。最低限、未対応の共役指定を Unsupported として拒否するようになっていることが条件です。
6.2 Spec と Options
/// Text, parsed notation or subscripts; parsing and validation happen
/// inside the operation, so construction never fails.
pub enum Spec<'a> { Text(&'a str), Notation(&'a EinsumNotation), Subscripts(&'a EinsumSubscripts) }
impl<'a> From<&'a str> for Spec<'a> { .. }
impl<'a> From<&'a EinsumNotation> for Spec<'a> { .. }
impl<'a> From<&'a EinsumSubscripts> for Spec<'a> { .. }
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct EinsumOptions {
pub optimize: EinsumOptimize,
pub conj: ConjMask, // オペランドごとの Conj。既定はすべて No
}Fromは表現を包むだけで、検証はしません。文字列の解析エラーは、演算の中でInvalidSubscriptsとして返します(v0.1 の合意)。EinsumOptimizeとContractionTreeにCloneを derive します。現在はEinsumOptimizeがDebugだけで、ContractionTreeは derive がありません(optimize.rs:54、planning/tree.rs:110)。&optsでツリーを渡すために必要です(P6)。ConjMaskは、2 入力の場合、DotGeneralAccumulationのlhs_conjとrhs_conjに写します。3 入力以上で共役が指定され、その経路が未対応の場合はUnsupportedを返します(#2565 の方針に合わせる)。EinsumOptimizeのうちAuto以外を concrete のプランが守れない問題(P2)について:ConcreteEinsumPlanは常にContractionTree::optimizeを実行しています。[本書で決定]Tree、Path、Nestedを指定された場合は、その木を使うように直します。直せない組み合わせはUnsupportedを返します。黙って無視してはいけません。
6.3 concrete
| 旧 | 新 |
|---|---|
TensorEinsumExt、TypedTensorEinsumExt、TensorReadEinsumExt、TypedTensorReadEinsumExt、*EinsumIntoExt(計 8 トレイト、それぞれ bare / _notation / _subscripts) |
EinsumOps。[&a, &b].einsum(spec, exec)、.einsum_with(spec, &opts, exec)、.einsum_into(spec, &opts, exec, dest) |
TensorTensordotExt、TypedTensorTensordotExt |
TensordotOps。a.tensordot(&b, axes, exec)(設定項目がないので _with は置かない) |
ConcreteEinsumPlan::prepare{,_subscripts,_notation,_typed*,_read*}(9 本) |
ConcreteEinsumPlan::prepare(inputs, spec, &opts)(1 本) |
execute、execute_typed、execute_read、execute_into、execute_typed_into、execute_read_into、execute_read_into_accum(7 本) |
plan.execute(inputs, exec)、plan.execute_into(inputs, exec, dest) |
EinsumOpsの受け手は、[X]と[X; N]です(X: AsView)。所有テンソルと借用ビューを混ぜて渡したい場合は、呼び出し側で[a.as_read(), b]のように借用ビューのスライスにそろえます。データのコピーは起きません(v0.1)。prepareは入力のメタデータ(dtype と形状)だけを読みます。inputsには、AsViewを実装する型のスライスを受け付けます。executeの出力は、入力のReprで決まります。typed の入力なら typed で返します。clear_cpu_cacheとcpu_cache_statsは E03 なので、そのまま残します。- プランのキャッシュキーにはレイアウトが入りません(P4)。レイアウトが変わると、キャッシュが一度ミスして入れ替わります。結果は正しく、ポリシーは撤回済みなので、この挙動のままでかまいません。
6.4 traced と eager
- traced:
trace.einsum(&[&t1, &t2], spec)とtrace.einsum_with(&[..], spec, &opts)を、TracedEinsumOps for TraceContextとして提供します。受け手は&selfで、戻り値はTracedTensorです(決定 4、案 C)。- 現行の
TraceContextEinsumExtは&mut selfを取り、TraceValueを返す6メソッドです。名前が衝突するので、この trait は削除して置き換えます(E07 を退役)。 - P6 の計測では、TracedTensor 経路の構築時間は TraceValue 経路と誤差の範囲で、割り当て回数は 12〜20% 多いという結果でした。この差は受け入れます。
- 現行の
TracedTensorからTraceValueを得る公開の変換はありません。derive_tensorは doc(hidden) です。新しい入口はTracedTensorを受けるので、この変換は不要です。TracedTensorEinsumExt::tensordotは、TracedEinsumOps for TracedTensorのt.tensordot(&u, axes)に移します。- eager:
EagerSessionEinsumExtをEagerEinsumOps for EagerSessionにし、sess.einsum(&[&x, &y], spec)、sess.einsum_with(..)、sess.tensordot(&x, &y, axes)を提供します。 TraceContext::input、finish、add_op、add_extensionとTraceValueは、E04 の IR ビルダー層としてそのまま残します。finishとcompile_manyの不一致:finishからcompile_traced_graphを経るとinput_keysが空になり、compile_manyでは埋まります(P6)。[本書で決定]finishの経路でもinput_keysを埋め、両者が同じ入力順と枝刈りになることをテストで固定します。- 下流への影響: yao-rs は
=0.4.0を固定しているので、すぐには壊れません。ただし移行先(Runtime::prepare→Runtime::run)を、docs/getting-started/api-migration.mdに書きます。
6.5 エラー
einsum は、現在どの層でも tenferro_einsum::Error を返しています。ルール 5 に合わせて、次のように変えます。 - concrete は tenferro_tensor::Error を返します。Error::Extension { family: EINSUM_EXTENSION_FAMILY_ID, kind, source: tenferro_einsum::Error } に包みます。 - traced と eager は tenferro_runtime::Error を返します。 - tenferro_einsum::Error と PlanningError は、領域のエラーとして残します(E09)。パーサー(parse_einsum_subscripts など)とプランナーは、引き続きこの型を返します。 - 同じ不正な spec に対する分類を、3 層でそろえます。P5 では、concrete と eager は InvalidSubscripts、traced は InvalidArgument でした。[本書で決定] 3 層とも kind() == Validation(InvalidArgument) にし、source() から tenferro_einsum::Error::InvalidSubscripts に届くようにします。
7. S5・S6:FFT と core
7.1 FFT
| 層 | 旧 | 新 |
|---|---|---|
| concrete | TensorFftExt(1 次元のみ)、TensorReadFftExt |
FftOps for X: AsView:fft、ifft、rfft、irfft、fftn、ifftn、rfftn、irfftn と、それぞれの _with |
| traced | TracedTensorFftExt、TraceContextFftExt |
TracedFftOps for TracedTensor。TraceContextFftExt は削除(決定 4) |
| eager | EagerSessionFftExt(1 次元のみ)、EagerTensorFftExt |
EagerFftOps for EagerSession:8 演算と _with。さらに fft_in_place(x, &opts) と ifft_in_place(x, &opts)(E01) |
| キャッシュ所有者 | FftExecutor::fft(&mut self, input, n, axis, norm, session) |
FftExecutor::fft_with(&mut self, &input, &opts, exec)。new、plan_cache、plan_cache_mut、cache_stats、clear_cache は残す(E02) |
- Options は次のとおりです。
FftOptions { n: Option<usize>, axis: isize, norm: FftNorm }(fft、ifft、rfft、irfftで共通)FftnOptions { shape: Option<Vec<usize>>, axes: Vec<isize>, norm: FftNorm }- 既定値は現行の既定値と同じにします。
axisは-1です。
- 現在、concrete と eager にない N 次元の FFT(
fftnなど)を足します。実装はFftExecutorの N 次元経路を呼べば済みます。 - in-place の FFT: 長さを変えられない演算なので、
FftOptionsのnを指定したらError::Validation(InvalidArgument)を返します。[本書で決定] in-place 専用の別の Options 型は作りません。 ifft_in_placeの検証エラーのラベル: 現在は"fft_in_place"になっているので、"ifft_in_place"に直します(P3)。EagerFftInPlaceError:?を使うと、取り戻せるはずの所有者が捨てられます(P3)。[本書で決定] 型は変えません。rustdoc の例で「?の前にmatchして、Rejected { input, .. }から所有者を取り戻す」書き方を示し、そのことをテストします。
7.2 core(runtime と ad)
| 層 | 旧 | 新 |
|---|---|---|
| concrete | TensorSessionOpsExt、TypedTensorSessionOpsExt、TypedTensorMaskSessionOpsExt |
CoreOps for X: AsView(where_select は受け手が TypedTensor<bool> のときだけ使える)。concatenate は CoreOps::concatenate(&[..], axis, exec) の関連関数 |
| traced | TracedTensor の固有メソッド |
固有メソッドのまま。名前と引数を文法に合わせる。_with は Options を持つ演算にだけ生成する |
| eager | EagerSession の固有メソッド |
固有メソッドのまま。同上 |
- concrete の
execは最後の引数です。現在のコードはすでにそうなっています。REPOSITORY_RULES.md の「engine は第1引数」という記述のほうが間違っているので、§8 で直します。 dot_general_with_conjは削除し、dot_general_with(&rhs, config, &DotGeneralOptions { lhs: Conj, rhs: Conj }, exec)にします。add_into(typed のみ)は、add_into(&rhs, exec, Dest::overwrite(&mut out))にします(addは設定項目がないので Options を持ちません)。それ以外の_intoは、今回は増やしません(決定 5:レジストリで演算ごとに宣言する)。- 軸の引数は
isizeにします(§3.2)。 - 型変換(
convert、cast)は明示的な演算のまま残します。データの移動が必要なreshapeを、メタデータだけの操作として扱ってはいけません。 - 層ごとの演算の集合の差(たとえば
EagerSessionにsoftmaxなどがない)は、この作業では埋めません。レジストリのlayersとomissionsに、現状をそのまま書きます。
8. S7:規約・仕様・ドキュメント・スキル
文法の変更と同じ作業ブランチ(同じ PR)で、次をすべて書き換えます。どれかが古いままだと、repository-rules-review.py と規約に沿ったレビューが、新しい文法を違反と判定します。
| ファイル | 書き換える内容 |
|---|---|
REPOSITORY_RULES.md「Public API Convention」(903〜964 行) |
次の4つを書き換える:(1) 文法の3形と層ごとの形、(2) 接尾辞は _with と _into だけで、累積は Dest、(3) トレイトの一覧を新しい 12 個に、(4) 例外は例外表を参照する。「Output And Write Surface Vocabulary」(_read、_read_into、_add_to、_into_accum)は、_in_place(E01)を残して削除し、生成された docs/spec/generated/api-ops.md を参照させる |
REPOSITORY_RULES.md「Public Surface Discipline」 |
_read と _view の命名について書いた箇条を、新しい文法に合わせる |
REPOSITORY_RULES.md「Wrapper DRY And Codegen」 |
レジストリによる生成を許す条件として、§4.2 の「生成するもの・しないもの」を書く |
PERFORMANCE_TIPS.md「Materialization And Copies」 |
新しい R3 と照らし合わせる。「*_read フック」は、公開名ではなくバックエンドのフックを指す言葉として残る。食い違いがあれば直す |
scripts/repository-rules-review.py |
## 節を足したり名前を変えたりした場合は、SECTION_TRIGGERS、ALWAYS_SECTIONS、HUMAN_ONLY_SECTIONS を更新する(AGENTS.md の指示) |
docs/spec/api-conventions.md |
命名規則 3(_read)と形状規則 4(einsum の 8 トレイト)を削除し、生成文書を参照させる。存在しない「Naming rule 10」への参照(122 行目)を直す |
scripts/check-api-consistency.py |
CI で実行されていない。_read の検査(read_suffix_without_read_input)は新しい文法では意味がないので削除する。残す検査(try_ 接頭辞、traced_ 接頭辞など)は、新しい文法と矛盾しないか確かめる。[本書で決定] スクリプトとテストは残し、CI への組み込みは公開 API スナップショット(S0)に任せる |
docs/design/api-consolidation-policy.md |
R2(_into を公開の基本形とする)を、「_into はレジストリで演算ごとに宣言する」に改める |
| tensor4all-agent-rules | 「no hidden … dense-layout conversions」の規則を、新しい R3 と合わせる。別のリポジトリなので、そちらに PR を出し、この PR の説明からリンクする |
.agents/skills/tenferro-compute/ と .claude/skills/tenferro-compute/ |
SKILL.md、references/api-cheatsheet.md、references/performance-idioms.md。2 つは別々の実ディレクトリなので、両方を同じ内容で直す。直したら scripts/check-agent-skills.py を実行する |
docs/guides/*.md、docs/getting-started/*.md、docs/tutorials/*.md、docs/tutorial-code/src/bin/*.rs、README.md |
旧トレイト名と旧メソッド名をすべて置き換える。docs/tutorial-code はコンパイルされるので、cargo build が通ることを確かめる |
docs/getting-started/api-migration.md |
旧名 → 新名の対応表を載せる(§11 の表を元にする) |
docs/internals/public-boundary-overhead-inventory.{json,md}、docs/spec/operation-categories.md |
check-public-boundary-inventory.py と check-operation-categories.py が読むので、名前と面を新しいものにする |
旧名が残っていないことは、次のコマンドが何も出力しないことで確かめます。
rg -n 'TensorLinalgExt|TensorReadLinalgExt|TypedTensorLinalgExt|TraceContextLinalgExt|TraceContextFftExt|TraceContextEinsumExt|TensorEinsumIntoExt|TensorReadEinsum|TypedTensorReadEinsum|TensorFftExt|TensorReadFftExt|EagerTensorLinalgExt|EagerTensorFftExt|TensorSessionOpsExt|_into_accum\b|_with_exec\b|svd_full|_with_rtol|prepare_typed|execute_read' \
--glob '!docs/plans/**' --glob '!docs/design/api-2552-convergence/**' --glob '!docs/worklogs/**' --glob '!api/**'docs/plans/ と docs/worklogs/ は履歴なので、書き換えません(AGENTS.md)。
9. 文法の移行とは別に進める修正
それぞれ main から切った別ブランチで、通常の PR にします。
| 修正 | 内容 | 完了条件 |
|---|---|---|
| #2565 | N 入力の einsum で共役の指定を捨てない。最低限、未対応なら拒否する | 2 入力と 3 入力、および ii,ij->j で、共役を指定したテストが、正しい値を返すか Unsupported になる |
| eager einsum の毎回のコピー | フォールバックが、コンパクトな入力も含めてすべてのオペランドを to_contiguous_read でコピーしている(P4) |
コンパクトな入力でコピーが起きないことを、to_contiguous_read のスパイ(またはカウンタ)で確かめるテスト。わざと元の実装に戻すと失敗する対照テストも置く(PERFORMANCE_TIPS.md の要求) |
| rank 3 の strided SVD バッチ | svd_with_exec のカーネルはそのまま読めるのに、ディスパッチの段階で gather している(P4) |
rank 3 の非コンパクトなバッチで gather が起きず、結果が変わらないことのテスト |
| CUDA linalg の転置 gather | 転置したビューを gather している | GPU でしか確かめられないので、local_gpu_gate.py で検証する(REPOSITORY_RULES.md の CI Cost Discipline) |
公開のカウンタは作りません。計測は、テストの中のスパイと、ベンチマークで行います。割り当て回数とコピー回数を同じものとして扱ってはいけません(決定更新 6764423689)。
10. 完了の定義と検証
10.1 演算ごとの完了条件
1 つの演算は、次をすべて満たしたときに完了です。
10.2 PR を出す前
AGENTS.md の「Pre-Push / PR Checklist」に従います。最低限、次を実行します。
bash scripts/check-pr-fast.sh --coverage-reviewed --test 'cargo test --workspace'
python3 scripts/repository-rules-review.py --base origin/main --head HEAD \
--output-json /tmp/repository-rules-review.json \
--dry-run --llm-skipped-reason "local deterministic review"
bash scripts/api-snapshot.sh --check
python3 scripts/check-agent-skills.py
cargo doc --workspace --no-depsapi/のスナップショットは--writeで更新してコミットします。PR の説明では、その差分を「消えたもの」と「増えたもの」に分けて要約します。この差分が、そのまま退役リストになります。- PR 本文には
## Verification節が必要です(bodyチェック)。実行したコマンドとその出力を貼ります。 - GPU を触る変更を含む場合は、
gpu-validated-locallyラベルを付け、local_gpu_gate.pyで検証します。
10.3 受け入れ条件(#2552 の決定更新から)
- 同じ演算なら、どの入力の形(adapter)を使っても、レイアウトの扱いが同じであること。
- provider が直接読める strided の経路が残っていること。
- レイアウトの制約と変換が、演算ごとに文書化されていること(レジストリの
layoutから生成)。 - 既知の避けられるコピーに、回帰テストか性能テストがあること(§9)。
- 数値、所有権、エイリアス、出力先の更新についての保証が変わっていないこと。
11. 旧名 → 新名の対応(抜粋)
| 旧 | 新 |
|---|---|
a.svd(eng) → (u, s, vh) |
let Svd { u, s, vh } = a.svd(eng)? |
a.svd_full(eng) |
a.svd_with(&SvdOptions::default().shape(SvdShape::Full), eng) |
r.svd_read(eng)(r: TensorRead) |
r.svd(eng) |
a.svd_with_options(opts, eng) |
a.svd_with(&opts, eng) |
a.pinv_with_rtol(rtol, eng) |
a.pinv_with(&PinvOptions::default().rtol(Some(rtol)), eng) |
a.triangular_solve(&b, true, true, false, false, eng) |
a.triangular_solve_with(&b, &TriangularSolveOptions::default(), eng) |
r.solve_read_into(b, out, eng) |
r.solve_into(&b, eng, Dest::overwrite(out)) |
a.norm(None, Some(&[0]), false, eng) |
a.norm_with(&NormOptions::default().axes(Some([0].into())), eng) |
x.solve(engine, &b)(EagerTensor) |
sess.solve(&x, &b) |
ctx.svd(a_value)(TraceContextLinalgExt) |
t.svd()(TracedTensor) |
[&a, &b].einsum_notation(&n, eng) |
[&a, &b].einsum(&n, eng) |
[r1, r2].einsum_read_into("ij,jk->ik", eng, out) |
[r1, r2].einsum_into("ij,jk->ik", &EinsumOptions::default(), eng, Dest::overwrite(out)) |
plan.execute_read_into_accum(inputs, eng, acc, out) |
plan.execute_into(inputs, eng, Dest::scaled(out, alpha, beta))。共役はプランを作るときの EinsumOptions::conj で指定する |
ConcreteEinsumPlan::prepare_typed_notation(inputs, &n) |
ConcreteEinsumPlan::prepare(inputs, &n, &EinsumOptions::default()) |
ctx.einsum_subscripts_with(&[v1, v2], s, opt)(&mut、TraceValue) |
ctx.einsum_with(&[&t1, &t2], s, &EinsumOptions { optimize: opt, ..Default::default() }) |
a.fft(None, -1, FftNorm::Backward, eng) |
a.fft(eng)、または a.fft_with(&FftOptions::default().norm(..), eng) |
x.fft_in_place(engine, axis, norm) |
sess.fft_in_place(x, &FftOptions::default().axis(axis).norm(norm)) |
exec.fft(&input, n, axis, norm, eng)(FftExecutor) |
exec.fft_with(&input, &opts, eng) |
engine.with_exec(\|exec\| svd_with_exec(exec, &mut pool, &view, false)) |
engine.with_lanes(&[n], &mut [pool], \|_, lane\| view.svd(lane)) |
レーンを手で作る(exec.token().fork_sized(..) と Exec::from_token と *_with_exec) |
engine.with_lanes(&shares, &mut pools, \|i, lane\| ..) |
a.dot_general_with_conj(&b, cfg, true, false, eng) |
a.dot_general_with(&b, cfg, &DotGeneralOptions::default().lhs(Conj::Yes), eng) |
a.reduce_sum(Some(&[0usize]), eng) |
a.reduce_sum(Some(&[0isize]), eng)(-1 も使える) |
12. 迷ったとき
- この文書と #2552 の決定が食い違う場合は、#2552 を優先し、この文書を直す PR を出してください。
- この文書に書いていない判断が必要になった場合は、次の2つのどちらかにします。
- 推測で実装せずに #2552 で質問する。
- レジストリの
omissionsか例外表に「未決」として記録し、Unsupportedを返す形で先に進む。
- 数値の結果を変えてしまう変更は、どんな理由があっても、この移行の中で行ってはいけません。必要なら別の Issue を立ててください。