NeuroMANCER v1.5.6

具有自适应非线性约束和高效正则化的神经模块（NeuroMANCER） 是一个开源的可微分编程（DP）库，用于求解参数化约束优化问题、基于物理信息的系统辨识以及基于模型的参数化最优控制。NeuroMANCER 使用 PyTorch 编写，允许将机器学习与科学计算系统性地结合，从而创建端到端的可微模型和算法，并在其中嵌入先验知识和物理规律。

---

目录

1. 概述
2. 关键特性
3. v1.5.3 新增内容
4. 安装
5. 快速入门
6. 教程
7. 文档与用户指南

---

关键特性

• 学习建模、学习控制、学习优化：我们的库旨在为最终用户提供多种工具，以解决学习优化（L2O）、学习建模（L2M）和学习控制（L2C）任务。您可以处理高级的约束参数化优化问题，使用基于物理信息的神经网络来建模流体动力学，或者学习如何控制建筑物内的室内温度以最大化建筑能效。
• 符号编程 接口使得在这些学习范式中定义和嵌入物理方程、领域知识和约束变得非常简单。
• 全面的学习工具：提供丰富的教程和示例应用——从基础的系统辨识到高级的预测控制——使用户能够轻松学习并将 NeuroMANCER 应用于实际问题。
• 最先进方法：NeuroMANCER 汇集了当前最先进的方法，例如用于函数逼近的函数编码器（FE）和科尔莫戈洛夫-阿诺德网络（KAN），用于学习动态系统的神经常微分方程（NODE）、神经库普曼算子（KO）以及稀疏非线性动力学识别（SINDy），用于学习优化中的安全约束的可微凸优化层，以及用于学习控制非线性系统的可微预测控制（DPC）。
• NeuroMANCER-GPT 助手：我们提供了易于使用的脚本，可以将 NeuroMANCER 库的内容转换为适合 RAG 基础“LLM 助手”管道的形式。请参阅 Assistant 以了解如何快速搭建一个 LLM 模型来帮助理解和编写 NeuroMANCER 代码。

v1.5.6 新增内容

新示例：

• 通过算子分裂法实现的神经 DAE
• 针对热力系统的混合整数 DPC
• 面向电网响应的建筑能源系统的 DPC
• 具有预览时域的 DPC

新功能

• 新类 SystemPreview，可作为 System 类的直接替代品，启用预览时域功能
• 单元测试已更新至最新版本。

修复的错误

• 修复了 mlflow 依赖项在 Google Colab 中引发冲突的问题

安装

只需运行

pip install neuromancer

如需手动安装，请参阅 安装说明

快速入门

在 examples 文件夹和下方的 教程 中，您可以找到大量教程。示例的交互式笔记本版本可在 Google Colab 上获取！在克隆仓库并搭建环境之前，不妨先试用一下 NeuroMANCER 的功能。

以下笔记本介绍了 NeuroMANCER 库的核心抽象概念，尤其是我们的符号编程接口和 Node 类。

符号变量、节点、约束、目标函数和系统类

• 第 1 部分：PyTorch 与 NeuroMANCER 中的线性回归。

• 第 2 部分：NeuroMANCER 语法教程——变量、约束和目标函数。

• 第 3 部分：NeuroMANCER 语法教程——模块、Node 和 System 类。

示例

使用 NeuroMANCER 解决参数化约束优化问题的快速示例，利用我们的符号编程接口、Node 和 Variable、Blocks、SLiM 库以及 PenaltyLoss 类。

# Neuromancer 语法示例：约束优化
import neuromancer as nm
import torch 

# 定义神经网络架构 
func = nm.modules.blocks.MLP(insize=1, outsize=2, 
                             linear_map=nm.slim.maps['linear'], 
                             nonlin=torch.nn.ReLU, hsizes=[80] * 4)
# 将神经网络通过 Node 类包装成符号表示：map(p) -> x
map = nm.system.Node(func, ['p'], ['x'], name='map')
    
# 定义决策变量
x = nm.constraint.variable("x")[:, [0]]
y = nm.constraint.variable("x")[:, [1]]

# 数据集中采样的问题参数
p = nm.constraint.variable('p')

# 定义目标函数
f = (1-x)**2 + (y-x**2)**2
obj = f.minimize(weight=1.0)

# 定义约束条件
con_1 = 100.*(x >= y)
con_2 = 100.*(x**2+y**2 <= p**2)

# 创建基于惩罚法的损失函数
loss = nm.loss.PenaltyLoss(objectives=[obj], constraints=[con_1, con_2])
# 构造可微分的约束优化问题
problem = nm.problem.Problem(nodes=[map], loss=loss)

领域示例

NeuroMANCER 旨在利用其丰富的算法来解决各种领域特定的建模和控制问题。以下展示了如何对建筑能源系统进行建模与控制，以及应用负荷预测技术。

如需深入了解我们的方法，请参阅下方的建模、优化与控制方法教程部分。

能源系统

• 使用神经ODE学习建筑热动力学
• 基于神经ODE的多区域建筑热动力学电阻-电容网络模型
• 使用神经ODE学习同步发电机摆动方程动力学
• 学习控制建筑物室内空气温度
• 基于MLP和CNN模型的建筑能耗负荷预测
• 基于Transformer模型的建筑能耗负荷预测
• 学习控制抽水蓄能水电系统
• 使用安全强化学习和DPC控制建筑暖通空调系统

• 建筑能源系统的电网响应型DPC

建模、优化与控制方法教程

学习优化（L2O）用于参数化编程

Neuromancer 允许您构建并求解广泛的参数化优化问题，借助机器学习来学习这些问题的解。关于参数化编程的更多信息

• 学习求解一个带约束的优化问题。

• 学习求解一个二次约束优化问题。

• 学习求解一组二维约束优化问题。

• 学习使用投影梯度法求解约束优化问题。

• 使用CvxpyLayers实现到多面体可行域的可微投影。

• 学习通过度量学习优化算子分裂层。

通过可微预测控制（DPC）学习控制（L2C）

Neuromancer 使您能够为全范围的可微白箱、灰箱和黑箱动力系统学习控制策略，同时满足选择约束和目标函数的要求。 关于可微预测控制的更多信息

• 学习如何稳定一个线性动力系统。
• 学习如何稳定一个非线性微分方程。
• 学习如何控制一个非线性微分方程。
• 学习未知动力系统的神经ODE模型及控制策略。
• 学习非线性动力系统的神经李雅普诺夫函数。

• 混合整数DPC

函数逼近

Neuromancer 紧跟最前沿的方法。在这里，我们展示了强大的科尔莫戈洛夫-阿诺德网络 关于科尔莫戈洛夫-阿诺德网络的更多信息

• 对比KANs与FBKANs在学习带噪声的1D多尺度函数时的表现
• 对比KANs与FBKANs在学习带噪声的2D多尺度函数时的表现

Neuromancer 包含函数编码器的实现，这是一种将基函数学习为神经网络的算法。请参阅 函数编码器：希尔伯特空间中迁移学习的一种原则性方法。

• 函数编码器简介

系统辨识

Neuromancer 允许用户结合机器学习、先验物理知识和领域专业知识，在已知系统行为观测数据的基础上，构建动力学系统的数据驱动模型。 关于通过神经状态空间模型和常微分方程进行系统辨识的更多信息

• 神经普通微分方程 (NODEs)
• 常微分方程系统的参数估计
• 通用微分方程 (UDEs)
• 带有外生输入的 NODEs
• 带有外生输入的神经状态空间模型 (NSSMs)
• 电阻-电容 (RC) 网络 ODE 的数据驱动建模
• 深度库普曼算子
• 面向控制的深度库普曼算子
• 非线性动力学稀疏识别 (SINDy)

• 函数编码器 + 神经普通微分方程

• 通过算子分裂法实现的神经微分代数方程 (DAEs)

物理信息神经网络 (PINNs)

Neuromancer 的符号编程设计非常适合求解 PINNs。关于 PINNs 的更多信息

• 扩散方程
• 伯格斯方程
• 带参数估计的伯格斯方程（反问题）
• 拉普拉斯方程（稳态）
• 通过堆叠 PINN 实现阻尼摆
• 纳维-斯托克斯方程（盖驱动腔流，稳态，KAN）

随机微分方程 (SDEs)

Neuromancer 已与 TorchSDE 集成，以处理随机动力学系统。关于 SDEs 的更多信息

• 隐式 SDE：使用 Neuromancer x TorchSDE 对随机过程进行“系统辨识”

可扩展性和可定制性

PyTorch Lightning 集成

我们集成了 PyTorch Lightning，以简化代码、实现自定义训练逻辑、支持 GPU 和多 GPU 配置，并处理大规模、内存密集型的学习任务。

• Lightning 集成基础教程。
• Lightning 高级功能与自动 GPU 支持。
• 通过 Lightning 模块化代码定义自定义训练逻辑。

文档与用户指南

该库的文档可在 在线 查阅。 此外，还有一段 介绍视频，涵盖了该库的核心功能。

如需更多信息，包括面向开发人员的内容，请访问我们的 开发者与用户指南。

社区信息

我们欢迎开源社区的贡献和反馈！

贡献、讨论与问题

请阅读 社区开发指南，以获取有关贡献、讨论 和 问题 的更多信息。

发布说明

请参阅 发布说明，其中记录了新功能。

许可证

NeuroMANCER 采用 BSD 许可证。 更多详情请参阅 许可证。

出版物

• Ashish S. Nair, Bruno Jacob, Amanda A. Howard, Jan Drgona, Panos Stinis, E-PINNs：认知不确定性物理信息神经网络，arXiv:2503.19333
• Bo Tang, Elias B. Khalil, Ján Drgoňa, 学习求解混合整数非线性规划的优化方法，arXiv:2410.11061，2024年
• John Viljoen, Wenceslao Shaw Cortez, Jan Drgona, Sebastian East, Masayoshi Tomizuka, Draguna Vrabie, 面向机器人技术的可微预测控制：一种数据驱动的预测安全滤波器方法，arXiv:2409.13817，2024年
• Jan Drgona, Aaron Tuor, Draguna Vrabie, 带有保证的学习受限参数化可微预测控制策略，IEEE系统、人机与控制论汇刊：系统，2024年
• Renukanandan Tumu, Wenceslao Shaw Cortez, Ján Drgoňa, Draguna L. Vrabie, Sonja Glavaski, 面向大规模城市道路网络的可微预测控制，arXiv:2406.10433，2024年
• Ethan King, James Kotary, Ferdinando Fioretto, Jan Drgona, 用于加速可微参数化规划中算子分裂法收敛的度量学习，arXiv:2404.00882，2024年
• James Koch, Madelyn Shapiro, Himanshu Sharma, Draguna Vrabie, Jan Drgona, 神经微分代数方程，arXiv:2403.12938，2024年
• Wenceslao Shaw Cortez, Jan Drgona, Draguna Vrabie, Mahantesh Halappanavar, 一种鲁棒高效的预测安全滤波器，arXiv:2311.08496，2024年
• Shrirang Abhyankar, Jan Drgona, Andrew August, Elliott Skomski, Aaron Tuor, 利用可微参数化优化进行神经—物理动态负荷建模，2023 IEEE电力与能源学会年会（PESGM）
• James Koch，Zhao Chen，Aaron Tuor，Jan Drgona，Draguna Vrabie，使用通用微分方程对网络化动力系统进行结构推断，arXiv:2207.04962，2022年
• Ján Drgoňa，Sayak Mukherjee，Aaron Tuor，Mahantesh Halappanavar，Draguna Vrabie，学习随机参数化可微预测控制策略，IFAC ROCOND会议（2022年）
• Sayak Mukherjee，Ján Drgoňa，Aaron Tuor，Mahantesh Halappanavar，Draguna Vrabie，神经李雅普诺夫可微预测控制，IEEE决策与控制会议2022年
• Wenceslao Shaw Cortez，Jan Drgona，Aaron Tuor，Mahantesh Halappanavar，Draguna Vrabie，具有安全保证的可微预测控制：基于控制屏障函数的方法，IEEE决策与控制会议2022年
• Ethan King，Jan Drgona，Aaron Tuor，Shrirang Abhyankar，Craig Bakker，Arnab Bhattacharya，Draguna Vrabie，基于库普曼算子的可微预测控制在动态感知经济调度问题中的应用，2022年美国控制会议（ACC）
• Drgoňa, J., Tuor, A. R., Chandan, V., & Vrabie, D. L., 物理约束下的多区域建筑热动力学深度学习。能源与建筑，243，110992，2021年
• E. Skomski，S. Vasisht，C. Wight，A. Tuor，J. Drgoňa和D. Vrabie，“受约束的块状非线性神经动力学模型”，2021年美国控制会议（ACC），2021年，第3993–4000页，doi：10.23919/ACC50511.2021.9482930。
• Skomski，E.，Drgoňa，J.，& Tuor，A.（2021年5月）。通过学习与进化自动发现物理信息神经状态空间模型。载于《动力学与控制的学习》（第980–991页）。PMLR。
• Drgoňa，J.，Tuor，A.，Skomski，E.，Vasisht，S.，& Vrabie，D.（2021年）。为建筑物开发深度学习显式可微预测控制律。IFAC-PapersOnLine，54(6)，第14–19页。
• Tuor，A.，Drgona，J.，& Vrabie，D.（2020年）。具有稳定性保证的受约束神经常微分方程。arXiv预印本arXiv:2004.10883。
• Drgona，Jan等。“可微预测控制：一种适用于未知非线性系统的MPC替代方案，采用受约束的深度学习。”过程控制杂志第116卷，2022年8月，第80–92页
• Drgona，J.，Skomski，E.，Vasisht，S.，Tuor，A.，& Vrabie，D.（2020年）。耗散型深度神经动力学系统，载于IEEE开放控制系统期刊，第1卷，第100–112页，2022年
• Drgona，J.，Tuor，A.，& Vrabie，D.，学习带有保证的受限自适应可微预测控制策略，arXiv预印本arXiv:2004.11184，2020年

引用方式

@article{Neuromancer2023,
  title={{NeuroMANCER：具有自适应非线性约束和高效正则化的神经模块}},
  author={Drgona, Jan and Tuor, Aaron and Koch, James and Shapiro, Madelyn and Jacob, Bruno and Vrabie, Draguna},
  Url= {https://github.com/pnnl/neuromancer}, 
  year={2023}
}

开发团队

主要开发者：Jan Drgona，Aaron Tuor
重要贡献者：Rahul Birmiwal，Bruno Jacob，Reilly Raab，Madelyn Shapiro，James Koch，Seth Briney，Bo Tang，Ethan King，Elliot Skomski，Zhao Chen，Christian Møldrup Legaard，Tyler Ingebrand，Alireza Daneshvar，Cary Faulkner
科学顾问：Draguna Vrabie，Panos Stinis

开源贡献者：

由contrib.rocks制作。

致谢

本研究得到了太平洋西北国家实验室（PNNL）实验室指导研究与发展（LDRD）项目的部分支持，具体通过“科学中的人工推理数学”（MARS）和“数据模型融合”（DMC）两大倡议；同时还得到了美国能源部高级科学计算研究办公室“复杂系统的数据驱动决策控制”（DnC2S）项目的支持，以及能源效率与可再生能源建筑技术办公室下“通过以物理为中心的自主深度学习和建筑运营优化实现动态脱碳”和“以经济高效的不同可微预测控制推动市场-ready建筑能源管理”两个项目的支持。此外，本项目还获得了美国能源部科学局高级科学计算研究（ASCR）计划下“多保真度算子学习不确定性量化”（MOLUcQ）项目的资助（项目编号：81739）。PNNL是由巴特尔纪念研究所根据合同编号DE-AC05-76RL0-1830代表美国能源部（DOE）运营的多学科国家实验室。本研究亦得到美国能源部科学局ASCR计划下“先进计算促进科学发现”（SciDAC）研究所“LEADS：学习加速领域科学”项目的部分支持。同时，本研究还得到了约翰霍普金斯大学拉尔夫·奥康纳可持续能源研究所（ROSEI）的支持。

NeuroMANCER 快速上手指南

NeuroMANCER 是一个基于 PyTorch 的开源可微分编程（DP）库，专为解决参数化约束优化问题、物理信息系统的辨识以及基于模型的参数化最优控制而设计。它支持将机器学习与科学计算系统性地结合，构建嵌入先验知识和物理规律端到端可微模型。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows
• Python: 建议 Python 3.8 或更高版本
• 核心依赖:
  • PyTorch (NeuroMANCER 基于 PyTorch 构建)
  • pip 包管理工具
• 推荐: 使用虚拟环境（如 venv 或 conda）以避免依赖冲突。

注意：本库未提供特定的国内镜像源，安装时可使用清华或阿里镜像加速 PyTorch 及相关依赖的下载。

安装步骤

方法一：使用 pip 直接安装（推荐）

这是最快捷的安装方式，会自动处理大部分依赖。

pip install neuromancer

若需加速下载，可添加国内镜像源：

pip install neuromancer -i https://pypi.tuna.tsinghua.edu.cn/simple

方法二：手动安装

如果您需要自定义安装或开发贡献，请参考项目根目录下的 INSTALLATION.md 文件进行手动配置。

基本使用

NeuroMANCER 的核心优势在于其符号编程接口，允许用户轻松定义物理方程、领域知识和约束条件。以下是一个解决参数化约束优化问题的最小化示例（基于经典的 Rosenbrock 函数变体）：

代码示例

# Neuromancer syntax example for constrained optimization
import neuromancer as nm
import torch 

# 1. 定义神经网络架构 (MLP)
func = nm.modules.blocks.MLP(insize=1, outsize=2, 
                             linear_map=nm.slim.maps['linear'], 
                             nonlin=torch.nn.ReLU, hsizes=[80] * 4)

# 2. 通过 Node 类将神经网络包装为符号表示：map(p) -> x
# 输入变量为 'p'，输出变量为 'x'
map = nm.system.Node(func, ['p'], ['x'], name='map')
    
# 3. 定义决策变量
x = nm.constraint.variable("x")[:, [0]]
y = nm.constraint.variable("x")[:, [1]]

# 4. 定义问题参数 (通常在数据集中采样)
p = nm.constraint.variable('p')

# 5. 定义目标函数 (最小化 f)
f = (1-x)**2 + (y-x**2)**2
obj = f.minimize(weight=1.0)

# 6. 定义约束条件
con_1 = 100.*(x >= y)
con_2 = 100.*(x**2+y**2 <= p**2)

# 7. 创建基于惩罚方法的损失函数
loss = nm.loss.PenaltyLoss(objectives=[obj], constraints=[con_1, con_2])

# 8. 构建可微分的约束优化问题
problem = nm.problem.Problem(nodes=[map], loss=loss)

下一步学习

完成上述基础示例后，建议您访问官方的 Google Colab 教程 进行深入实践，涵盖以下内容：

• 基础语法: 变量、节点、系统与约束的定义。
• 领域应用: 建筑热动力学建模 (Neural ODEs)、能源负载预测、电力系统控制等。
• 高级方法: 学习优化 (L2O)、学习控制 (L2C) 及微分预测控制 (DPC)。