Trait Module 

pub trait Module {
    // Required method
    fn forward<'t>(
        &self,
        tape: TapeRef<'t>,
        input: &Var<'t>,
    ) -> Result<Var<'t>, AutodiffError>;

    // Provided methods
    fn named_parameters(&self) -> Vec<(String, &Tensor<f32>)> { ... }
    fn set_parameter(
        &mut self,
        name: &str,
        _value: Tensor<f32>,
    ) -> Result<(), AutodiffError> { ... }
    fn state_dict(&self) -> HashMap<String, Tensor<f32>> { ... }
    fn load_state_dict(
        &mut self,
        state: HashMap<String, Tensor<f32>>,
    ) -> Result<(), AutodiffError> { ... }
    fn set_training(&mut self, _training: bool) { ... }
    fn training(&self) -> bool { ... }
    fn set_requires_grad(
        &mut self,
        _requires_grad: bool,
    ) -> Result<(), AutodiffError> { ... }
    fn freeze(&mut self) -> Result<(), AutodiffError> { ... }
    fn requires_grad(&self) -> bool { ... }
    fn children(&self) -> Vec<(String, &dyn Module)> { ... }
    fn named_modules(&self) -> Vec<(String, &dyn Module)> { ... }
    fn parameter_count(&self) -> usize { ... }
    fn type_name(&self) -> &'static str { ... }
    fn children_mut(&mut self) -> Vec<(String, &mut dyn Module)> { ... }
}

facade 利用者が独自層を定義するための共通 forward シグネチャ。

required は Self::forward の 1 件、defaulted は 14 件 （Self::named_parameters・Self::set_parameter・Self::state_dict・ Self::load_state_dict・Self::set_training・Self::training・ Self::set_requires_grad・Self::freeze・Self::requires_grad・ Self::children・Self::children_mut・Self::named_modules・ Self::parameter_count・Self::type_name。children・named_modules・ parameter_count・type_name の 4 件は autodiff Module（#2134）の同名メソッドの 鏡写し〈イシュー #2401〉、children_mut は set_requires_grad の葉単位ロールバック用に children と対で実装する facade 独自のメソッド〈#2400〉）。 出典は crates/autodiff/src/nn/module.rs で、tests/api_surface.rs が この集合を機械的に固定する。

Required Methods

fn forward<'t>( &self, tape: TapeRef<'t>, input: &Var<'t>, ) -> Result<Var<'t>, AutodiffError>

このステップの tape 上で 1 回分の forward を計算する。

tape は crate::TapeRef（TapeRef::from(&fandhe_ai::tape()) 等）。 パラメータは tape.var(&tensor) で葉ノード登録してから使う。

Provided Methods

fn named_parameters(&self) -> Vec<(String, &Tensor<f32>)>

学習可能パラメータの「名前, 参照」列。名前は struct フィールド名／accessor 名 を正とし、順序は登録順（weight → bias）。既定は空（無状態層向け）。

fn set_parameter( &mut self, name: &str, _value: Tensor<f32>, ) -> Result<(), AutodiffError>

Self::named_parameters が返す名前のパラメータを書き戻す（shape 保存置換のみ）。

該当名がなければ AutodiffError::InvalidArgument（fail-closed）。既定は常に Err （無状態層向け）。Self::named_parameters を override する層は必ず本メソッドも 対で override すること（片方だけだと Self::load_state_dict が Err になる）。

fn state_dict(&self) -> HashMap<String, Tensor<f32>>

Self::named_parameters のキー付きビュー（各値は clone）。順序契約は持たない。

fn load_state_dict( &mut self, state: HashMap<String, Tensor<f32>>, ) -> Result<(), AutodiffError>

Self::state_dict の逆（strict 限定）。

パス 1 でキー集合の完全一致（欠落・余剰を昇順列挙）と shape 完全一致を検証し （無変更）、パス 2 でキー名昇順に Self::set_parameter を適用する。途中で 失敗したら適用済みキーを逆順に元の値へ戻す。ロールバック自体が失敗した場合は 部分適用の可能性を明示した Err を返す（完全な原子性は保証しない）。

fn set_training(&mut self, _training: bool)

学習／評価モードの切替。既定は no-op（無状態層向け）。モード依存層は Self::training と必ず両方を override して自層に保持すること。

fn training(&self) -> bool

現在のモード。既定は true（PyTorch Module.training の初期値と同じ）。

fn set_requires_grad( &mut self, _requires_grad: bool, ) -> Result<(), AutodiffError>

層単位の requires_grad 凍結（PyTorch module.requires_grad_(bool) 相当。 #2137 の鏡写し・#2400）。

実装者契約: パラメータを持つ層は requires_grad: bool を自層に保持し、forward 内でパラメータ葉を if self.requires_grad { tape.var(&p) } else { tape.var_no_grad(&p) } のように切り替えて登録する。本メソッドと Self::requires_grad は必ず対で override すること。

複合層（Self::children が非空）が自身にも requires_grad フラグを持つ場合、 Self::requires_grad はそのフラグを返すこと。凍結が失敗したときのロールバックは 複合層ごとに「自身へ set_requires_grad(呼び出し前の自身の requires_grad()) → 子を葉単位で再帰復元」の順に呼んで戻す（自身の呼び出しが子へ伝播した値は直後の子の 復元で上書きされる）。ただし復元の前に子を照合キー（名前・型・アドレス・サイズ）で照合し、不一致なら自身の 呼び出しを省いて部分適用エラーにする（Self::children_mut 参照。検出範囲は同 doc の (b)〜(d) のとおりで、取り消しは不可）。不一致が無ければ自身のフラグと各子の状態が共に 呼び出し前へ戻る。

• 反映は次の forward（葉登録）から。登録済みの Var は変わらない。
• Self::set_training／Self::training とは独立の軸（BatchNorm 系の統計は 凍結後も training のまま更新される）。
• Self::state_dict／Self::load_state_dict／Self::set_parameter の対象外で、 パラメータを差し替えてもフラグは保持される。
• 粒度は層単位（パラメータ名指定の個別凍結は範囲外）。

既定は fail-closed: パラメータ 0 件なら Ok(())（無状態層）、1 件以上なら InvalidArgument。override 忘れで「凍結したつもりが学習が続く」黙った事故を 防ぐ（security.md A08。no-op 既定は採らない）。文言は autodiff 側と同一。

fn freeze(&mut self) -> Result<(), AutodiffError>

Self::set_requires_grad(false) の別名（転移学習で backbone を固定する典型呼び出し）。

fn requires_grad(&self) -> bool

この層が現在追跡対象か。既定は true（パラメータを持たない層は状態を持たない）。 パラメータを持つ層は Self::set_requires_grad と対で override する。自身のフラグを 持つ複合層はそのフラグを返すこと（ロールバックが自身→子の順に復元するため。 Self::set_requires_grad 参照）。

fn children(&self) -> Vec<(String, &dyn Module)>

この層が直接内包する子 Module の「名前, 参照」列を登録順で返す （autodiff Module::children・PyTorch Module.children() 相当。#2134・#2401）。

名前は Self::named_parameters の接頭辞と完全一致させる（ModuleList／ Sequential は "{index}"）。既定は空（葉モジュール向け）。

fn named_modules(&self) -> Vec<(String, &dyn Module)>

子孫を深さ優先（子自身 → その子孫）・登録順で再帰列挙する （autodiff Module::named_modules の鏡写し。#2134・#2401）。

ルート自身は含めない（Self: Sized 境界が object safety を壊すため。PyTorch の "" エントリとは異なる）。パスは "{parent}.{child}"。

循環・重複: 同一性は (データポインタ, type_name) の組で判定する。(1) 祖先スタックに 既出なら常に打ち切る（循環でも panic しない）、(2) ゼロサイズ型を除き訪問済み集合でも dedup する（共有子は最初の経路のみ。PyTorch の memo 相当）。ZST は複数インスタンスが dangling address を共有しうるため (2) から除外する。型名をキーに含めるのは、先頭 フィールドの子がルートと同一アドレスになる（offset 0）場合の誤判定を避けるため。

fn parameter_count(&self) -> usize

Self::named_parameters が公開する学習可能パラメータの総要素数 （autodiff Module::parameter_count の鏡写し。#2134・#2401）。 saturating_add で合計するためオーバーフローでも panic せず usize::MAX に飽和する。

fn type_name(&self) -> &'static str

実装型名（std::any::type_name::<Self>()）。出力形式は標準ライブラリが安定を 保証しないため表示用途に限る（autodiff Module::type_name の鏡写し。#2134・#2401）。 例外として、凍結ロールバックが子の型の照合キーに使う（Self::children_mut の (b)。 異なる型は区別できるが同じ型の別インスタンスは区別できない。偽る override は範囲外）。

fn children_mut(&mut self) -> Vec<(String, &mut dyn Module)>

Self::children の可変版（同じ「名前, 参照」列を同じ順序・同じ名前で返す。 #2400・PR #2426 レビュー是正。2026-09-29 ユーザー承認済みの公開面追加）。

用途: 凍結（Self::set_requires_grad）が失敗したとき、コンテナが子孫を葉単位 （葉 = Self::children が空の層）で呼び出し前の状態へ戻すための可変アクセス。 子を持つ利用者定義の複合層は children と対で必ず実装すること（children と同じ子への 参照を同じ順・同じ名前で返し、名前が同じでも別の子オブジェクトを返してはならない）。

契約と検出範囲（PR #2426 第 6〜8 回レビュー P1 是正。ライブラリは Module 参照から真の 同一性を得られないため、検出できる範囲を次のとおり定義する）:

• (a) 実装側の契約: Self::children／本メソッドは Self::set_requires_grad の間、 同じ子を返し続けること。
• (b) ライブラリは、件数・名前・型（Self::type_name）・データアドレス・サイズで検出 できる契約違反を、ModuleList／Sequential／ModuleDict の set_requires_grad が 状態を変更する前の InvalidArgument（事前検査。children_mut 未実装で children だけ 実装した層を含む）、または復元時の部分適用エラー（InvalidArgument）として報告する。 復元は複合層ごとに、まず本メソッドの子を取得時のキーと照合し、不一致なら自身の Self::set_requires_grad は呼ばない。一致した位置の子だけを葉単位で戻す。
• (c) 同じ型・同じ格納位置での値の置き換え（同じアドレスでの再確保を含む）は検出できず、 ロールバックは位置（格納スロット）単位で、そのスロットを凍結前の値へ戻す。
• (d) 自身の setter の実行中の伝播先は利用者の実装の責任で、ライブラリは防げない （事後の再照合で検出できる範囲だけ部分適用エラーとして報告し、取り消しはしない）。 type_name を偽って override する実装は信頼境界の外。
• 全一致のときは自身へ set_requires_grad を呼んでから本メソッドを取り直して再照合する。 取得時は葉（children が空）だった層が復元時に子を持っていれば、setter を呼ばず部分適用 エラーにする。

既定は空（葉モジュール向け）。

Trait Implementations

impl FromIterator<Box<dyn Module>> for ModuleList

fn from_iter<I: IntoIterator<Item = Box<dyn Module>>>(iter: I) -> Self

Creates a value from an iterator.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl Module for ModuleDict

impl Module for ModuleList

impl Module for Sequential

impl<M: Module> Module for ForwardHooked<M>