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 的工具包，将神经网络损失面这一抽象概念转化为具体的数值网格，实际绘图工作交由你完成。它正在积极现代化，敬请关注仓库以获取即将发布的稳定版本。