GeoTorch

|Build| |Docs| |Codecov| |Codestyle Black| |License|

一个用于在 PyTorch 中进行约束优化和流形优化（manifold optimization）的深度学习库

概述

GeoTorch 提供了一种简单的方法，可以在 PyTorch 中执行约束优化和流形优化。
它开箱即用，兼容任何在 PyTorch 中实现的优化器、层和模型，无需在训练代码中添加任何样板代码。只需在构建模型时声明约束条件，就可以直接开始使用！

.. code:: python

import torch
import torch.nn as nn
import geotorch

class Model(nn.Module):
    def __init__(self):
        super().__init__()
        # 只需一行代码：实例化一个具有正交列的线性层
        self.linear = nn.Linear(64, 128)
        geotorch.orthogonal(self.linear, "weight")

        # 支持张量：实例化一个秩为 1 的卷积核 CNN
        self.cnn = nn.Conv2d(16, 32, 3)
        geotorch.low_rank(self.cnn, "weight", rank=1)

        # 在施加约束时，权重会被初始化为随机值，
        # 但您可以通过赋值重新初始化它们
        self.linear.weight = torch.eye(128, 64)
        # 就是这么简单。剩下的就是常规的 PyTorch 代码了

    def forward(self, x):
        # self.linear 是正交的，self.cnn 中每个 3x3 卷积核的秩为 1

# 像平常一样使用模型。一切都正常工作
model = Model().cuda()

# 使用您选择的优化器。任何优化器都可以与任何参数化方法无缝协作
optim = torch.optim.Adam(model.parameters(), lr=lr)

约束条件

以下约束条件已实现，并可像上面的示例一样使用：

• |symmetric|_. 对称矩阵
• |skew_constr|_. 反对称矩阵
• |sphere_constr|_. 范数为 1 的向量
• |orthogonal|_. 具有正交列的矩阵
• |grassmannian|_. 反对称矩阵
• |almost_orthogonal|_. 奇异值位于区间 [1-λ, 1+λ] 的矩阵
• |invertible|_. 行列式为正的可逆矩阵
• |sln|_. 行列式等于 1 的矩阵
• |low_rank|_. 秩至多为 r 的矩阵
• |fixed_rank|_. 秩为 r 的矩阵
• |positive_definite|_. 正定矩阵
• |positive_semidefinite|_. 半正定矩阵
• |positive_semidefinite_low_rank|_. 秩至多为 r 的半正定矩阵
• |positive_semidefinite_fixed_rank|_. 秩为 r 的半正定矩阵

.. |symmetric| replace:: geotorch.symmetric .. _symmetric: https://geotorch.readthedocs.io/en/latest/constraints.html#geotorch.symmetric .. |skew_constr| replace:: geotorch.skew .. _skew_constr: https://geotorch.readthedocs.io/en/latest/constraints.html#geotorch.skew .. |sphere_constr| replace:: geotorch.sphere .. _sphere_constr: https://geotorch.readthedocs.io/en/latest/constraints.html#geotorch.sphere .. |orthogonal| replace:: geotorch.orthogonal .. _orthogonal: https://geotorch.readthedocs.io/en/latest/constraints.html#geotorch.orthogonal .. |grassmannian| replace:: geotorch.grassmannian .. _grassmannian: https://geotorch.readthedocs.io/en/latest/constraints.html#geotorch.grassmannian .. |almost_orthogonal| replace:: geotorch.almost_orthogonal(λ) .. _almost_orthogonal: https://geotorch.readthedocs.io/en/latest/constraints.html#geotorch.almost_orthogonal .. |invertible| replace:: geotorch.invertible .. _invertible: https://geotorch.readthedocs.io/en/latest/constraints.html#geotorch.invertible .. |sln| replace:: geotorch.sln .. _sln: https://geotorch.readthedocs.io/en/latest/constraints.html#geotorch.sln .. |low_rank| replace:: geotorch.low_rank(r) .. _low_rank: https://geotorch.readthedocs.io/en/latest/constraints.html#geotorch.low_rank .. |fixed_rank| replace:: geotorch.fixed_rank(r) .. _fixed_rank: https://geotorch.readthedocs.io/en/latest/constraints.html#geotorch.fixed_rank .. |positive_definite| replace:: geotorch.positive_definite .. _positive_definite: https://geotorch.readthedocs.io/en/latest/constraints.html#geotorch.positive_definite .. |positive_semidefinite| replace:: geotorch.positive_semidefinite .. _positive_semidefinite: https://geotorch.readthedocs.io/en/latest/constraints.html#geotorch.positive_semidefinite .. |positive_semidefinite_low_rank| replace:: geotorch.positive_semidefinite_low_rank(r) .. _positive_semidefinite_low_rank: https://geotorch.readthedocs.io/en/latest/constraints.html#geotorch.positive_semidefinite_low_rank .. |positive_semidefinite_fixed_rank| replace:: geotorch.positive_semidefinite_fixed_rank(r) .. _positive_semidefinite_fixed_rank: https://geotorch.readthedocs.io/en/latest/constraints.html#geotorch.positive_semidefinite_fixed_rank

这些约束条件都有额外的参数，可以用来根据具体问题调整行为。更多内容请参阅文档。

这些约束条件是以下列出的空间族的前端实现。

支持的空间

GeoTorch 中的每个约束条件都实现为一个流形（manifold）。这为用户提供了更大的灵活性，可以选择每种参数化的选项。所有这些空间都支持黎曼梯度下降法（Riemannian Gradient Descent，更多信息请参见 这里_），但也支持通过任何其他 PyTorch 优化器进行优化。

GeoTorch 当前支持以下空间：

• |reals|_: Rⁿ. 无限制优化
• |sym|_: 对称矩阵的向量空间
• |skew|_: 反对称矩阵的向量空间
• |sphere|_: Rⁿ 中的球面。{ x ∈ Rⁿ | ||x|| = 1 } ⊂ Rⁿ
• |so|_: n×n 正交矩阵的流形
• |st|_: 具有正交列的 n×k 矩阵的流形
• |almost|_: 奇异值位于区间 [1-λ, 1+λ] 的 n×k 矩阵的流形
• |grass|_: Rⁿ 中 k 维子空间的流形
• |glp|_: 行列式为正的可逆 n×n 矩阵的流形
• |sl|_: 行列式等于 1 的 n×n 矩阵的流形
• |low|_: 秩为 r 或更小的 n×k 矩阵的簇
• |fixed|_: 秩为 r 的 n×k 矩阵的流形
• |psd|_: n×n 对称正定矩阵的锥体
• |pssd|_: n×n 对称半正定矩阵的锥体
• |pssdlow|_: 秩为 r 或更小的 n×n 对称半正定矩阵的簇
• |pssdfixed|_: 秩为 r 的 n×n 对称半正定矩阵的流形
• |product|_: 流形的乘积 M₁ × ... × Mₖ

每个维度为 (n, k) 的空间都可以应用于形状为 (*, n, k) 的张量，因此我们还可以高效地实现并行化的乘积空间，例如：

• ObliqueManifold(n,k): 具有单位长度列的矩阵，Sⁿ⁻¹ × ...ᵏ⁾ × Sⁿ⁻¹

在您的代码中使用 GeoTorch

examples/copying_problem.py_ 和 examples/sequential_mnist.py_ 文件作为教程，展示了如何在实际代码中处理 GeoTorch（几何优化工具包）的初始化和使用。它们还展示了如何实现黎曼梯度下降（Riemannian Gradient Descent）以及一些其他技巧。如果想了解该库的实际实现方式，请参阅 Jupyter Notebook 文件 examples/parametrisations.ipynb_。

你可以通过以下方式安装 GeoTorch：

.. code:: bash

pip install git+https://github.com/Lezcano/geotorch/

GeoTorch 在 Linux、Mac 和 Windows 环境下经过测试，支持 Python >= 3.6，并兼容 PyTorch >= 1.9。

共享权重、参数化与归一化流

如果希望在模型的不同地方使用一个参数化的张量，或者多次使用某个参数化的层（例如在 RNN 中），建议如下包装前向传播过程，以避免每个参数化被重复计算多次：

.. code:: python

with geotorch.parametrize.cached():
    logits = model(input_)

当然，这个 with 语句也可以简单地用在前向函数中，特别是当参数化层被多次使用时。

这些思想属于参数化优化（parametrized optimization）的范畴，其中将一个张量 X 包装在一个函数 f 中，而不是直接使用 X，而是使用 f(X)。这种思想的具体例子包括剪枝（pruning）、权重归一化（weight normalization）和谱归一化（spectral normalization）等。本仓库实现了一个框架来解决这类问题。该框架已被纳入 PyTorch 1.8 核心功能，可以在 torch.nn.utils.parametrize_ 和 torch.nn.utils.parametrizations_ 下找到。当使用 PyTorch 1.10 或更高版本时，GeoTorch 内部会使用原生的 PyTorch 函数。在这种情况下，用户可以使用 PyTorch 函数与 GeoTorch 中的参数化进行交互。

由于 GeoTorch 中的每个空间本质上都是从平坦空间到流形的映射，因此这里实现的工具也可作为归一化流（normalizing flows）的构建模块。例如，使用像 |low|_ 这样的分解空间，可以直接计算其定义的变换的行列式，因为我们能够直接访问层的奇异值。

.. |reals| replace:: Rn(n) .. _reals: https://geotorch.readthedocs.io/en/latest/vector_spaces/reals.html .. |sym| replace:: Sym(n) .. _sym: https://geotorch.readthedocs.io/en/latest/vector_spaces/symmetric.html .. |skew| replace:: Skew(n) .. _skew: https://geotorch.readthedocs.io/en/latest/vector_spaces/skew.html .. |sphere| replace:: Sphere(n) .. _sphere: https://geotorch.readthedocs.io/en/latest/orthogonal/sphere.html .. |so| replace:: SO(n) .. _so: https://geotorch.readthedocs.io/en/latest/orthogonal/so.html .. |st| replace:: St(n,k) .. _st: https://geotorch.readthedocs.io/en/latest/orthogonal/stiefel.html .. |almost| replace:: AlmostOrthogonal(n,k,λ) .. _almost: https://geotorch.readthedocs.io/en/latest/orthogonal/almostorthogonal.html .. |grass| replace:: Gr(n,k) .. _grass: https://geotorch.readthedocs.io/en/latest/orthogonal/grassmannian.html .. |glp| replace:: GLp(n) .. _glp: https://geotorch.readthedocs.io/en/latest/invertibility/glp.html .. |sl| replace:: SL(n) .. _sl: https://geotorch.readthedocs.io/en/latest/invertibility/sl.html .. |low| replace:: LowRank(n,k,r) .. _low: https://geotorch.readthedocs.io/en/latest/lowrank/lowrank.html .. |fixed| replace:: FixedRank(n,k,r) .. _fixed: https://geotorch.readthedocs.io/en/latest/lowrank/fixedrank.html .. |psd| replace:: PSD(n) .. _psd: https://geotorch.readthedocs.io/en/latest/psd/psd.html .. |pssd| replace:: PSSD(n) .. _pssd: https://geotorch.readthedocs.io/en/latest/psd/pssd.html .. |pssdlow| replace:: PSSDLowRank(n,r) .. _pssdlow: https://geotorch.readthedocs.io/en/latest/psd/pssdlowrank.html .. |pssdfixed| replace:: PSSDFixedRank(n,r) .. _pssdfixed: https://geotorch.readthedocs.io/en/latest/psd/pssdfixedrank.html .. |product| replace:: ProductManifold(M₁, ..., Mₖ) .. _product: https://geotorch.readthedocs.io/en/latest/product.html

参考文献

如果你发现 GeoTorch 有用，请引用以下工作。这篇论文提供了一个简化的数学解释，部分揭示了 GeoTorch 的内部工作机制。

.. code:: bibtex

@inproceedings{lezcano2019trivializations,
    title = {Trivializations for gradient-based optimization on manifolds},
    author = {Lezcano-Casado, Mario},
    booktitle={Advances in Neural Information Processing Systems, NeurIPS},
    pages = {9154--9164},
    year = {2019},
}

.. |Build| image:: https://github.com/lezcano/geotorch/workflows/Build/badge.svg :target: https://github.com/lezcano/geotorch/workflows/Build/badge.svg :alt: Build .. |Docs| image:: https://readthedocs.org/projects/geotorch/badge/?version=latest :target: https://geotorch.readthedocs.io/en/latest/?badge=latest :alt: 文档 .. |Codecov| image:: https://codecov.io/gh/Lezcano/geotorch/branch/master/graph/badge.svg?token=1AKM2EQ7RT :target: https://codecov.io/gh/Lezcano/geotorch/branch/master/graph/badge.svg?token=1AKM2EQ7RT :alt: 代码覆盖率 .. |Codestyle Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/ambv/black :alt: 黑色代码风格 .. |License| image:: https://img.shields.io/badge/license-MIT-green.svg :target: https://github.com/Lezcano/geotorch/blob/master/LICENSE :alt: 许可证

.. _here: https://github.com/Lezcano/geotorch/blob/master/examples/copying_problem.py#L16 .. _torch.nn.utils.parametrize: https://pytorch.org/docs/stable/generated/torch.nn.utils.parametrize.register_parametrization.html .. _torch.nn.utils.parametrizations: https://pytorch.org/docs/stable/generated/torch.nn.utils.parametrizations.orthogonal.html .. _geotorch/parametrize.py: https://github.com/Lezcano/geotorch/blob/master/geotorch/parametrize.py .. _examples/sequential_mnist.py: https://github.com/Lezcano/geotorch/blob/master/examples/sequential_mnist.py .. _examples/copying_problem.py: https://github.com/Lezcano/geotorch/blob/master/examples/copying_problem.py .. _examples/parametrisations.ipynb: https://github.com/Lezcano/geotorch/blob/master/examples/parametrisations.ipynb

GeoTorch 快速上手指南

GeoTorch 是一个用于 PyTorch 的约束优化和流形优化库，支持在深度学习模型中轻松实现各种约束。

---

环境准备

系统要求

• 操作系统：Linux、Mac 或 Windows
• Python 版本：>= 3.6
• PyTorch 版本：>= 1.9

前置依赖

确保已安装以下依赖：

• PyTorch（推荐使用最新稳定版本）
• Git（用于从源码安装）

---

安装步骤

通过以下命令安装 GeoTorch：

pip install git+https://github.com/Lezcano/geotorch/

如果需要加速安装，可以尝试使用国内镜像源（如阿里云）：

pip install git+https://github.com/Lezcano/geotorch/ -i https://mirrors.aliyun.com/pypi/simple

---

基本使用

以下是一个简单的示例，展示如何在模型中使用 GeoTorch 添加约束：

import torch
import torch.nn as nn
import geotorch

class Model(nn.Module):
    def __init__(self):
        super().__init__()
        # 创建一个具有正交列的线性层
        self.linear = nn.Linear(64, 128)
        geotorch.orthogonal(self.linear, "weight")

        # 创建一个秩为 1 的卷积层
        self.cnn = nn.Conv2d(16, 32, 3)
        geotorch.low_rank(self.cnn, "weight", rank=1)

        # 可以重新初始化权重
        self.linear.weight = torch.eye(128, 64)

    def forward(self, x):
        # self.linear 是正交的，self.cnn 的每个 3x3 核是秩为 1 的
        return self.linear(x)

# 实例化模型并移动到 GPU
model = Model().cuda()

# 使用任意优化器，无需额外配置
optim = torch.optim.Adam(model.parameters(), lr=0.001)

---

以上代码展示了如何在模型中添加正交性和低秩约束，并正常训练模型。更多约束类型和高级用法，请参考 官方文档。