面向科学机器学习的统一框架

---

入门指南 | 文档 | 贡献说明

PINA 是一个开源的 Python 库，旨在简化和加速科学机器学习（SciML）解决方案的开发。基于 PyTorch、PyTorch Lightning 和 PyTorch Geometric 构建，PINA 提供了一个直观的框架，用于定义、实验和解决使用神经网络、物理信息神经网络（PINNs）、神经算子等复杂问题。

• 模块化架构：PINA 在设计时充分考虑了模块化，并依赖于强大且可组合的抽象层，允许用户轻松地插入、替换或扩展组件，从而简化实验和自定义过程。

• 可扩展性能：PINA 原生支持多设备训练，能够高效处理大规模数据集，提供接近手写实现的性能，同时开销极低。

• 高度灵活：无论您是需要完全自动化还是精细控制，PINA 都能适应您的工作流程。高层抽象简化了模型定义，而高级用户则可以深入到训练和推理过程的每一个细节进行微调。

安装

安装稳定版 PINA

使用 pip 安装：

pip install "pina-mathlab"

从源码安装：

git clone https://github.com/mathLab/PINA
cd PINA
git checkout master
pip install .

安装附加包：

要安装运行测试或教程目录所需的额外依赖，请使用以下命令：

pip install "pina-mathlab[extras]" 

可用的附加选项包括：

• dev 用于开发目的，如果您想 贡献代码，请使用此选项。
• test 用于在本地运行测试。
• doc 用于在本地构建文档。
• tutorial 用于运行 教程。

新用户快速入门

在 PINA 中解决微分问题遵循 四步流程：

1. 使用 Problem API 定义待求解的问题及其约束条件。

2. 使用 PyTorch 设计您的模型；对于基于图的问题，可以利用 PyTorch Geometric 构建图神经网络。您也可以直接从 Model API 导入模型。

3. 选择或构建问题的求解器，例如监督型求解器或物理信息型求解器（如 PINN）。PINA 求解器 具有模块化特性，可以直接使用或进行定制。

4. 使用基于 PyTorch Lightning 构建的 Trainer API 类来训练模型，该类支持高效、可扩展的训练，并具备高级功能。

想了解更多吗？请查看我们的 教程。

解决数据驱动问题

数据驱动建模旨在学习一个函数，该函数根据输入数据生成输出（例如回归、分类等）。在 PINA 中，您可以轻松完成以下操作：

import torch
from pina import Trainer
from pina.model import FeedForward
from pina.solver import SupervisedSolver
from pina.problem.zoo import SupervisedProblem

input_tensor  = torch.rand((10, 1))
target_tensor = input_tensor.pow(3)

# 第一步：定义问题
problem = SupervisedProblem(input_tensor, target_tensor)
# 第二步：设计模型（您可以在此处使用自己喜欢的 torch.nn.Module）
model   = FeedForward(input_dimensions=1, output_dimensions=1, layers=[64, 64])
# 第三步：定义求解器
solver  = SupervisedSolver(problem, model, use_lt=False)
# 第四步：训练
trainer = Trainer(solver, max_epochs=1000, accelerator='gpu')
trainer.train()

解决物理信息问题

物理信息建模旨在学习不仅拟合数据，而且满足已知物理定律（如微分方程或边界条件）的函数。例如，以下微分问题：

$$ \begin{cases} \frac{d}{dx}u(x) &= u(x) \quad x \in(0,1)\ u(x=0) &= 1 \end{cases} $$

在 PINA 中，可以轻松实现如下：

from pina import Trainer, Condition
from pina.problem import SpatialProblem
from pina.operator import grad
from pina.solver import PINN
from pina.model import FeedForward
from pina.domain import CartesianDomain
from pina.equation import Equation, FixedValue

def ode_equation(input_, output_):
    u_x = grad(output_, input_, components=["u"], d=["x"])
    u = output_.extract(["u"])
    return u_x - u

# 构建问题
class SimpleODE(SpatialProblem):
    output_variables = ["u"]
    spatial_domain = CartesianDomain({"x": [0, 1]})
    domains = {
        "x0": CartesianDomain({"x": 0.0}),
        "D": CartesianDomain({"x": [0, 1]}),
    }
    conditions = {
        "bound_cond": Condition(domain="x0", equation=FixedValue(1.0)),
        "phys_cond": Condition(domain="D", equation=Equation(ode_equation)),
    }

# 第一步：定义问题
problem = SimpleODE()
problem.discretise_domain(n=100, mode="grid", domains=["D", "x0"])
# 第二步：设计模型（您可以在此处使用自己喜欢的 torch.nn.Module）
model   = FeedForward(input_dimensions=1, output_dimensions=1, layers=[64, 64])
# 第三步：定义求解器
solver  = PINN(problem, model)

# 步骤 4. 训练
trainer = Trainer(solver, max_epochs=1000, accelerator='gpu')
trainer.train()

应用程序编程接口

以下是 PINA 主要模块的简要介绍。为了获得更好的使用体验和完整信息，请查阅 文档。

贡献与社区

我们非常期待与社区伙伴共同开发 PINA！开始贡献的最佳方式是从带有 good-first-issue 标签 的问题中选择一个。如果您希望参与贡献，请仔细阅读我们的 贡献指南，以获取所有相关细节。

我们衷心感谢迄今为止支持 PINA 的所有贡献者：

由 contrib.rocks 制作。

引用

如果 PINA 对您的研究起到了重要作用，并且您希望在学术出版物中提及该项目，我们建议引用以下论文：

Coscia, D., Ivagnes, A., Demo, N., & Rozza, G. (2023). 基于物理信息的神经网络在高级建模中的应用. 开源软件期刊, 8(87), 5352.

或以 BibTex 格式：

@article{coscia2023physics,
        title={基于物理信息的神经网络在高级建模中的应用},
        author={Coscia, Dario 和 Ivagnes, Anna 和 Demo, Nicola 和 Rozza, Gianluigi},
        journal={开源软件期刊},
        volume={8},
        number={87},
        pages={5352},
        year={2023}
        }

PINA 快速上手指南

PINA 是一个基于 PyTorch 构建的开源科学机器学习（SciML）统一框架，旨在简化物理信息神经网络（PINNs）、神经算子等复杂问题的定义与求解。

环境准备

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

• 操作系统：Linux, macOS 或 Windows
• Python 版本：3.8 及以上
• 前置依赖：
  • PyTorch
  • PyTorch Lightning
  • PyTorch Geometric (处理图神经网络问题时必需)

提示：建议先安装与您的 CUDA 版本匹配的 PyTorch，然后再安装 PINA。

安装步骤

方式一：通过 pip 安装（推荐）

直接安装稳定版本：

pip install "pina-mathlab"

若需运行教程或进行测试，可安装额外依赖包：

pip install "pina-mathlab[extras]" 

支持的额外选项包括：

• tutorial：运行官方教程所需依赖
• test：本地运行测试所需依赖
• dev：开发贡献所需依赖
• doc：构建文档所需依赖

方式二：从源码安装

如果您需要最新的功能或参与开发：

git clone https://github.com/mathLab/PINA
cd PINA
git checkout master
pip install .

基本使用

PINA 的核心工作流遵循四个步骤：定义问题 -> 设计模型 -> 选择求解器 -> 训练。

场景一：数据驱动问题 (Data Driven)

适用于回归、分类等传统机器学习任务。以下示例演示了如何拟合 $y = x^3$ 函数。

import torch
from pina import Trainer
from pina.model import FeedForward
from pina.solver import SupervisedSolver
from pina.problem.zoo import SupervisedProblem

# 生成模拟数据
input_tensor  = torch.rand((10, 1))
target_tensor = input_tensor.pow(3)

# Step 1. 定义问题
problem = SupervisedProblem(input_tensor, target_tensor)

# Step 2. 设计模型 (使用前馈神经网络)
model   = FeedForward(input_dimensions=1, output_dimensions=1, layers=[64, 64])

# Step 3. 定义求解器
solver  = SupervisedSolver(problem, model, use_lt=False)

# Step 4. 训练模型
trainer = Trainer(solver, max_epochs=1000, accelerator='gpu') # 若无 GPU 可改为 'cpu'
trainer.train()

场景二：物理信息问题 (Physics Informed)

适用于求解微分方程，模型需同时满足数据约束和物理定律。以下示例求解常微分方程： $$ \frac{d}{dx}u(x) = u(x), \quad u(0)=1 $$

from pina import Trainer, Condition
from pina.problem import SpatialProblem
from pina.operator import grad
from pina.solver import PINN
from pina.model import FeedForward
from pina.domain import CartesianDomain
from pina.equation import Equation, FixedValue

# 定义物理方程: du/dx - u = 0
def ode_equation(input_, output_):
    u_x = grad(output_, input_, components=["u"], d=["x"])
    u = output_.extract(["u"])
    return u_x - u

# 构建问题类
class SimpleODE(SpatialProblem):
    output_variables = ["u"]
    # 定义空间域 x ∈ [0, 1]
    spatial_domain = CartesianDomain({"x": [0, 1]})
    domains = {
        "x0": CartesianDomain({"x": 0.0}), # 边界点
        "D": CartesianDomain({"x": [0, 1]}), # 计算域
    }
    conditions = {
        "bound_cond": Condition(domain="x0", equation=FixedValue(1.0)), # 边界条件 u(0)=1
        "phys_cond": Condition(domain="D", equation=Equation(ode_equation)), # 物理方程约束
    }

# Step 1. 实例化问题并离散化域
problem = SimpleODE()
problem.discretise_domain(n=100, mode="grid", domains=["D", "x0"])

# Step 2. 设计模型
model   = FeedForward(input_dimensions=1, output_dimensions=1, layers=[64, 64])

# Step 3. 定义 PINN 求解器
solver  = PINN(problem, model)

# Step 4. 训练模型
trainer = Trainer(solver, max_epochs=1000, accelerator='gpu')
trainer.train()

更多高级用法和详细案例，请参考官方 Tutorials。