normflows: 一个基于 PyTorch 的归一化流（Normalizing Flows）包

normflows 是一个离散归一化流（discrete normalizing flows）的 PyTorch 实现。实现了许多流行的流架构，详见 下方列表。该包可以通过 pip 轻松安装。基本用法在 此处 描述，同时也提供 完整文档。关于本包的更详细描述见我们的 配套论文。

在 examples 文件夹 中提供了几个示例用例，包括 Glow、VAE 和 Residual Flow。此外，两个简单应用在 示例部分 中被突出展示。你可以使用下方的链接自己在 Google Colab 中运行它们，以熟悉 normflows。

Link	Description
	Real NVP 应用于双模态二维目标分布
	使用神经样条流（Neural Spline Flow）对圆柱面上的分布进行建模
	使用 Glow 建模和生成 CIFAR-10 图像

Implemented Flows

Architecture	Reference
Planar Flow (平面流)	Rezende & Mohamed, 2015
Radial Flow (径向流)	Rezende & Mohamed, 2015
NICE	Dinh et al., 2014
Real NVP	Dinh et al., 2017
Glow	Kingma et al., 2018
Masked Autoregressive Flow (掩码自回归流)	Papamakarios et al., 2017
Neural Spline Flow (神经样条流)	Durkan et al., 2019
Circular Neural Spline Flow (圆形神经样条流)	Rezende et al., 2020
Residual Flow (残差流)	Chen et al., 2019
Stochastic Normalizing Flow (随机归一化流)	Wu et al., 2020

注意，也支持具有圆形和非圆形坐标的神经样条流（Neural Spline Flows）。

Installation

该包的最新版可通过 pip 安装

pip install normflows

至少需要 Python 3.7。如果你打算使用 GPU，请按照 PyTorch 网站 上的说明确保 PyTorch 配置正确。

要运行示例笔记本，请先克隆仓库

git clone https://github.com/VincentStimper/normalizing-flows.git

然后安装依赖项。

pip install -r requirements_examples.txt

使用

一个归一化流（Normalizing Flow）由定义在 nf.distributions.base 的基础分布和 nf.flows 中给出的流列表组成。 假设我们的目标是二维分布。我们选择一个对角高斯基础分布，这是最常见的选择。我们的流将是一个 Real NVP 模型，因此我们需要 定义一个神经网络来计算仿射耦合映射的参数。一个维度用于计算另一个维度的缩放和平移参数。在每个耦合层之后，我们交换它们的角色。

import normflows as nf

# Define 2D Gaussian base distribution
base = nf.distributions.base.DiagGaussian(2)

# Define list of flows
num_layers = 32
flows = []
for i in range(num_layers):
    # Neural network with two hidden layers having 64 units each
    # Last layer is initialized by zeros making training more stable
    param_map = nf.nets.MLP([1, 64, 64, 2], init_zeros=True)
    # Add flow layer
    flows.append(nf.flows.AffineCouplingBlock(param_map))
    # Swap dimensions
    flows.append(nf.flows.Permute(2, mode='swap'))

设置完成后，我们可以定义一个 nf.NormalizingFlow 模型。如果目标密度可用，可以将其添加到模型中以便在训练期间使用。示例目标分布在 nf.distributions.target 中给出。

# If the target density is not given
model = nf.NormalizingFlow(base, flows)

# If the target density is given
target = nf.distributions.target.TwoMoons()
model = nf.NormalizingFlow(base, flows, target)

可以使用模型的这些方法计算损失并进行最小化。

# When doing maximum likelihood learning, i.e. minimizing the forward KLD
# with no target distribution given
loss = model.forward_kld(x)

# When minimizing the reverse KLD based on the given target distribution
loss = model.reverse_kld(num_samples=512)

# Optimization as usual
loss.backward()
optimizer.step()

示例

我们在 examples 目录下提供了几个关于如何使用该包的说明性示例。其中包括 Glow、 变分自编码器（VAE） 的实现，以及 残差流（Residual Flow）。 更高级的实验可以在 重采样基础分布的仓库 中列出的脚本中进行，请参阅其 experiments 文件夹。

下面，我们考虑两个简单的二维示例。

Real NVP 应用于二维双峰目标分布

在 这个笔记本 中， 可以直接在 Colab 中打开， 我们将具有两个半月形模式的二维分布作为目标。我们用 Real NVP 模型对其进行近似，并获得以下结果。

请注意，两个模式之间可能存在连接密度细丝，这是由于归一化流的架构限制所致，特别是在 Real NVP 中尤为明显。你可以在 这篇论文 中找到更多关于它的信息。

使用神经样条流（Neural Spline Flow）对圆柱面上的分布进行建模

在 另一个示例 中， 该示例也可在 Colab 上获得， 我们将神经样条流（Neural Spline Flow）模型应用于圆柱上定义的分布。生成的密度如下图所示。

本示例包含在与本仓库配套的 论文 中。

支持

如果您遇到问题，请阅读 包文档 并查看上面的 示例部分。也欢迎您在 GitHub 上创建问题 以获取帮助。请注意，浏览现有的 开放 和 已关闭 问题是值得的，这些问题可能解决了您面临的问题。

贡献

如果您发现错误或有功能请求，请在 GitHub 上提交问题。

欢迎您通过修复错误或添加功能来为包做出贡献。如果您想贡献，请为您添加或修改的代码添加测试，并通过运行 pytest 确保其成功通过。 这可以通过在您的本地仓库版本中简单地执行以下命令来完成：

pytest

确保您的代码文档完善，我们也鼓励对现有文档做出贡献。完成编码和测试后，请在 GitHub 上创建拉取请求。

使用情况

该包已被应用于多项研究论文中。其中部分列举如下。

Andrew Campbell, Wenlong Chen, Vincent Stimper, José Miguel Hernández-Lobato, and Yichuan Zhang. 一种基于梯度的哈密顿蒙特卡洛超参数优化策略. 发表于第 38 届国际机器学习大会论文集，pp. 1238–1248. PMLR, 2021.

代码托管于 GitHub。

Vincent Stimper, Bernhard Schölkopf, and José Miguel Hernández-Lobato. 重采样归一化流的基分布. 发表于第 25 届人工智能与统计国际会议论文集，volume 151, pp. 4915–4936, 2022.

代码托管于 GitHub。

Laurence I. Midgley, Vincent Stimper, Gregor N. C. Simm, Bernhard Schölkopf, and José Miguel Hernández-Lobato. 流退火重要性采样 Bootstrap. 第十一届表示学习国际会议，2023.

代码托管于 GitHub。

Arnau Quera-Bofarull, Joel Dyer, Anisoara Calinescu, J. Doyne Farmer, and Michael Wooldridge. BlackBIRDS：可微模拟器的黑盒推理. 开源软件期刊，8(89), 5776, 2023.

代码托管于 GitHub。

Utkarsh Singhal, Carlos Esteves, Ameesh Makadia, and Stella X. Yu. 学习变换以实现可泛化的实例级不变性. IEEE/CVF 国际计算机视觉会议论文集 (ICCV)，pp. 6211-6221, 2023.

代码托管于 GitHub。

Ba-Hien Tran, Giulio Franzese, Pietro Michiardi, and Maurizio Filippone. 一行代码的数据平滑改进基于似然的生成模型优化. 神经信息处理系统进展第 36 卷，pp. 6545–6567, 2023.

代码托管于 GitHub。

此外，boltzgen 包也是基于 normflows 构建的。

引用

如果您使用了 normflows，请按照以下方式引用相关论文。

Stimper 等人，(2023)。normflows：一个用于归一化流（Normalizing Flows）的 PyTorch 包。开源软件期刊，8(86), 5361, https://doi.org/10.21105/joss.05361

BibTeX

@article{Stimper2023, 
  author = {Vincent Stimper and David Liu and Andrew Campbell and Vincent Berenz and Lukas Ryll and Bernhard Schölkopf and José Miguel Hernández-Lobato}, 
  title = {normflows: A PyTorch Package for Normalizing Flows}, 
  journal = {Journal of Open Source Software}, 
  volume = {8},
  number = {86}, 
  pages = {5361}, 
  publisher = {The Open Journal}, 
  doi = {10.21105/joss.05361}, 
  url = {https://doi.org/10.21105/joss.05361}, 
  year = {2023}
} 

normflows 快速上手指南

normflows 是一个基于 PyTorch 实现的离散归一化流（Normalizing Flows）包。它支持多种流行的流架构，适用于概率建模、生成模型等任务。

环境准备

• Python 版本: 至少需要 Python 3.7。
• 深度学习框架: 需预先安装 PyTorch。如需使用 GPU 加速，请确保按照 PyTorch 官网 正确配置 CUDA 环境。
• 依赖库: 基础功能仅需 normflows，运行示例 notebook 需额外安装示例依赖。

安装步骤

通过 pip 安装最新版本：

pip install normflows

若需运行官方提供的示例 Notebook，请先克隆仓库并安装示例依赖：

git clone https://github.com/VincentStimper/normalizing-flows.git
cd normalizing-flows
pip install -r requirements_examples.txt

基本使用

以下示例展示如何构建一个基于 Real NVP 模型的归一化流，用于拟合 2D 分布。

1. 导入库与定义基础分布

import normflows as nf

# 定义 2D 高斯基础分布
base = nf.distributions.base.DiagGaussian(2)

2. 定义流层序列

num_layers = 32
flows = []
for i in range(num_layers):
    # 创建神经网络参数映射（两层隐藏层，每层 64 单元）
    param_map = nf.nets.MLP([1, 64, 64, 2], init_zeros=True)
    # 添加仿射耦合层
    flows.append(nf.flows.AffineCouplingBlock(param_map))
    # 交换维度
    flows.append(nf.flows.Permute(2, mode='swap'))

3. 构建模型与训练

# 初始化模型（可选传入目标分布密度）
target = nf.distributions.target.TwoMoons()
model = nf.NormalizingFlow(base, flows, target)

# 计算损失函数
# 无目标分布时使用前向 KL 散度
# loss = model.forward_kld(x)

# 有目标分布时反向 KL 散度
loss = model.reverse_kld(num_samples=512)

# 执行优化
loss.backward()
optimizer.step()

更多详细用法及高级示例（如 Glow, VAE, Residual Flow），请参考 官方文档 或 GitHub Examples。