marcellodebernardi/loss-landscapes

Approximating neural network loss landscapes in low-dimensional parameter subspaces for PyTorch

什么是 loss‑landscapes？

loss‑landscapes は PyTorch の上に構築された小さな Python ライブラリで、ニューラルネットワークの巨大なパラメータ空間の低次元スライス上で、スカラー量（損失、勾配ノルム、曲率、期待報酬など）をサンプリング・評価するのを支援します。直線、平面、その他の部分空間上で得られた数値データを提供することで、モデルの重みを動かしたときの損失の変化を示す、伝統的な損失面の可視化を簡単に作成できます。

コアとなるアイデア

コンセプト	機能
Metric	ラップされたモデルまたはエージェントを受け取り、単一の浮動小数点数（例：損失、勾配ノルム、曲率、期待報酬）を返す呼び出し可能オブジェクト。`Loss`、`LossGradient`、`PrincipalCurvatureEvaluator` などの一般的なメトリクスが標準搭載されており、`Metric` を継承して独自のメトリクスを定義できます。
パラメータ部分空間	全重み空間の低次元領域（点、直線、ランダムな平面など）。`random_plane` や `linear_interpolation` などの関数でこれらの部分空間を生成し、その内部のグリッド点でメトリクスを評価します。
ModelWrapper	内部のアダプタで、モデルや強化学習エージェントの呼び出し方法を隠蔽します。`forward` に似た一貫したインターフェースを提供するため、`torch.nn.Module` とより複雑なエージェントの両方で同じメトリクスコードが利用可能です。

一般的なワークフロー（Pythonスタイル）

import torch, loss_landscapes as ll

# 1️⃣ モデルの学習（任意の torch.nn.Module）…
model = MyNet()
# … 学習コード …

# 2️⃣ メトリクスの選択 – ここでは標準的な教師あり損失
metric = ll.metrics.Loss(loss_fn=torch.nn.CrossEntropyLoss(),
                         inputs=X_train, target=y_train)

# 3️⃣ 部分空間の選択 – 現在の重みの周りのランダムな2次元平面
plane = ll.random_plane(model, metric, normalize="filter")

# 4️⃣ `plane` は損失値の2次元 NumPy / torch 配列です。
#    matplotlib、plotly など、好きな方法でプロットできます。

このライブラリはプロットユーティリティを提供しません。返された配列を好きな可視化ツールに渡してください。

なぜ使うべきか？

再利用可能なメトリクス抽象化 – 損失、勾配、曲率、カスタム量を、ボイラープレートコードを再実装せずに評価可能。
複雑なエージェントのサポート – ModelWrapper を通じて、強化学習エージェントの期待報酬の損失面を探索可能（教師あり損失に限らない）。
正規化オプション – 例：normalize="filter" は方向をスケーリングして、誤解を招くスケール差を回避。
オープンソースかつ拡張可能 – Metric を継承して独自のメトリクスを追加可能。

現在の状態

元の2019年リリース（3.0.6）は 破損している（明示的な torch 依存性が欠落しており、数学的に誤った正規化を含む）。
長い休止期間を経てリポジトリが再開された。現在、最新の Python および PyTorch バージョンに対応する現代的な再実装が進行中。API は変更される可能性があり、作者は 新しいバージョンがリリースされるまで、公開された 3.0.6 パッケージの使用を避けるよう推奨 しています。

セットアップ方法

pip install loss-landscapes   # 最後に公開された wheel を取得（まだ古いままで）
# 最新コードで開発する場合：
uv sync --all-groups          # uv で依存関係をインストール
uv run pytest                 # テストスイートを実行

examples/ フォルダには、損失等高線、3D表面、曲率、RL報酬の損失面を示す Jupyter ノートブックが含まれています。

どんな人に役立つか？

機械学習研究者：最適化幾何、平坦な最小値 vs. 鋭い最小値、正則化が損失面に与える影響を調査する際。
実務家：収束した重みの周辺でのモデルの損失の振る舞いを可視化することで、学習ダイナミクスを検証したい人。
RL開発者：ポリシーのパラメータが期待報酬に与える影響に興味がある人。
教育者：講義で具体的な損失面のプロットを簡単に生成したい人。

要するに：loss‑landscapes は、ニューラルネットワークの損失面という抽象的概念を、実際の数値グリッドに変換する、焦点を絞った PyTorch ネイティブツールキットです。実際にプロットする部分はあなたに任されています。現在、積極的に現代化が進められており、安定版リリースのリポジトリを注目しておいてください。