marcellodebernardi/loss-landscapes

什麼是 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️⃣ 選擇一個子空間 —— 當前權重周圍的隨機二維平面
plane = ll.random_plane(model, metric, normalize="filter")

# 4️⃣ `plane` 是一個二維 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/ 資料夾中的 Jupyter 筆記本，示範了損失等高線、3D 表面、曲率與 RL 回報損失面。

---

哪些人可能用得上？

• 機器學習研究者：研究優化幾何、平坦最小值 vs. 尖銳最小值，或正則化對損失面的影響。
• 實務工作者：想透過可視化模型在收斂權重附近的損失行為，來驗證訓練動態。
• 強化學習開發者：好奇策略參數如何影響預期回報。
• 教育者：尋找一種輕量級方法生成具體的損失面圖用於授課。

---

簡而言之：loss‑landscapes 是一個專注、原生 PyTorch 的工具包，將神經網路損失面這一抽象概念轉化為具體的數值網格，實際繪圖工作交由你完成。它正在積極現代化，請密切關注倉儲以取得即將發布的穩定版本。