geoopt

|Python Package Index| |Read The Docs| |Build Status| |Coverage Status| |Codestyle Black| |Gitter|

流形感知的 pytorch.optim。

非官方实现，用于 “黎曼自适应优化方法”_ ICLR2019 及更多内容。

安装

请确保已安装 pytorch>=2.0.1。

有两种方式可以安装 geoopt：

1. GitHub（目前推荐），因为开发仍在积极进行中。

.. code-block:: bash

pip install git+https://github.com/geoopt/geoopt.git

2. pypi（这可能会显著落后于主分支，但会尽可能保持最新）。

.. code-block:: bash

pip install geoopt

一旦项目达到稳定阶段，推荐的安装方式将会改变。目前，由于我们正在积极开发并实现新功能，pypi 版本仍落后于主分支。

PyTorch 支持

Geoopt 官方支持 **PyTorch 最新两个稳定版本** 或最新的主要发布版。

目前已完成的工作
-------------------

工作仍在进行中，但您已经可以使用它了。请注意，API 在未来的版本中可能会发生变化。

张量
~~~~~~~

-  ``geoopt.ManifoldTensor`` - 类似于 torch.Tensor，但增加了 ``manifold`` 关键字参数。
-  ``geoopt.ManifoldParameter`` - 同上，在 ``torch.nn.Module.parameters`` 中被正确识别为子类。

以上所有容器都具有特殊方法，可用于将其作为特定流形上的点进行操作：

-  ``.proj_()`` - 将点就地投影到流形上。
-  ``.proju(u)`` - 将向量 ``u`` 投影到切空间。在使用以下所有方法之前，都需要先对向量进行投影。
-  ``.egrad2rgrad(u)`` - 将梯度 ``u`` 投影到黎曼流形上。
-  ``.inner(u, v=None)`` - 在该点计算两个 **切向量** 的内积。传入的向量无需再投影，假设它们已经处于切空间中。
-  ``.retr(u)`` - 根据向量 ``u`` 进行缩映射。
-  ``.expmap(u)`` - 根据向量 ``u`` 进行指数映射（如果无法以闭式表达，则使用最佳近似值）。
-  ``.transp(v, u)`` - 沿方向 ``u`` 平行移动向量 ``v``。
-  ``.retr_transp(v, u)`` - 沿方向 ``u`` 平行移动 ``self`` 和向量 ``v``（以及可能的其他向量）（返回结果为普通张量）。

流形
~~~~~~~~~

-  ``geoopt.Euclidean`` - 带有欧几里得度量的无约束实数空间流形。
-  ``geoopt.Stiefel`` - 矩阵 Stiefel 流形，满足 ``A in R^{n x p} : A^t A=I``, ``n >= p``。
-  ``geoopt.Sphere`` - 单位球面流形 ``||x||=1``。
-  ``geoopt.BirkhoffPolytope`` - 双随机矩阵流形。
-  ``geoopt.Stereographic`` - 常曲率立体投影模型。
-  ``geoopt.SphereProjection`` - 球面立体投影模型。
-  ``geoopt.PoincareBall`` -  `庞加莱圆盘模型 <https://en.wikipedia.org/wiki/Poincar%C3%A9_disk_model>`_。
-  ``geoopt.Lorentz`` -  `双曲面模型 <https://en.wikipedia.org/wiki/Hyperboloid_model>`_。
-  ``geoopt.ProductManifold`` - 流形乘积构造器。
-  ``geoopt.Scaled`` - 流形的缩放版本。与 ``ProductManifold`` 结合时，类似于 `学习乘积空间中的混合曲率表示 <https://openreview.net/forum?id=HJxeWnCcF7>`_。
-  ``geoopt.SymmetricPositiveDefinite`` - 对称正定矩阵流形。
-  ``geoopt.UpperHalf`` - 西格尔上半平面流形。支持黎曼和芬斯勒度量，如 `图嵌入的对称空间：一种芬斯勒-黎曼方法 <https://arxiv.org/abs/2106.04941>`_ 所述。
-  ``geoopt.BoundedDomain`` - 西格尔有界域流形。支持黎曼和芬斯勒度量。

所有流形都实现了在流形上操作张量以及处理切向量所需的方法，以便在通用场景中使用。更多信息请参阅 `文档`_。

优化器
~~~~~~~~~~

-  ``geoopt.optim.RiemannianSGD`` - 是 ``torch.optim.SGD`` 的子类，具有相同的 API。
-  ``geoopt.optim.RiemannianAdam`` - 是 ``torch.optim.Adam`` 的子类。

采样器
~~~~~~~~

-  ``geoopt.samplers.RSGLD`` - 黎曼随机梯度朗之万动力学。
-  ``geoopt.samplers.RHMC`` - 黎曼哈密顿蒙特卡洛。
-  ``geoopt.samplers.SGRHMC`` - 随机梯度黎曼哈密顿蒙特卡洛。


层
~~~~~~
实验性的 ``geoopt.layers`` 模块允许将 geoopt 嵌入到深度学习中。

引用 Geoopt
~~~~~~~~~~~~~
如果您在研究中发现该项目有用，请在参考文献中添加以下 BibTeX 条目并予以引用。

.. code:: bibtex

    @misc{geoopt2020kochurov,
        title={Geoopt: PyTorch 中的黎曼优化},
        author={Max Kochurov、Rasul Karimov 和 Serge Kozlukov},
        year={2020},
        eprint={2005.02819},
        archivePrefix={arXiv},
        primaryClass={cs.CG}
    }

捐赠
~~~~~~~~~
ETH: 0x008319973D4017414FdF5B3beF1369bA78275C6A
   

.. _“黎曼自适应优化方法”: https://openreview.net/forum?id=r1eiqi09K7
.. _文档: https://geoopt.readthedocs.io/en/latest/manifolds.html


.. |Python Package Index| image:: https://img.shields.io/pypi/v/geoopt.svg
   :target: https://pypi.python.org/pypi/geoopt
.. |Read The Docs| image:: https://readthedocs.org/projects/geoopt/badge/?version=latest
   :target: https://geoopt.readthedocs.io/en/latest/?badge=latest
   :alt: 文档状态
.. |Build Status| image:: https://github.com/geoopt/geoopt/actions/workflows/testing.yml/badge.svg?branch=master
   :target: https://github.com/geoopt/geoopt/actions/workflows/testing.yml
.. |Coverage Status| image:: https://codecov.io/gh/geoopt/geoopt/branch/master/graph/badge.svg?token=HOI5LD0VWF
   :target: https://codecov.io/gh/geoopt/geoopt
.. |Codestyle Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
   :target: https://github.com/ambv/black
.. |Gitter| image:: https://badges.gitter.im/geoopt/community.png
   :target: https://gitter.im/geoopt/community

Geoopt 快速上手指南

Geoopt 是一个基于 PyTorch 的黎曼优化（Riemannian Optimization）库，支持在多种流形（如球面、双曲空间、Stiefel 流形等）上进行梯度下降和自适应优化。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：建议 Python 3.8+
• 核心依赖：
  • PyTorch >= 2.0.1（官方支持最新的两个稳定版本或最新主版本）
• 可选依赖：无特殊要求，标准科学计算环境即可

安装步骤

由于该项目处于活跃开发阶段，推荐直接从 GitHub 安装以获取最新功能。

方式一：从 GitHub 安装（推荐）

pip install git+https://github.com/geoopt/geoopt.git

国内用户若下载缓慢，可尝试配置 pip 使用国内镜像源加速克隆过程，或直接使用方式二（注意版本可能滞后）。

方式二：从 PyPI 安装

pip install geoopt

基本使用

以下示例展示如何在单位球面（Sphere Manifold）上创建一个参数，并使用黎曼 SGD 优化器进行更新。

1. 导入库与定义流形

import torch
import geoopt

# 定义球面流形
manifold = geoopt.Sphere()

# 创建一个位于流形上的随机参数 (维度为 3)
# 初始化后会自动投影到流形上
param = geoopt.ManifoldParameter(torch.randn(3), manifold=manifold)

# 验证参数是否在流形上 (范数应接近 1)
print(f"Norm: {param.norm().item():.6f}") 

2. 定义优化器与训练循环

# 定义简单的损失函数：最小化参数与目标向量 [1, 0, 0] 的距离
target = torch.tensor([1.0, 0.0, 0.0])

# 创建黎曼 SGD 优化器
optimizer = geoopt.optim.RiemannianSGD([param], lr=0.01)

# 模拟几步优化过程
for step in range(100):
    optimizer.zero_grad()
    
    # 计算欧几里得梯度
    loss = (param - target).pow(2).sum()
    loss.backward()
    
    # 执行黎曼更新步 (自动处理投影和切空间运算)
    optimizer.step()
    
    if (step + 1) % 20 == 0:
        print(f"Step {step+1}, Loss: {loss.item():.6f}, Norm: {param.norm().item():.6f}")

核心概念简述

• ManifoldTensor / ManifoldParameter: 带有流形属性的张量，自动管理投影。
• 常用流形: geoopt.Euclidean, geoopt.Stiefel, geoopt.PoincareBall, geoopt.Lorentz 等。
• 优化器: geoopt.optim.RiemannianSGD, geoopt.optim.RiemannianAdam，API 与原生 PyTorch 完全兼容。