fandhe-ai 0.13.0

//! `fandhe_ai::optim`（イシュー #961・親 #960）のみを optimizer 面として
//! 使う学習ループ統合テスト（受入基準 3「利用者が `fandhe_ai::optim` から
//! optimizer 一式を使えること」の構造的裏付け）。
//!
//! **本ファイルは `fandhe_ai` と `bench_harness::rng` 以外を import しない**
//! （`fandhe_ai_autodiff`／`fandhe_ai_tensor_core` を一切 import しない契約。
//! `crates/facade/tests/compat_sequential_train.rs` は内部クレート
//! `fandhe_ai_autodiff::optim`／`fandhe_ai_autodiff::nn::optim` を直接 import して
//! いるのに対し、本ファイルは「facade のみへの依存で学習ループが書ける」
//! ことを import 文そのもので裏付ける。レビュー・CI では
//! `grep -n "fandhe_ai_autodiff\|fandhe_ai_tensor_core" tests/optim_train_loop.rs`
//! がヒット 0 件であることを確認する）。
//!
//! **適用順序契約**: 1 学習ステップは
//! `backward → clip → optimizer step`（`fandhe_ai::optim` モジュール doc
//! 「適用順序契約」節「AMP を使わない場合」を参照。本ファイルは AMP
//! 非使用の既存経路（無変更で動作する契約）を固定する。AMP 使用時の
//! 順序は `crates/facade/tests/optim_amp_train_loop.rs`（イシュー #1722）
//! を参照）。
//!
//! **決定的シード**: モデル・データ・シードは
//! `crates/facade/tests/compat_sequential_train.rs` と同一
//! （`.claude/rules/coding-rust.md`「学習系回帰テストには決定的シード
//! 設定ユーティリティを使う」）。
//!
//! **数値判定の規律**: 収束判定は既存様式（最終 loss が初期 loss から
//! 十分減少すること）を踏襲し、新規の許容誤差（tolerance）は設けない
//! （`.claude/rules/coding-rust.md`）。
//!
//! 実機（CUDA/Metal）非依存のため `#[ignore]` 分離は行わない。

use bench_harness::rng::Xorshift64Star;
use fandhe_ai::Tensor;
use fandhe_ai::compat::Sequential;
use fandhe_ai::optim::{
    Adadelta, AdadeltaConfig, Adagrad, AdagradConfig, Adam, AdamConfig, AdamW, AdamWConfig, Adamax,
    AdamaxConfig, ConstantLr, CosineAnnealingLr, ExponentialLr, Lamb, LambConfig, LinearWarmupLr,
    LrScheduler, NAdam, NAdamConfig, OneCycleAnneal, OneCycleLr, OneCycleLrConfig, RAdam,
    RAdamConfig, RmsProp, RmsPropConfig, Sgd, SgdConfig, StepLr, clip_grad_norm, clip_grad_value,
};

const BATCH: usize = 4;
const D_IN: usize = 8;
const D_HIDDEN: usize = 16;
const D_OUT: usize = 4;

const SEED_DATA: u64 = 0xC0FFEE;
const SEED_L1: u64 = 0x1111_1111;
const SEED_L2: u64 = 0x2222_2222;

/// `crates/facade/tests/compat_sequential_train.rs::gen_regression_data`
/// と同一生成順（`x`: `[BATCH, D_IN]`・`y`: `[BATCH, D_OUT]`）。
fn gen_regression_data(seed: u64) -> (Tensor<f32>, Tensor<f32>) {
    let mut rng = Xorshift64Star::new(seed);
    let x = rng.fill_vec(BATCH * D_IN);
    let y = rng.fill_vec(BATCH * D_OUT);
    (
        Tensor::new(x, &[BATCH, D_IN])
            .unwrap_or_else(|e| panic!("test fixture: x の shape 構築に失敗: {e}")),
        Tensor::new(y, &[BATCH, D_OUT])
            .unwrap_or_else(|e| panic!("test fixture: y の shape 構築に失敗: {e}")),
    )
}

fn build_model() -> Sequential {
    Sequential::new()
        .add_linear(D_IN, D_HIDDEN, SEED_L1)
        .unwrap_or_else(|e| panic!("test fixture: 層 1 の構築に失敗: {e}"))
        .add_relu()
        .add_linear(D_HIDDEN, D_OUT, SEED_L2)
        .unwrap_or_else(|e| panic!("test fixture: 層 2 の構築に失敗: {e}"))
}

fn scalar(t: &Tensor<f32>) -> f32 {
    t.get(&[])
        .unwrap_or_else(|| panic!("test fixture: スカラー shape [] のはず"))
}

// =====================================================================
// Sgd + clip
// =====================================================================

/// `Sequential::bind` → forward → `Var::mse_loss` → `Tape::backward` →
/// `SequentialVars::trainable_grads` → `clip_grad_norm` → `Sgd::step` →
/// `Sequential::apply_parameters` の 1 ステップを `steps` 回繰り返す。
///
/// **借用スコープ**: `SequentialVars`（`bound`）は `&model`／`&tape` を
/// 借用するため、`apply_parameters`（`&mut model`）を呼ぶ前に必ず
/// ブロックを抜けて借用を解放する（`compat_sequential_train.rs` と同じ
/// 構成）。
fn train_with_sgd_and_clip(
    model: &mut Sequential,
    steps: usize,
    lr: f32,
    max_norm: f32,
) -> Vec<f32> {
    let (x_data, y_data) = gen_regression_data(SEED_DATA);
    let mut sgd = Sgd::new(SgdConfig::new(lr))
        .unwrap_or_else(|e| panic!("test fixture: Sgd::new が失敗した: {e}"));
    let mut log = Vec::with_capacity(steps);

    for _ in 0..steps {
        let updated = {
            let tape = fandhe_ai::tape();
            let bound = model.bind(&tape);
            let x = tape.var(&x_data);
            let y = tape.var(&y_data);

            let pred = bound
                .forward(&tape, &x)
                .unwrap_or_else(|e| panic!("test fixture: forward が失敗した: {e}"));
            let loss = pred
                .mse_loss(&y)
                .unwrap_or_else(|e| panic!("test fixture: mse_loss が失敗した: {e}"));
            log.push(scalar(&loss.to_tensor()));

            let grads = tape
                .backward(&loss)
                .unwrap_or_else(|e| panic!("test fixture: backward が失敗した: {e}"));
            let grad_refs = bound
                .trainable_grads(&grads)
                .unwrap_or_else(|e| panic!("test fixture: trainable_grads が失敗した: {e}"));
            // 適用順序契約: backward → clip → optimizer step。
            let clip_result = clip_grad_norm(&grad_refs, max_norm)
                .unwrap_or_else(|e| panic!("test fixture: clip_grad_norm が失敗した: {e}"));
            let clipped_grad_refs: Vec<&Tensor<f32>> = clip_result.grads.iter().collect();
            let param_refs = model.trainable_parameters();
            sgd.step(&param_refs, &clipped_grad_refs)
                .unwrap_or_else(|e| panic!("test fixture: Sgd::step が失敗した: {e}"))
        };
        model
            .apply_parameters(updated)
            .unwrap_or_else(|e| panic!("test fixture: apply_parameters が失敗した: {e}"));
    }

    log
}

/// `fandhe_ai::optim::{Sgd, clip_grad_norm}` のみを使った学習ループで
/// loss が減少すること（受入基準 3）。
#[test]
fn sgd_with_clip_converges_via_facade_only() {
    const STEPS: usize = 100;
    const LR: f32 = 0.05;
    const MAX_NORM: f32 = 10.0;

    let mut model = build_model();
    let log = train_with_sgd_and_clip(&mut model, STEPS, LR, MAX_NORM);

    assert_eq!(log.len(), STEPS);
    let initial = log[0];
    let final_loss = *log.last().unwrap_or_else(|| unreachable!("log は空でない"));
    assert!(final_loss.is_finite(), "final loss が非有限: {final_loss}");
    assert!(
        final_loss < 0.5 * initial,
        "loss did not converge sufficiently: initial={initial} final={final_loss}"
    );
}

// =====================================================================
// AdamW + clip
// =====================================================================

/// `Sequential::bind` → forward → `Var::mse_loss` → `Tape::backward` →
/// `SequentialVars::trainable_grads` → `clip_grad_norm` → `AdamW::step`
/// （`params_and_grads` タプル列を `zip` で構築） →
/// `Sequential::apply_parameters` の 1 ステップを `steps` 回繰り返す。
fn train_with_adamw_and_clip(model: &mut Sequential, steps: usize, max_norm: f32) -> Vec<f32> {
    let (x_data, y_data) = gen_regression_data(SEED_DATA);
    let mut adamw = AdamW::new(AdamWConfig::default())
        .unwrap_or_else(|e| panic!("test fixture: AdamW::new が失敗した: {e}"));
    let mut log = Vec::with_capacity(steps);

    for _ in 0..steps {
        let updated = {
            let tape = fandhe_ai::tape();
            let bound = model.bind(&tape);
            let x = tape.var(&x_data);
            let y = tape.var(&y_data);

            let pred = bound
                .forward(&tape, &x)
                .unwrap_or_else(|e| panic!("test fixture: forward が失敗した: {e}"));
            let loss = pred
                .mse_loss(&y)
                .unwrap_or_else(|e| panic!("test fixture: mse_loss が失敗した: {e}"));
            log.push(scalar(&loss.to_tensor()));

            let grads = tape
                .backward(&loss)
                .unwrap_or_else(|e| panic!("test fixture: backward が失敗した: {e}"));
            let grad_refs = bound
                .trainable_grads(&grads)
                .unwrap_or_else(|e| panic!("test fixture: trainable_grads が失敗した: {e}"));
            let clip_result = clip_grad_norm(&grad_refs, max_norm)
                .unwrap_or_else(|e| panic!("test fixture: clip_grad_norm が失敗した: {e}"));
            let param_refs = model.trainable_parameters();
            let params_and_grads: Vec<(&Tensor<f32>, &Tensor<f32>)> = param_refs
                .into_iter()
                .zip(clip_result.grads.iter())
                .collect();
            adamw
                .step(&params_and_grads)
                .unwrap_or_else(|e| panic!("test fixture: AdamW::step が失敗した: {e}"))
        };
        model
            .apply_parameters(updated)
            .unwrap_or_else(|e| panic!("test fixture: apply_parameters が失敗した: {e}"));
    }

    log
}

/// `fandhe_ai::optim::{AdamW, clip_grad_norm}` のみを使った学習ループで
/// loss が減少すること（受入基準 3）。
#[test]
fn adamw_with_clip_converges_via_facade_only() {
    const STEPS: usize = 100;
    const MAX_NORM: f32 = 10.0;

    let mut model = build_model();
    let log = train_with_adamw_and_clip(&mut model, STEPS, MAX_NORM);

    assert_eq!(log.len(), STEPS);
    let initial = log[0];
    let final_loss = *log.last().unwrap_or_else(|| unreachable!("log は空でない"));
    assert!(final_loss.is_finite(), "final loss が非有限: {final_loss}");
    assert!(
        final_loss < 0.5 * initial,
        "loss did not converge sufficiently: initial={initial} final={final_loss}"
    );
}

// =====================================================================
// Adam（coupled L2 weight decay。イシュー #1742）+ clip
// =====================================================================

/// `train_with_adamw_and_clip` と同型（`AdamW::step` を `Adam::step` へ
/// 差し替えただけ）。`wd>0` を指定し coupled 経路を実際に通す
/// （`optim.rs` モジュール doc「Adam（coupled L2 weight decay）」節）。
fn train_with_adam_and_clip(model: &mut Sequential, steps: usize, max_norm: f32) -> Vec<f32> {
    let (x_data, y_data) = gen_regression_data(SEED_DATA);
    let cfg = AdamConfig {
        weight_decay: 1e-4,
        ..AdamConfig::default()
    };
    let mut adam =
        Adam::new(cfg).unwrap_or_else(|e| panic!("test fixture: Adam::new が失敗した: {e}"));
    let mut log = Vec::with_capacity(steps);

    for _ in 0..steps {
        let updated = {
            let tape = fandhe_ai::tape();
            let bound = model.bind(&tape);
            let x = tape.var(&x_data);
            let y = tape.var(&y_data);

            let pred = bound
                .forward(&tape, &x)
                .unwrap_or_else(|e| panic!("test fixture: forward が失敗した: {e}"));
            let loss = pred
                .mse_loss(&y)
                .unwrap_or_else(|e| panic!("test fixture: mse_loss が失敗した: {e}"));
            log.push(scalar(&loss.to_tensor()));

            let grads = tape
                .backward(&loss)
                .unwrap_or_else(|e| panic!("test fixture: backward が失敗した: {e}"));
            let grad_refs = bound
                .trainable_grads(&grads)
                .unwrap_or_else(|e| panic!("test fixture: trainable_grads が失敗した: {e}"));
            let clip_result = clip_grad_norm(&grad_refs, max_norm)
                .unwrap_or_else(|e| panic!("test fixture: clip_grad_norm が失敗した: {e}"));
            let param_refs = model.trainable_parameters();
            let params_and_grads: Vec<(&Tensor<f32>, &Tensor<f32>)> = param_refs
                .into_iter()
                .zip(clip_result.grads.iter())
                .collect();
            adam.step(&params_and_grads)
                .unwrap_or_else(|e| panic!("test fixture: Adam::step が失敗した: {e}"))
        };
        model
            .apply_parameters(updated)
            .unwrap_or_else(|e| panic!("test fixture: apply_parameters が失敗した: {e}"));
    }

    log
}

/// `fandhe_ai::optim::{Adam, clip_grad_norm}` のみを使った学習ループで
/// loss が減少すること（受入基準 3。`AdamW` 版と同型の収束テスト）。
#[test]
fn adam_with_clip_converges_via_facade_only() {
    const STEPS: usize = 100;
    const MAX_NORM: f32 = 10.0;

    let mut model = build_model();
    let log = train_with_adam_and_clip(&mut model, STEPS, MAX_NORM);

    assert_eq!(log.len(), STEPS);
    let initial = log[0];
    let final_loss = *log.last().unwrap_or_else(|| unreachable!("log は空でない"));
    assert!(final_loss.is_finite(), "final loss が非有限: {final_loss}");
    assert!(
        final_loss < 0.5 * initial,
        "loss did not converge sufficiently: initial={initial} final={final_loss}"
    );
}

// =====================================================================
// RMSprop + clip（イシュー #1743・親 #1610）
// =====================================================================

/// `train_with_adamw_and_clip` と同型（`RmsProp::step` も `AdamW::step`
/// と同じ `&[(&Tensor<f32>, &Tensor<f32>)]` シグネチャのため差し替えの
/// みで構成できる）。`lr` は既定 `1e-2` では小規模 MLP で発散しうる
/// ため呼び出し元から渡す（`nn_optim_rmsprop.rs::mlp_converges_with_
/// rmsprop` と同じ理由）。
fn train_with_rmsprop_and_clip(
    model: &mut Sequential,
    steps: usize,
    lr: f32,
    max_norm: f32,
) -> Vec<f32> {
    let (x_data, y_data) = gen_regression_data(SEED_DATA);
    let cfg = RmsPropConfig {
        lr,
        ..RmsPropConfig::default()
    };
    let mut rmsprop =
        RmsProp::new(cfg).unwrap_or_else(|e| panic!("test fixture: RmsProp::new が失敗した: {e}"));
    let mut log = Vec::with_capacity(steps);

    for _ in 0..steps {
        let updated = {
            let tape = fandhe_ai::tape();
            let bound = model.bind(&tape);
            let x = tape.var(&x_data);
            let y = tape.var(&y_data);

            let pred = bound
                .forward(&tape, &x)
                .unwrap_or_else(|e| panic!("test fixture: forward が失敗した: {e}"));
            let loss = pred
                .mse_loss(&y)
                .unwrap_or_else(|e| panic!("test fixture: mse_loss が失敗した: {e}"));
            log.push(scalar(&loss.to_tensor()));

            let grads = tape
                .backward(&loss)
                .unwrap_or_else(|e| panic!("test fixture: backward が失敗した: {e}"));
            let grad_refs = bound
                .trainable_grads(&grads)
                .unwrap_or_else(|e| panic!("test fixture: trainable_grads が失敗した: {e}"));
            let clip_result = clip_grad_norm(&grad_refs, max_norm)
                .unwrap_or_else(|e| panic!("test fixture: clip_grad_norm が失敗した: {e}"));
            let param_refs = model.trainable_parameters();
            let params_and_grads: Vec<(&Tensor<f32>, &Tensor<f32>)> = param_refs
                .into_iter()
                .zip(clip_result.grads.iter())
                .collect();
            rmsprop
                .step(&params_and_grads)
                .unwrap_or_else(|e| panic!("test fixture: RmsProp::step が失敗した: {e}"))
        };
        model
            .apply_parameters(updated)
            .unwrap_or_else(|e| panic!("test fixture: apply_parameters が失敗した: {e}"));
    }

    log
}

/// `fandhe_ai::optim::{RmsProp, clip_grad_norm}` のみを使った学習
/// ループで loss が減少すること（受入基準 3）。
#[test]
fn rmsprop_with_clip_converges_via_facade_only() {
    const STEPS: usize = 100;
    const LR: f32 = 1e-3;
    const MAX_NORM: f32 = 10.0;

    let mut model = build_model();
    let log = train_with_rmsprop_and_clip(&mut model, STEPS, LR, MAX_NORM);

    assert_eq!(log.len(), STEPS);
    let initial = log[0];
    let final_loss = *log.last().unwrap_or_else(|| unreachable!("log は空でない"));
    assert!(final_loss.is_finite(), "final loss が非有限: {final_loss}");
    assert!(
        final_loss < 0.5 * initial,
        "loss did not converge sufficiently: initial={initial} final={final_loss}"
    );
}

// =====================================================================
// Adagrad + clip（イシュー #1743・親 #1610）
// =====================================================================

/// `train_with_adamw_and_clip` と同型（`Adagrad::step` も `AdamW::step`
/// と同じ `&[(&Tensor<f32>, &Tensor<f32>)]` シグネチャのため差し替えの
/// みで構成できる）。`lr` は既定 `1e-2`・100 step では収束不足になり
/// うるため呼び出し元から渡す（`nn_optim_adagrad.rs::mlp_converges_
/// with_adagrad` と同じ理由）。
fn train_with_adagrad_and_clip(
    model: &mut Sequential,
    steps: usize,
    lr: f32,
    max_norm: f32,
) -> Vec<f32> {
    let (x_data, y_data) = gen_regression_data(SEED_DATA);
    let cfg = AdagradConfig {
        lr,
        ..AdagradConfig::default()
    };
    let mut adagrad =
        Adagrad::new(cfg).unwrap_or_else(|e| panic!("test fixture: Adagrad::new が失敗した: {e}"));
    let mut log = Vec::with_capacity(steps);

    for _ in 0..steps {
        let updated = {
            let tape = fandhe_ai::tape();
            let bound = model.bind(&tape);
            let x = tape.var(&x_data);
            let y = tape.var(&y_data);

            let pred = bound
                .forward(&tape, &x)
                .unwrap_or_else(|e| panic!("test fixture: forward が失敗した: {e}"));
            let loss = pred
                .mse_loss(&y)
                .unwrap_or_else(|e| panic!("test fixture: mse_loss が失敗した: {e}"));
            log.push(scalar(&loss.to_tensor()));

            let grads = tape
                .backward(&loss)
                .unwrap_or_else(|e| panic!("test fixture: backward が失敗した: {e}"));
            let grad_refs = bound
                .trainable_grads(&grads)
                .unwrap_or_else(|e| panic!("test fixture: trainable_grads が失敗した: {e}"));
            let clip_result = clip_grad_norm(&grad_refs, max_norm)
                .unwrap_or_else(|e| panic!("test fixture: clip_grad_norm が失敗した: {e}"));
            let param_refs = model.trainable_parameters();
            let params_and_grads: Vec<(&Tensor<f32>, &Tensor<f32>)> = param_refs
                .into_iter()
                .zip(clip_result.grads.iter())
                .collect();
            adagrad
                .step(&params_and_grads)
                .unwrap_or_else(|e| panic!("test fixture: Adagrad::step が失敗した: {e}"))
        };
        model
            .apply_parameters(updated)
            .unwrap_or_else(|e| panic!("test fixture: apply_parameters が失敗した: {e}"));
    }

    log
}

/// `fandhe_ai::optim::{Adagrad, clip_grad_norm}` のみを使った学習
/// ループで loss が減少すること（受入基準 3）。
#[test]
fn adagrad_with_clip_converges_via_facade_only() {
    const STEPS: usize = 100;
    const LR: f32 = 5e-2;
    const MAX_NORM: f32 = 10.0;

    let mut model = build_model();
    let log = train_with_adagrad_and_clip(&mut model, STEPS, LR, MAX_NORM);

    assert_eq!(log.len(), STEPS);
    let initial = log[0];
    let final_loss = *log.last().unwrap_or_else(|| unreachable!("log は空でない"));
    assert!(final_loss.is_finite(), "final loss が非有限: {final_loss}");
    assert!(
        final_loss < 0.5 * initial,
        "loss did not converge sufficiently: initial={initial} final={final_loss}"
    );
}

// =====================================================================
// Adadelta／Adamax／NAdam／RAdam + clip（イシュー #2501。#2171 実装の
// facade 公開）。4 種とも `step` は `AdamW::step` と同一の
// `&[(&Tensor<f32>, &Tensor<f32>)]` シグネチャのため、step 呼び出しを
// クロージャで差し替える共通ループで `backward → clip → step` を固定する。
// =====================================================================

/// `train_with_adagrad_and_clip` と同型。optimizer の `step` をクロージャ
/// （更新後パラメータ列を返す）として受け取る。
fn train_with_step_and_clip<F>(
    model: &mut Sequential,
    steps: usize,
    max_norm: f32,
    mut step: F,
) -> Vec<f32>
where
    F: FnMut(&[(&Tensor<f32>, &Tensor<f32>)]) -> Vec<Tensor<f32>>,
{
    let (x_data, y_data) = gen_regression_data(SEED_DATA);
    let mut log = Vec::with_capacity(steps);

    for _ in 0..steps {
        let updated = {
            let tape = fandhe_ai::tape();
            let bound = model.bind(&tape);
            let x = tape.var(&x_data);
            let y = tape.var(&y_data);

            let pred = bound
                .forward(&tape, &x)
                .unwrap_or_else(|e| panic!("test fixture: forward が失敗した: {e}"));
            let loss = pred
                .mse_loss(&y)
                .unwrap_or_else(|e| panic!("test fixture: mse_loss が失敗した: {e}"));
            log.push(scalar(&loss.to_tensor()));

            let grads = tape
                .backward(&loss)
                .unwrap_or_else(|e| panic!("test fixture: backward が失敗した: {e}"));
            let grad_refs = bound
                .trainable_grads(&grads)
                .unwrap_or_else(|e| panic!("test fixture: trainable_grads が失敗した: {e}"));
            let clip_result = clip_grad_norm(&grad_refs, max_norm)
                .unwrap_or_else(|e| panic!("test fixture: clip_grad_norm が失敗した: {e}"));
            let param_refs = model.trainable_parameters();
            let params_and_grads: Vec<(&Tensor<f32>, &Tensor<f32>)> = param_refs
                .into_iter()
                .zip(clip_result.grads.iter())
                .collect();
            step(&params_and_grads)
        };
        model
            .apply_parameters(updated)
            .unwrap_or_else(|e| panic!("test fixture: apply_parameters が失敗した: {e}"));
    }

    log
}

/// 100 step で最終 loss が初期 loss の半分未満になること。
fn assert_converged(log: &[f32], steps: usize) {
    assert_eq!(log.len(), steps);
    let initial = log[0];
    let final_loss = *log.last().unwrap_or_else(|| unreachable!("log は空でない"));
    assert!(final_loss.is_finite(), "final loss が非有限: {final_loss}");
    assert!(
        final_loss < 0.5 * initial,
        "loss did not converge sufficiently: initial={initial} final={final_loss}"
    );
}

/// `fandhe_ai::optim::{Adadelta, clip_grad_norm}` のみを使った学習ループ。
#[test]
fn adadelta_with_clip_converges_via_facade_only() {
    let mut opt = Adadelta::new(AdadeltaConfig::default())
        .unwrap_or_else(|e| panic!("test fixture: Adadelta::new が失敗した: {e}"));
    let mut model = build_model();
    let log = train_with_step_and_clip(&mut model, 100, 10.0, |pg| {
        opt.step(pg)
            .unwrap_or_else(|e| panic!("test fixture: Adadelta::step が失敗した: {e}"))
    });
    assert_converged(&log, 100);
}

/// `fandhe_ai::optim::{Adamax, clip_grad_norm}` のみを使った学習ループ。
#[test]
fn adamax_with_clip_converges_via_facade_only() {
    let mut opt = Adamax::new(AdamaxConfig::default())
        .unwrap_or_else(|e| panic!("test fixture: Adamax::new が失敗した: {e}"));
    let mut model = build_model();
    let log = train_with_step_and_clip(&mut model, 100, 10.0, |pg| {
        opt.step(pg)
            .unwrap_or_else(|e| panic!("test fixture: Adamax::step が失敗した: {e}"))
    });
    assert_converged(&log, 100);
}

/// `fandhe_ai::optim::{NAdam, clip_grad_norm}` のみを使った学習ループ。
#[test]
fn nadam_with_clip_converges_via_facade_only() {
    let mut opt = NAdam::new(NAdamConfig::default())
        .unwrap_or_else(|e| panic!("test fixture: NAdam::new が失敗した: {e}"));
    let mut model = build_model();
    let log = train_with_step_and_clip(&mut model, 100, 10.0, |pg| {
        opt.step(pg)
            .unwrap_or_else(|e| panic!("test fixture: NAdam::step が失敗した: {e}"))
    });
    assert_converged(&log, 100);
}

/// `fandhe_ai::optim::{RAdam, clip_grad_norm}` のみを使った学習ループ。
/// `lr=0.01` は `compat_sequential_optim_ext.rs`・`nn_optim_radam.rs` と同じ。
#[test]
fn radam_with_clip_converges_via_facade_only() {
    let cfg = RAdamConfig {
        lr: 0.01,
        ..RAdamConfig::default()
    };
    let mut opt =
        RAdam::new(cfg).unwrap_or_else(|e| panic!("test fixture: RAdam::new が失敗した: {e}"));
    let mut model = build_model();
    let log = train_with_step_and_clip(&mut model, 100, 10.0, |pg| {
        opt.step(pg)
            .unwrap_or_else(|e| panic!("test fixture: RAdam::step が失敗した: {e}"))
    });
    assert_converged(&log, 100);
}

// =====================================================================
// LAMB（layer-wise trust ratio。イシュー #1744）+ clip
// =====================================================================

/// `train_with_adamw_and_clip` と同型（`AdamW::step` を `Lamb::step` へ
/// 差し替えただけ）。trust ratio により実効ステップが縮むため、`AdamW`
/// 用 lr（既定 `1e-3`）のままでは 100 step で収束しない（実測で確認
/// 済み）ため lr を大きくしている（`crates/autodiff/tests/
/// nn_optim_lamb.rs::mlp_converges_with_lamb` と同じ lr）。
fn train_with_lamb_and_clip(model: &mut Sequential, steps: usize, max_norm: f32) -> Vec<f32> {
    let (x_data, y_data) = gen_regression_data(SEED_DATA);
    let cfg = LambConfig {
        lr: 0.02,
        ..LambConfig::default()
    };
    let mut lamb =
        Lamb::new(cfg).unwrap_or_else(|e| panic!("test fixture: Lamb::new が失敗した: {e}"));
    let mut log = Vec::with_capacity(steps);

    for _ in 0..steps {
        let updated = {
            let tape = fandhe_ai::tape();
            let bound = model.bind(&tape);
            let x = tape.var(&x_data);
            let y = tape.var(&y_data);

            let pred = bound
                .forward(&tape, &x)
                .unwrap_or_else(|e| panic!("test fixture: forward が失敗した: {e}"));
            let loss = pred
                .mse_loss(&y)
                .unwrap_or_else(|e| panic!("test fixture: mse_loss が失敗した: {e}"));
            log.push(scalar(&loss.to_tensor()));

            let grads = tape
                .backward(&loss)
                .unwrap_or_else(|e| panic!("test fixture: backward が失敗した: {e}"));
            let grad_refs = bound
                .trainable_grads(&grads)
                .unwrap_or_else(|e| panic!("test fixture: trainable_grads が失敗した: {e}"));
            // 適用順序契約: backward → clip → optimizer step。
            let clip_result = clip_grad_norm(&grad_refs, max_norm)
                .unwrap_or_else(|e| panic!("test fixture: clip_grad_norm が失敗した: {e}"));
            let param_refs = model.trainable_parameters();
            let params_and_grads: Vec<(&Tensor<f32>, &Tensor<f32>)> = param_refs
                .into_iter()
                .zip(clip_result.grads.iter())
                .collect();
            lamb.step(&params_and_grads)
                .unwrap_or_else(|e| panic!("test fixture: Lamb::step が失敗した: {e}"))
        };
        model
            .apply_parameters(updated)
            .unwrap_or_else(|e| panic!("test fixture: apply_parameters が失敗した: {e}"));
    }

    log
}

/// `fandhe_ai::optim::{Lamb, clip_grad_norm}` のみを使った学習ループで
/// loss が減少すること（受入基準 3。`AdamW` 版と同型の収束テスト）。
#[test]
fn lamb_with_clip_converges_via_facade_only() {
    const STEPS: usize = 100;
    const MAX_NORM: f32 = 10.0;

    let mut model = build_model();
    let log = train_with_lamb_and_clip(&mut model, STEPS, MAX_NORM);

    assert_eq!(log.len(), STEPS);
    let initial = log[0];
    let final_loss = *log.last().unwrap_or_else(|| unreachable!("log は空でない"));
    assert!(final_loss.is_finite(), "final loss が非有限: {final_loss}");
    assert!(
        final_loss < 0.5 * initial,
        "loss did not converge sufficiently: initial={initial} final={final_loss}"
    );
}

// =====================================================================
// clip → step 順序契約の効果確認
// =====================================================================

/// 極端に小さい `max_norm` で clip した場合、1 ステップ目の更新幅が
/// clip なしより小さくなること（`scaled == true` を伴う）を確認する
/// （適用順序契約「clip は optimizer step の前に適用する」の効果が
/// 実際に現れることの回帰チェック。tolerance は使わず不等号比較のみ）。
#[test]
fn clip_before_step_order_contract_is_documented_and_effective() {
    const LR: f32 = 0.05;
    const TINY_MAX_NORM: f32 = 1e-3;
    const LARGE_MAX_NORM: f32 = 1e6;

    let (x_data, y_data) = gen_regression_data(SEED_DATA);

    // 同一初期パラメータから 1 step 分の grad を計算し、clip 適用の有無
    // で `ClipGradResult` を比較する（optimizer step 自体は本テストの
    // 主眼ではないため、`clip_grad_norm` の出力比較に絞る）。
    let model = build_model();
    let tape = fandhe_ai::tape();
    let bound = model.bind(&tape);
    let x = tape.var(&x_data);
    let y = tape.var(&y_data);
    let pred = bound
        .forward(&tape, &x)
        .unwrap_or_else(|e| panic!("test fixture: forward が失敗した: {e}"));
    let loss = pred
        .mse_loss(&y)
        .unwrap_or_else(|e| panic!("test fixture: mse_loss が失敗した: {e}"));
    let grads = tape
        .backward(&loss)
        .unwrap_or_else(|e| panic!("test fixture: backward が失敗した: {e}"));
    let grad_refs = bound
        .trainable_grads(&grads)
        .unwrap_or_else(|e| panic!("test fixture: trainable_grads が失敗した: {e}"));

    let tiny = clip_grad_norm(&grad_refs, TINY_MAX_NORM)
        .unwrap_or_else(|e| panic!("test fixture: clip_grad_norm(tiny) が失敗した: {e}"));
    let large = clip_grad_norm(&grad_refs, LARGE_MAX_NORM)
        .unwrap_or_else(|e| panic!("test fixture: clip_grad_norm(large) が失敗した: {e}"));

    assert!(
        tiny.scaled,
        "max_norm={TINY_MAX_NORM} は total_norm={} より小さいはずで scaled=true になるべき",
        tiny.total_norm
    );
    assert!(
        !large.scaled,
        "max_norm={LARGE_MAX_NORM} は total_norm={} より大きいはずで scaled=false になるべき",
        large.total_norm
    );

    // clip 後の勾配ノルムは tiny 側が明確に小さい（LR を掛けても同じ
    // 大小関係が保たれる。順序契約が効いていることの確認）。
    let tiny_norm_sq: f32 = tiny
        .grads
        .iter()
        .map(|g| {
            g.as_slice()
                .unwrap_or_else(|| unreachable!("contiguous なテンソルのはず"))
                .iter()
                .map(|v| v * v)
                .sum::<f32>()
        })
        .sum();
    let large_norm_sq: f32 = large
        .grads
        .iter()
        .map(|g| {
            g.as_slice()
                .unwrap_or_else(|| unreachable!("contiguous なテンソルのはず"))
                .iter()
                .map(|v| v * v)
                .sum::<f32>()
        })
        .sum();
    assert!(
        tiny_norm_sq < large_norm_sq,
        "tiny クリップ後の勾配ノルムが large クリップ後より小さくなっていない\
         （clip → step の順序契約の効果が確認できない）: tiny={tiny_norm_sq} large={large_norm_sq}"
    );
    let _ = LR; // LR は本テストの意図（クリップ効果の説明）を明確にするための定数。
}

// =====================================================================
// LrScheduler + Sgd
// =====================================================================

/// `StepLr::lr_at(step)` の返す学習率で毎 step `SgdConfig` を作り直し、
/// `Sgd`（momentum 無し）で数ステップ回す。lr の切り替わり系列と loss
/// 減少の両方を確認する（受入基準 3。`fandhe_ai::optim::{StepLr,
/// LrScheduler, Sgd, SgdConfig}` のみを使用）。
#[test]
fn lr_scheduler_drives_sgd_config_via_facade_only() {
    const STEPS: usize = 6;
    const BASE_LR: f32 = 0.1;
    const STEP_SIZE: usize = 2;
    const GAMMA: f32 = 0.5;

    let scheduler = StepLr::new(BASE_LR, STEP_SIZE, GAMMA)
        .unwrap_or_else(|e| panic!("test fixture: StepLr::new が失敗した: {e}"));

    // `lr_at` の返り値が期待する階段減衰系列と完全一致することを固定
    // する（tolerance 不使用。`StepLr` の定義: lr = base_lr * gamma^(step / step_size)
    // 〈整数除算切り捨て〉）。
    let expected_lrs = [0.1_f32, 0.1, 0.05, 0.05, 0.025, 0.025];
    let observed_lrs: Vec<f32> = (0..STEPS).map(|step| scheduler.lr_at(step)).collect();
    assert_eq!(
        observed_lrs, expected_lrs,
        "StepLr::lr_at の系列が期待値と一致しない"
    );

    let mut model = build_model();
    let (x_data, y_data) = gen_regression_data(SEED_DATA);
    let mut log = Vec::with_capacity(STEPS);

    for step in 0..STEPS {
        let lr = scheduler.lr_at(step);
        let mut sgd = Sgd::new(SgdConfig::new(lr))
            .unwrap_or_else(|e| panic!("test fixture: Sgd::new が失敗した: {e}"));

        let updated = {
            let tape = fandhe_ai::tape();
            let bound = model.bind(&tape);
            let x = tape.var(&x_data);
            let y = tape.var(&y_data);

            let pred = bound
                .forward(&tape, &x)
                .unwrap_or_else(|e| panic!("test fixture: forward が失敗した: {e}"));
            let loss = pred
                .mse_loss(&y)
                .unwrap_or_else(|e| panic!("test fixture: mse_loss が失敗した: {e}"));
            log.push(scalar(&loss.to_tensor()));

            let grads = tape
                .backward(&loss)
                .unwrap_or_else(|e| panic!("test fixture: backward が失敗した: {e}"));
            let grad_refs = bound
                .trainable_grads(&grads)
                .unwrap_or_else(|e| panic!("test fixture: trainable_grads が失敗した: {e}"));
            let param_refs = model.trainable_parameters();
            sgd.step(&param_refs, &grad_refs)
                .unwrap_or_else(|e| panic!("test fixture: Sgd::step が失敗した: {e}"))
        };
        model
            .apply_parameters(updated)
            .unwrap_or_else(|e| panic!("test fixture: apply_parameters が失敗した: {e}"));
    }

    assert_eq!(log.len(), STEPS);
    let initial = log[0];
    let final_loss = *log.last().unwrap_or_else(|| unreachable!("log は空でない"));
    assert!(final_loss.is_finite(), "final loss が非有限: {final_loss}");
    assert!(
        final_loss < initial,
        "loss did not decrease: initial={initial} final={final_loss}"
    );

    // `ConstantLr` も同モジュールから到達可能であることを併せて確認する
    // （facade のみ依存で `optim::{ConstantLr, LrScheduler}` を使える裏付け）。
    let constant = ConstantLr::new(BASE_LR)
        .unwrap_or_else(|e| panic!("test fixture: ConstantLr::new が失敗した: {e}"));
    assert_eq!(constant.lr_at(0), BASE_LR);
    assert_eq!(constant.lr_at(100), BASE_LR);
}

// =====================================================================
// Sgd + clip_grad_value（イシュー #1753・親 #1631）
// =====================================================================

/// `Sequential::bind` → forward → `Var::mse_loss` → `Tape::backward` →
/// `SequentialVars::trainable_grads` → `clip_grad_value` → `Sgd::step` →
/// `Sequential::apply_parameters` の 1 ステップを `steps` 回繰り返す
/// （`train_with_sgd_and_clip` の value 方式版。適用順序契約
/// `backward → clip → optimizer step` は norm 方式と同一）。
fn train_with_sgd_and_clip_value(
    model: &mut Sequential,
    steps: usize,
    lr: f32,
    clip_value: f32,
) -> Vec<f32> {
    let (x_data, y_data) = gen_regression_data(SEED_DATA);
    let mut sgd = Sgd::new(SgdConfig::new(lr))
        .unwrap_or_else(|e| panic!("test fixture: Sgd::new が失敗した: {e}"));
    let mut log = Vec::with_capacity(steps);

    for _ in 0..steps {
        let updated = {
            let tape = fandhe_ai::tape();
            let bound = model.bind(&tape);
            let x = tape.var(&x_data);
            let y = tape.var(&y_data);

            let pred = bound
                .forward(&tape, &x)
                .unwrap_or_else(|e| panic!("test fixture: forward が失敗した: {e}"));
            let loss = pred
                .mse_loss(&y)
                .unwrap_or_else(|e| panic!("test fixture: mse_loss が失敗した: {e}"));
            log.push(scalar(&loss.to_tensor()));

            let grads = tape
                .backward(&loss)
                .unwrap_or_else(|e| panic!("test fixture: backward が失敗した: {e}"));
            let grad_refs = bound
                .trainable_grads(&grads)
                .unwrap_or_else(|e| panic!("test fixture: trainable_grads が失敗した: {e}"));
            // 適用順序契約: backward → clip → optimizer step。
            let clipped = clip_grad_value(&grad_refs, clip_value)
                .unwrap_or_else(|e| panic!("test fixture: clip_grad_value が失敗した: {e}"));
            let clipped_grad_refs: Vec<&Tensor<f32>> = clipped.iter().collect();
            let param_refs = model.trainable_parameters();
            sgd.step(&param_refs, &clipped_grad_refs)
                .unwrap_or_else(|e| panic!("test fixture: Sgd::step が失敗した: {e}"))
        };
        model
            .apply_parameters(updated)
            .unwrap_or_else(|e| panic!("test fixture: apply_parameters が失敗した: {e}"));
    }

    log
}

/// `fandhe_ai::optim::{Sgd, clip_grad_value}` のみを使った学習ループで
/// loss が減少すること（受入基準 3。`clip_grad_norm` 版と対になる value
/// 方式の facade-only 収束確認）。
#[test]
fn sgd_with_clip_value_converges_via_facade_only() {
    const STEPS: usize = 100;
    const LR: f32 = 0.05;
    const CLIP_VALUE: f32 = 1.0;

    let mut model = build_model();
    let log = train_with_sgd_and_clip_value(&mut model, STEPS, LR, CLIP_VALUE);

    assert_eq!(log.len(), STEPS);
    let initial = log[0];
    let final_loss = *log.last().unwrap_or_else(|| unreachable!("log は空でない"));
    assert!(final_loss.is_finite(), "final loss が非有限: {final_loss}");
    assert!(
        final_loss < 0.5 * initial,
        "loss did not converge sufficiently: initial={initial} final={final_loss}"
    );
}
/// イシュー #1745（親 #1611）: `CosineAnnealingLr`／`ExponentialLr`／
/// `LinearWarmupLr` が `ConstantLr`／`StepLr` と同じく `fandhe_ai::optim`
/// のみへの依存で学習ループを駆動できることを固定する（facade のみ
/// import の裏付け。`lr_scheduler_drives_sgd_config_via_facade_only` の
/// 姉妹テスト）。`CosineAnnealingLr` の系列を毎 step `lr_at(step)` で
/// 取り出して `SgdConfig` を作り直す構成のみ確認し、他 2 種は
/// `nn_optim_lr_scheduler.rs` の系列テストへ委ねる。
#[test]
fn cosine_annealing_lr_scheduler_drives_sgd_config_via_facade_only() {
    const STEPS: usize = 6;
    const BASE_LR: f32 = 0.1;
    const T_MAX: usize = 4;

    let scheduler = CosineAnnealingLr::new(BASE_LR, T_MAX, 0.0)
        .unwrap_or_else(|e| panic!("test fixture: CosineAnnealingLr::new が失敗した: {e}"));

    let mut model = build_model();
    let (x_data, y_data) = gen_regression_data(SEED_DATA);
    let mut log = Vec::with_capacity(STEPS);

    for step in 0..STEPS {
        let lr = scheduler.lr_at(step);
        // lr_at は非負を返しうる。`SgdConfig::validate` は lr<0.0 のみ
        // 拒否し lr==0.0 は受理するため、非負であれば常に Sgd::new は
        // 成功する（`ConstantLr`／`StepLr` と同じ制約）。
        let mut sgd = Sgd::new(SgdConfig::new(lr))
            .unwrap_or_else(|e| panic!("test fixture: Sgd::new が失敗した: {e}"));

        let updated = {
            let tape = fandhe_ai::tape();
            let bound = model.bind(&tape);
            let x = tape.var(&x_data);
            let y = tape.var(&y_data);

            let pred = bound
                .forward(&tape, &x)
                .unwrap_or_else(|e| panic!("test fixture: forward が失敗した: {e}"));
            let loss = pred
                .mse_loss(&y)
                .unwrap_or_else(|e| panic!("test fixture: mse_loss が失敗した: {e}"));
            log.push(scalar(&loss.to_tensor()));

            let grads = tape
                .backward(&loss)
                .unwrap_or_else(|e| panic!("test fixture: backward が失敗した: {e}"));
            let grad_refs = bound
                .trainable_grads(&grads)
                .unwrap_or_else(|e| panic!("test fixture: trainable_grads が失敗した: {e}"));
            let param_refs = model.trainable_parameters();
            sgd.step(&param_refs, &grad_refs)
                .unwrap_or_else(|e| panic!("test fixture: Sgd::step が失敗した: {e}"))
        };
        model
            .apply_parameters(updated)
            .unwrap_or_else(|e| panic!("test fixture: apply_parameters が失敗した: {e}"));
    }

    assert_eq!(log.len(), STEPS);
    let initial = log[0];
    let final_loss = *log.last().unwrap_or_else(|| unreachable!("log は空でない"));
    assert!(final_loss.is_finite(), "final loss が非有限: {final_loss}");
    assert!(
        final_loss < initial,
        "loss did not decrease: initial={initial} final={final_loss}"
    );

    // `ExponentialLr`／`LinearWarmupLr` も同モジュールから到達可能で
    // あることを併せて確認する（facade のみ依存で
    // `optim::{ExponentialLr, LinearWarmupLr}` を使える裏付け）。
    let exponential = ExponentialLr::new(BASE_LR, 0.9)
        .unwrap_or_else(|e| panic!("test fixture: ExponentialLr::new が失敗した: {e}"));
    let warmup = LinearWarmupLr::new(BASE_LR, T_MAX, 0.25)
        .unwrap_or_else(|e| panic!("test fixture: LinearWarmupLr::new が失敗した: {e}"));
    assert!((exponential.lr_at(0) - BASE_LR).abs() < 1e-6);
    assert!((warmup.lr_at(T_MAX) - BASE_LR).abs() < 1e-6);
}
/// イシュー #1747（親 #1611）: `OneCycleLr` が facade のみを通じて
/// SGD の学習ループを駆動できることを固定する（`cosine_annealing_lr_
/// scheduler_drives_sgd_config_via_facade_only` の鏡写し）。
#[test]
fn one_cycle_lr_scheduler_drives_sgd_config_via_facade_only() {
    const STEPS: usize = 6;
    const MAX_LR: f32 = 0.1;
    const TOTAL_STEPS: usize = STEPS;

    let scheduler = OneCycleLr::new(OneCycleLrConfig::new(MAX_LR, TOTAL_STEPS))
        .unwrap_or_else(|e| panic!("test fixture: OneCycleLr::new が失敗した: {e}"));

    let mut model = build_model();
    let (x_data, y_data) = gen_regression_data(SEED_DATA);
    let mut log = Vec::with_capacity(STEPS);

    for step in 0..STEPS {
        let lr = scheduler.lr_at(step);
        // `OneCycleLr::lr_at` は常に正の値を返す（`initial_lr`〜
        // `max_lr` の範囲内。`min_lr` も `> 0`）ため `Sgd::new` は
        // 常に成功する（`CosineAnnealingLr` テストと異なり lr==0.0 に
        // なることはない）。
        let mut sgd = Sgd::new(SgdConfig::new(lr))
            .unwrap_or_else(|e| panic!("test fixture: Sgd::new が失敗した: {e}"));

        let updated = {
            let tape = fandhe_ai::tape();
            let bound = model.bind(&tape);
            let x = tape.var(&x_data);
            let y = tape.var(&y_data);

            let pred = bound
                .forward(&tape, &x)
                .unwrap_or_else(|e| panic!("test fixture: forward が失敗した: {e}"));
            let loss = pred
                .mse_loss(&y)
                .unwrap_or_else(|e| panic!("test fixture: mse_loss が失敗した: {e}"));
            log.push(scalar(&loss.to_tensor()));

            let grads = tape
                .backward(&loss)
                .unwrap_or_else(|e| panic!("test fixture: backward が失敗した: {e}"));
            let grad_refs = bound
                .trainable_grads(&grads)
                .unwrap_or_else(|e| panic!("test fixture: trainable_grads が失敗した: {e}"));
            let param_refs = model.trainable_parameters();
            sgd.step(&param_refs, &grad_refs)
                .unwrap_or_else(|e| panic!("test fixture: Sgd::step が失敗した: {e}"))
        };
        model
            .apply_parameters(updated)
            .unwrap_or_else(|e| panic!("test fixture: apply_parameters が失敗した: {e}"));
    }

    assert_eq!(log.len(), STEPS);
    let initial = log[0];
    let final_loss = *log.last().unwrap_or_else(|| unreachable!("log は空でない"));
    assert!(final_loss.is_finite(), "final loss が非有限: {final_loss}");
    assert!(
        final_loss < initial,
        "loss did not decrease: initial={initial} final={final_loss}"
    );

    // `OneCycleAnneal::Linear` 指定でも同モジュールから到達可能で
    // あることを併せて確認する（facade のみ依存で `optim::
    // {OneCycleAnneal, OneCycleLr, OneCycleLrConfig}` を使える裏付け）。
    let linear_config = OneCycleLrConfig {
        anneal_strategy: OneCycleAnneal::Linear,
        ..OneCycleLrConfig::new(MAX_LR, TOTAL_STEPS)
    };
    let linear_scheduler = OneCycleLr::new(linear_config)
        .unwrap_or_else(|e| panic!("test fixture: OneCycleLr::new(Linear) が失敗した: {e}"));
    assert!((linear_scheduler.lr_at(0) - MAX_LR / 25.0).abs() < 1e-6);
    assert!((linear_scheduler.lr_at(TOTAL_STEPS - 1) - MAX_LR / 25.0 / 1e4).abs() < 1e-6);
}