tensor4all/tenferro-rs · issue #2552 への提案 · 2026-11-10 · v0.2 とプロトタイプの結果まで反映(実体化ポリシーは撤回、公開カウンタは要件外)

tenferro API の文法

演算ごと・層ごとに名前を増やす今のやり方をやめて、全クレート共通の「呼び出しの文法」を1つ決めます。ルールは7つで、どれも文章ではなく生成・型・スナップショットのどれかで守ります。

14→4
SVD 系の公開名
(svd svd_with svdvals svdvals_with)
31→12
公開拡張トレイト
(4 ファミリー × 3 層)
~20→3
einsum の入口名
(einsum einsum_with einsum_into)

数値は origin/main 62b9f7b8 の静的カウント(pub trait *Ext と演算名の grep)。内部クレートとテストは除外。

いま何が起きているか

名前が掛け算で増えている

1つの演算の名前に、入力の種類・パラメータの違い・出力の受け取り方・層がすべて織り込まれています。新しい軸が1つ増えるたびに、全演算の名前が倍に増えます。

入力の種類×パラメータの違い×出力モード×層
(なし)
_read
typed
typed + _read
× (なし)
_full
_with_options
_with_rtol / _with_driver
× (なし)
_into
_into_accum
× Tensor 拡張
_with_exec 自由関数
TracedTensor / TraceContext
EagerTensor / EagerSession

しかも現行の api-conventions.md は、命名規則 3 で _read 接尾辞を要求し、形状規則 4 で einsum の 8 トレイトを列挙しています。規約そのものが掛け算を固定してしまっています。さらに、同じビューでも入口によってレイアウトの扱いが違います(コピーする / 拒否する / そのまま読む)。#2552 の監査で見つかった食い違いの根はここにあります。

ルールを文章で足しても、すでに古くなり始めています。
  • REPOSITORY_RULES.md:921 は「engine は第1引数」と書いているが、コードでは最後の引数になっている(runtime の 89 メソッドすべて)。
  • チェッカーの対応表は存在しない「命名規則 10」を参照しており、try_ の許可リストは存在しないファイルを指している。
  • check-api-consistency.py は main で 18 件の指摘を出して落ちている。また、行頭が pub の行しか見ないため、*Ext トレイトのメソッドは一度も検査されていない。
  • チェッカーは scripts/check-*.py だけで 32 本、約 6,400 行ある。

この提案では、ルールの数を減らしたうえで、各ルールを文章ではない仕組みに担わせます。

核心

呼び出しの文法は1つだけ

tenferro のあらゆる演算呼び出しは次の形に収まります。色付きの枠がスロットで、名前に入ってよいのは op と2種類の接尾辞だけです。

x受け手=入力 . svd演算名 [_with|_into]許される接尾辞 ( operands…必須の追加入力 , &opts意味オプション , exec実行器 , out_into のみ・Dest )

concrete(即時計算)

exec = &mut dyn Engine。Tensor・TensorRead・TypedTensor<T>・ビューのどれでも同じメソッドが呼べる

a.svd(&mut eng)?
a.svd_with(&opts, &mut eng)?
a.solve_into(&b, &opts, &mut eng, Dest::overwrite(&mut x))?

eager(自動微分つき即時)

実行器 EagerSession が受け手の位置に来て、入力 x は第1引数に移る。それ以外の名前・引数順・結果型は concrete と同じ(決定 3)

sess.svd(&x)?
sess.svd_with(&x, &opts)?

traced(グラフ構築)

演算の呼び出しに exec は出てこない。実行は prepare → run で、呼び出し側が持つエンジンに渡す

t.svd()?
t.svd_with(&opts)?
trace.einsum_with(&[a, b], spec, &opts)?
runtime.run(&prepared, inputs)?

入力の個数が決まっていない演算(einsum)は、所有者を受け手にします。eager では sess.einsum(&[x, y], spec)、traced では trace.einsum(&[a, b], spec) です。concrete にはそのような所有者がないので、入力のスライス [&a, &b].einsum(spec, eng) を受け手にします(決定 4)。

短い形 op(..., exec) は「オプションをすべて既定値にする」糖衣構文です。何か1つでも指定したいときは op_with を使います。

ルール

7つのルール

各ルールには、それを守る仕組みを1つ以上付けています。生成 は演算レジストリからマクロで作るので手書きの余地がないもの、型 はコンパイラが拒否するもの、凍結 は公開 API のスナップショットとの差分で CI が落ちるものです。

1

名前は「何を計算するか」だけを表す

層・入力の型・パラメータ・実行器の違いは名前に入れない。許される接尾辞は _with(オプションを指定する)と _into(出力先を渡す)の2つだけ。同じ演算はどの層・どのクレートでも同じ名前。

いま
a.svd_full_read(s)
svd_values_with_exec(e, b, v)
t.svdvals()   // 層で名前が違う
ルール後
a.svd_with(&full, s)
v.svdvals(e)
t.svdvals()   // どの層でも同じ
生成凍結
消えるもの:_read _full _with_options _with_rtol _with_driver _with_exec _values _notation _subscripts _typed _into_accum
2

入力は借用ビューの1種類だけ

実装は借用ビュー上に1つだけ書く。所有テンソル・型付きテンソル・TensorRead は、メタデータの付け替えだけでそのビューになる(コピーは起きない)。入口が1つになるので、同じ入力ならレイアウトの扱いも必ず同じになる。typed で渡せば typed で返る。表現は typed と erased の2つで、typed を erased にしてから型を戻すようなことはしない。出力の型は演算ごとに決まる(複素 SVD の s は実数)ので、関連型1つでは表せない(v0.1 の指摘)。

いま
TensorLinalgExt       (owned)
TensorReadLinalgExt   (borrowed)
TypedTensorLinalgExt  (typed)
+ svd_with_exec 自由関数
→ 負ストライドで 3 通りの挙動
ルール後
// どの入力型もメタデータ変換で
// 同じ実装に入る(AsView、要試作)
let r = a.svd(e)?;  // a: Tensor / TensorRead
let r = v.svd(e)?;  // v: TypedTensorView<C64>
// r: Svd<TypedTensor<C64>, TypedTensor<f64>>
型生成
消えるもの:TensorRead*Ext TypedTensorRead*Ext *IntoExt 系トレイト、with_exec.rs の自由関数と Sealed
3

違いは名前ではなく、型付きの引数で表す

意味に関わる指定は、すべての演算に1つずつある XxxOptions(#[non_exhaustive]、Default、with_* セッター)に入れる。制御フラグとしての bool は公開シグネチャに置かない(取り違えてもコンパイルが通り、数値が黙って変わるため)。真偽値のデータや述語は対象外。軸はすべて isize(NumPy 流の負数インデックス)。長さ・次元・IR の識別子は対象外。文字列か解析済み記法か、のような入力表現の違いは1つの spec 引数で受ける。文字列の解析は失敗しうるので、検証は演算の中で行ってエラーを返す(From<&str> で検証済みのように見せない)。

いま
a.triangular_solve(b, true, false,
                   true, false, s)
plan::prepare_typed_notation(..)
norm(dim: Option<&[usize]>)  // fft は isize
ルール後
a.triangular_solve_with(&b,
  &TriSolveOptions::default()
     .side(Side::Left).uplo(Uplo::Lower), s)
EinsumPlan::prepare(inputs, spec /* &str でも可 */)
型生成
消えるもの:公開引数の bool、prepare_* 9 種、execute_* 7 種(prepare と execute / execute_with / execute_into に整理する)
4

実行器は呼び出しごとの引数。コピーを禁止する引数は置かない

実行器(Engine / EagerSession)は引数で渡し、Engine に呼び出しをまたぐ状態を持たせない。実体化ポリシー(Allow / Forbid)は文法に入れない(2026-11-10 に裁定を見直し)。プロトタイプでは、native CPU で Forbid が拒否するのは SVD read の負ストライドと rank 3 以上の非コンパクトなバッチだけで、einsum では何も拒否しなかった。拒否されても呼び出し側にできるのは明示的なコピー(同じコスト)か上流のレイアウト変更だけで、ポリシーは制御ではなく診断になる。また、ポリシーが何を禁じるのかを、利用者に安定して約束できる形で定義できなかった。同じデータ移動でも、選ばれたカーネルによって正規化とも workspace とも分類されてしまう。そこで、同じデバイス・同じ dtype でのレイアウト変換は実行の中で行ってよいとし、op ごとに文書化する。ポリシーを engine の状態・options・リクエストのラッパーへ移すこともしない。公開カウンタも今回の要件にしない(必須でも禁止でもなく、具体的な利用者と数え方の約束ができてから別に設計する)。避けられるコピーは、内部・テスト用の計測とベンチマークで、入力全体の一時コピー、パッキング、workspace の確保と再利用を区別して確かめる。デバイス転送と dtype 変換は今までどおり明示的に行う。

いま
a.svd(session)            // 最後
x.solve(engine, b)        // 2番目
svd_with_exec(exec, ..)   // 最初
einsum_into(s, sess, out) vs
solve_read_into(b, out, sess)
ルール後
// どの演算も …, &opts, exec, dest
a.svd_with(&o, e)
sess.solve_with(&x, &b, &o)
a.einsum_into(spec, &o, e,
              Dest::accumulate(&mut c))
// 既知の避けられるコピーは
// 回帰・性能テストで押さえる(公開 API は増やさない)
生成型
消えるもの:エンジン位置の3流派、公開シグネチャに出ている tcontract_exec::Exec / BufferPool(Exec を包む Engine 型のコンストラクタ1か所に寄せる。置き換えられることを試作で示してから削除する。例外 E08)
5

結果は名前付き構造体。エラーは外側を層ごとに1型にし、原因は残す

出力が複数ある演算は名前付き構造体で返す。値の型と実数の型は分ける。たとえば Svd<V, R = V> { u: V, s: R, vh: V } で、複素 SVD の s は実数、実数行列の eig の結果は複素になる。外側のエラー型は層ごとに1つ(concrete は tenferro_tensor::Error、traced は tenferro_runtime::Error、eager は tenferro_ad::Error)で、すべて #[non_exhaustive]。ファミリー固有のエラー(linalg の特異・非収束など)は残し、外側のエラーの source() から downcast_ref で取り出せるようにする。構造化された原因を文字列に変えることはしない。共通の検査用トレイト(TensorError など)は、それを必要とする利用者が示されるまで追加しない(v0.2)。分類 kind と原因が食い違わないことは、当面はテストと監査で確かめる。Error::Extension は各フィールドを公開した variant なので、コンストラクタを足すだけでは食い違いを防げない。

いま
(Tensor, Tensor, Tensor)   // 順序は型に出ない
TypedSvd<T> = (..)         // タプル別名
LinalgBackend → Vec<Tensor>
einsum だけ einsum::Error
ルール後
let Svd { u, s, vh } = a.svd(e)?;
// 複素入力なら Svd<TypedTensor<C64>, TypedTensor<f64>>
Lu<V,R>, Qr<V>, Eigh<V,R>, Eig<C>, Slogdet<V,R>
err.source() → tenferro_linalg::Error
型生成
消えるもの:結果タプル別名、公開の Vec<Tensor> 返り値。ファミリー固有のエラーは退役しない(v0.1)
6

公開するのは宣言したものだけ

公開項目は Release・owner-scoped bridge・experimental のどれかで、どれにも当たらないものは非公開にする。#[doc(hidden)] pub は所有者を明記した bridge にだけ許す。意図せず他クレートの型を公開シグネチャに出さない。承認済みの数値型や bridge は、シンボル単位の許可リストに載せる(例外 E06)。公開 API は cargo public-api のスナップショットとしてリポジトリに置き、差分のある PR は必ずレビューに出す。

いま
#[doc(hidden)] pub  // gpu で 136 項目
CudaEngine::open が hidden なのに
CudaBackend は pub
map_error(tlinalg::Op, ..) が公開
ルール後
api/tenferro-linalg.txt  (スナップショット)
api/tenferro-gpu.txt
CI: 差分あり かつ 未更新 → fail
凍結
消えるもの:正規表現で公開面を推測するチェッカーの大半
7

仕組みで守れないルールはルールにしない

ルールは「生成・型・凍結」のどれかで守る。守り方が決まらないものは提案止まりにする。規約文書は人が書かず、演算レジストリとスナップショットから生成する(演算 × 層の表、接尾辞の一覧、例外表)。例外はレジストリ内に理由付きで書く。生成できない規約ファイル(REPOSITORY_RULES.md、PERFORMANCE_TIPS.md、tensor4all-agent-rules)は、文法を変える PR と同じ PR で書き換え、repository-rules-review.py が新旧どちらの文法も認める期間を作らない。

生成型凍結
消えるもの:手で保守している規約の本文(api-conventions.md 命名規則 3、形状規則 4、consolidation policy R2/R3)。REPOSITORY_RULES.md「Public API Convention」の接尾辞体系と旧トレイト一覧は書き換える
文章が古くならない理由

ルールを担う3つの仕組み

規約文書が古くなるのは、コードと文書が別々に書かれているからです。そこで、公開面のほうを1か所の宣言から生成し、残った部分は型とスナップショットで固定します。

生成演算レジストリ

演算ごとに1行の宣言を書き、マクロが 3 層ぶんのトレイトメソッド・_with/_into・ドキュメント表を生成します。ルール 1・3・4・5 は「手で書かない」ことで守られます。core には既に primitive_ops!(catalog.rs:81)という種があります。

tenferro_ops! {
  op svd(a) -> Svd {
    options: SvdOptions,
    layers: [concrete, eager, traced],
  }
  op solve(a, b) -> Tensor {
    options: SolveOptions,
    into: true,
  }
}

型コンパイラ

#[non_exhaustive] の Options、bool の代わりの列挙型、Svd<V, R>、AsView アダプタ、Dest。違反するとコンパイルが通りません。

// 取り違えはコンパイルエラー
Uplo::Lower, Side::Left
// 構造体リテラルで固定できない
SvdOptions::default()
    .full_matrices(true)

凍結公開 API スナップショット

cargo public-api の出力をクレートごとにコミットします。CI では既に check-no-public-rayon.sh がこのツールを使っています。公開面が変わる PR は差分として必ず目に入ります。ただし、スナップショットはレビューの証拠であって、意味が一貫していることの証明ではありません。adapter 間でレイアウトの扱いが一致すること、provider が直接読める strided 経路が残っていること、エイリアス、所有権、出力先の更新、数値結果といった振る舞いは、別途テストで確かめます(v0.2 D、2026-11-10 の決定更新)。

$ cargo public-api -p tenferro-linalg \
    > api/tenferro-linalg.txt
CI: git diff --exit-code api/
全体像

トレイトは 31 から 12 へ

受け手の種類ごとに作っていたトレイトを、層ごとに1つへまとめます。赤が退役するもの、緑が残る形です。

受け手(いま)corelinalgeinsumfft→ ルール後
TensorTensorSessionOpsExtTensorLinalgExtTensorEinsumExt
TensorEinsumIntoExt
TensorTensordotExt
TensorFftExtconcrete 層
CoreOps / LinalgOps /
EinsumOps / FftOps
TensorRead–TensorReadLinalgExtTensorReadEinsumExt
TensorReadEinsumIntoExt
TensorReadFftExt
TypedTensor<T>TypedTensorSessionOpsExt
TypedTensorMaskSessionOpsExt
TypedTensorLinalgExtTypedTensorEinsumExt
TypedTensorEinsumIntoExt
TypedTensorTensordotExt
–
typed 借用 / 自由関数–svd_with_exec ほかTypedTensorReadEinsumExt
TypedTensorReadEinsumIntoExt
FftExecutor
(キャッシュ所有者として存続・E02)
TracedTensor / TraceContextinherentTracedTensorLinalgExt
TraceContextLinalgExt
TracedTensorEinsumExt
TraceContextEinsumExt
TracedTensorFftExt
TraceContextFftExt
traced 層(各ファミリー1つ)
+ TraceContext は einsum と IR ビルダ核のみ
EagerTensor / EagerSessioninherentEagerTensorLinalgExt
EagerSessionLinalgExt
EagerSessionEinsumExtEagerTensorFftExt
EagerSessionFftExt
eager 層(各ファミリー1つ)
退役の進め方

破壊的変更は 0.12 で1回だけ

早期開発中のリポジトリでは互換シムを置かない、という共有ルールに従い、旧 API は非推奨期間を設けずに削除します。順序は「先に仕組み、後で中身」です。

STEP 1

現行を基準として記録

全公開クレートの public-api スナップショットを、feature とツールチェーンを明示してコミットする。新設計の承認ではないので、プロトタイプを待たずに取れる。

STEP 2

6つの縦断プロトタイプ

複素 SVD、係数付き einsum、消費型 FFT、レイアウトを変えたときのプラン再利用、エラー原因の保持、TraceContext 縮約木。新しい目標 API はこれが通ってから固定する。

STEP 3

レジストリ生成と削除

レジストリから 3 層を生成して旧 API を置き換え、削除する。スナップショットの差分がそのまま退役リストになる。同じ PR で REPOSITORY_RULES.md の「Public API Convention」(engine を第1引数にする形、_read / _add_to / _into_accum の接尾辞体系、正規トレイトの一覧、solve と in-place FFT の例外)と「Wrapper DRY And Codegen」を新しい文法に書き換える。旧規約のままでは repository-rules-review.py と規約に沿った差分レビューが新しい文法を違反と判定し、旧規約に合わせれば文法が割れる。

STEP 4

隠れたコピーの削減と規約の同期

eager einsum の毎回コピー、rank 3 SVD のギャザー、CUDA の転置ギャザーを減らし、それぞれに回帰・性能テストを置く。公開カウンタは入れない。PERFORMANCE_TIPS.md の「Materialization And Copies」を新しい R3(op ごとに文書化したレイアウト変換)と照らし合わせ、食い違いがあれば同じ PR で直す。tensor4all-agent-rules と生成文書も同じ PR 群で更新する。

決定事項 · 2026-11-10

判断事項の結論

6つの判断事項はすべて決まりました。

1. 軸の型

決定:isize。NumPy と同じく負数で末尾から数える。runtime(usize 109 件)と linalg(33 件)の usize を移行する。

2. 空の Options

決定:全演算に置く。DetOptions のような空の構造体も作り、どの演算にも op と op_with がそろう。

3. eager の受け手

決定:sess.op(&x, ..) を維持。eager では実行器が受け手の位置に来る、と文法に明記する。EagerSession は別ランタイムのテンソルを拒否し、境界の外へ出られないので、受け手にしておく意味がある。EagerTensor 側の solve は退役する。in-place FFT 2つは入力を消費する演算として session 側に移す(session.fft_in_place(input, ..))。その接尾辞 _in_place は、理由を添えてレジストリの例外表に登録する(v0.1 とそのレビュー)。

4. TraceContext 拡張

決定:案 C(核だけ残す)。linalg と fft の拡張は退役する。einsum は trace.einsum_with(&[TracedTensor], spec, &opts) の1形にまとめる。input / finish / add_op / add_extension と TraceValue は IR ビルダ層として別枠で凍結する。finish と compile_many はどちらも snapshot_pruned を通るので、刈り込みのずれは見つかっていない(v0.2)。残る確認は、入力キーの対応づけとノードごとのコストで、プロトタイプ 6 で決める(例外 E07)。

検討の経緯:

39 メソッドあり、39 メソッドあり、linalg と fft の実装は derive_tensor してから TracedTensor 版を呼ぶだけ(例:traced.rs:1257)。einsum のような複数入力の受け方と合わせて検討する。

下流での利用:yao-rs(GiggleLiu/yao-rs、src/tenferro.rs:128-238)が使っている。TraceContext::new() → trace.input(..) で Copy な TraceValue ハンドルを作り、縮約木を再帰的にたどりながら trace.einsum_subscripts_with(&children, &subs, ..) を呼んで、最後に trace.finish している。つまり「ハンドルで組み立てるグラフ構築 API」として使われている。なお yao-rs は tenferro =0.4.0 に固定されている。また、実行に使っている execute_scoped_read_only は現行のソースに見つからないので、0.12 を待たずに書き換えが必要になる。

Fable 5.2 への相談結果(推奨案 C、未決定):TraceContext は核の部分だけ残す。

  • TraceContextLinalgExt と TraceContextFftExt の 33 メソッドは純粋な重複なので退役する。
  • einsum は事情が違う。traced の einsum は今 TraceContext 側にしかない(TracedTensorEinsumExt は tensordot だけ)。そこで trace.einsum_with(&[TracedTensor], spec, &opts) -> TracedTensor の1形にまとめ、_notation と _subscripts は impl Into<Spec> に吸収する。
  • input / finish / add_op / add_extension と TraceValue は、演算の文法の外にある IR ビルダ層として別枠で凍結する。

あわせて文法に1行足す必要がある:「入力の個数が決まっていない演算は、所有者(EagerSession / TraceContext)を受け手にする」。eager の sess.einsum(..) と対になる。

残る懸念:大きな縮約木でノードごとに TracedTensor を作るコストは未計測。また、finish と compile_many で入力の順序が一致するかも未確認。

5. _into の範囲

決定:演算ごとに宣言。レジストリに into: true と書いた演算だけ生成する。どこにあるかは生成される表でわかり、必要になった演算から足していく。

6. 累積出力

決定:出力先引数で表す。Dest::overwrite(&mut t) / Dest::accumulate(&mut t)。加えて、v0.1 の指摘を受けて alpha・beta 付きの更新を用意し、beta = 0 のときは出力を読まないことを保証する。共役は出力先ではなく、演算のオプションに置く。_into_accum、使われていない _add_to 語彙、DotGeneralAccumulation 引数は退役し、接尾辞は _with と _into の2つだけになる。

根拠:#2552 本文、独立監査コメント(2026-11-09)、裁定コメント(2026-11-10)、origin/main 62b9f7b8 の静的調査。コードのビルドやテストは実行していません。数値は grep による概数です。