PDE 求解框架

unitarylab.library.equation 提供一套基于 Schrödingerization（薛定谔化）的方程求解工具：先把离散后的非酉演化问题嵌入更高维的薛定谔型演化，再使用经典矩阵指数、Trotter 线路或块编码线路求解。

本页同时介绍底层公共接口和 examples 中的 20 个配置驱动算法。第一次使用时，建议先运行默认的 classical 配置，确认方程参数和输出正确后，再切换 Trotter 或 block 方法。

工作流程


setup.json / dict / JSON 字符串
        │
        ▼
parse_equation()
        │
        ├── Equation 与方程参数
        ├── BoundaryCondition
        ├── InitialCondition
        ├── DiscreteFormat
        ├── Preprocessing
        └── SolutionMethod
        │
        ▼
有限差分与 Schrödingerization
        │
        ├── classical：矩阵指数参考实现
        ├── trotter：构造并执行 Trotter 线路
        └── block：构造并执行块编码线路
        │
        ▼
结果字典 + 解图 + 线路图 + 日志

框架按四层职责组织：


equation/
├── differential_operator/   # 经典、Trotter 和块编码差分算子
├── equation_parser/         # 方程、边界、初值、离散格式与求解器配置解析
├── schrodingerization/      # classical 和 Trotter Schrödingerization
└── examples/                # 20 个配置驱动的方程算法

公共接口

以下 9 个名称由 unitarylab.library.equation 顶层直接导出：

接口	作用
`CDiff`	构造经典有限差分算子
`TDiff`	构造可用于 Trotter 演化的有限差分算子
`ClassicalOperator`	经典矩阵形式的微分算子
`TrotterOperator`	Trotter 线路形式的微分算子
`parse_equation()`	将字典或 JSON 字符串解析为完整的 `Equation`
`Equation`	聚合方程、边界、初值、离散化、预处理和求解器配置
`schro_trotter()`	执行 Trotterized Schrödingerization
`initial_schro_fp()`	构造辅助寄存器使用的 warped phase 初态函数
`schro_classical()`	使用矩阵指数计算 classical 参考解


from unitarylab.library.equation import (
    CDiff,
    TDiff,
    ClassicalOperator,
    TrotterOperator,
    parse_equation,
    Equation,
    schro_trotter,
    initial_schro_fp,
    schro_classical,
)

大多数用户应优先使用 examples 中的算法类；只有需要自行组装离散算子或 Schrödingerization 流程时，才直接调用上述底层接口。

快速开始：一维热方程

HeatEquationAlgorithm 默认读取同目录的 setup.json。当前默认选择 classical 方法，因此不需要量子模拟后端：


from unitarylab.library.equation.examples import HeatEquationAlgorithm
 
solver = HeatEquationAlgorithm()
result = solver.run(
    params=None,
    algo_dir="results/pde-heat",
)
 
print(result["status"])
print(result["message"])
print(result["grid"])
print(result["x"][:5])
print(result["u"][:5])
print(result["plot"])
print(result["circuit"])

典型返回结果包含：

字段	说明
`status`	执行状态，成功时为 `"ok"`
`message`	方程和方法对应的结果说明
`grid`	网格点数量、步长等离散信息
`x`、`u`	空间坐标和数值解；二维问题通常还包含 `y`
`plot`	解图的格式和文件路径
`circuit`	生成的线路图路径列表；classical 方法也会生成算法模板线路图

run() 会写入结果文件。根据执行路径，algo_dir 可包含 algorithm.log、algorithm_error.log、解图 SVG 和线路图。省略 algo_dir 时，默认目录为：


<当前工作目录>/results/equation/equation_heat

需要固定输出位置时，应显式传入 algo_dir。

配置结构

params 可以是 None、已经解析的字典，或者等价的 JSON 字符串。传入 None 时读取算法目录内的 setup.json。


{
  "request_id": "可选请求标识",
  "params": [
    {
      "equation": {...},
      "boundary_condition": [...],
      "initial_condition": [...],
      "discrete_format": [...],
      "preprocessing": [...]
    },
    {
      "type": "solutionMethod_classical",
      "par_fix": [...],
      "par_func": [...]
    }
  ]
}

params[0] 描述方程，并通过 type 字段选择边界条件、初值、离散格式和预处理方案。
params[1] 是本次实际使用的求解方法，例如 solutionMethod_classical、solutionMethod_trotter 或 solutionMethod_block。
par_fix 保存标量参数，例如 L、T、nx、na、R、p、order 和 dt。
par_func 保存初值、源项等函数表达式。
parse_equation() 会把配置装配成 Equation，并挂载 boundary、initial、discrete、preprocessing 和 solver。

求解方法必须同时由对应算法和 setup.json 声明支持；未声明的方法名会导致配置或执行错误。

求解方式

方法	行为	后端参数
classical	通过经典矩阵指数计算参考解，同时生成结果图和模板线路图	不使用 `backend`、`device`、`dtype`
trotter	构造差分算子和 Trotter 线路，并使用模拟后端执行	在支持该签名的算法中可配置
block	构造块编码线路并执行 Schrödingerization	在支持该签名的算法中可配置

Trotter 和 block 并非每个示例都支持。即使某个 run() 接受后端参数，也只能选择该示例 method_list 中声明的方法。

内置算法

示例目录 / 算法类	问题	支持方法	后端参数
`equation_heat` / `HeatEquationAlgorithm`	一维热方程	classical、trotter、block	支持
`equation_heat2d` / `Heat2dEquationAlgorithm`	二维热方程	classical、trotter	支持
`equation_heatVariableCoefficient` / `HeatVariableCoefficientEquationAlgorithm`	一维变系数热方程	classical、block	不支持
`equation_backHeat` / `backHeatEquationAlgorithm`	一维反向热方程	classical、trotter、block	支持
`equation_backHeat2d` / `backHeat2dEquationAlgorithm`	二维反向热方程	classical、trotter	支持
`equation_advection` / `AdvectionEquationAlgorithm`	一维平流方程	classical、trotter	支持
`equation_burgers` / `BurgersEquationAlgorithm`	一维 Burgers 方程	classical、trotter	支持
`equation_burgers2d` / `Burgers2DEquationAlgorithm`	二维 Burgers 方程	classical、trotter	支持
`equation_elasticWave` / `ElasticWaveEquationAlgorithm`	一维弹性波	classical、trotter	支持
`equation_elasticWave2d` / `ElasticWave2DEquationAlgorithm`	二维弹性波	classical	不支持
`equation_general` / `GeneralLinearEquationAlgorithm`	一般一维线性方程	classical、trotter、block	支持
`equation_traffic` / `TrafficFlowEquationAlgorithm`	一维交通流	classical、trotter	支持
`equation_blackScholes` / `BlackScholesEquationAlgorithm`	一维 Black–Scholes 方程	classical、trotter、block	支持
`equation_Helmholtz` / `HelmholtzEquationAlgorithm`	一维 Helmholtz 方程	classical	不支持
`equation_OUprocess` / `OUProcessEquationAlgorithm`	Ornstein–Uhlenbeck 过程	classical	不支持
`equation_SchrABC` / `SchrABCEquationAlgorithm`	带人工边界的二维 Schrödinger 方程	classical	不支持
`equation_hamiltonjacobi` / `HamiltonJacobiEquationAlgorithm`	一维 Hamilton–Jacobi 方程	classical	不支持
`equation_maxwell` / `MaxwellEquationAlgorithm`	一维 Maxwell 方程	classical	不支持
`equation_multiElliptic` / `MultiEllipticEquationAlgorithm`	一维多尺度椭圆方程	classical	不支持
`equation_multiTransport` / `MultiTransportEquationAlgorithm`	一维多尺度输运方程	classical	不支持

“后端参数支持”表示 run() 接受 backend="torch"、device="cpu"、dtype=np.complex128。当前共有 11 个示例支持这三个参数，另外 9 个只接受 params 和 algo_dir。不要对所有算法统一传入后端参数，否则会触发 TypeError。

示例类也可以从具体子模块导入：


from unitarylab.library.equation.examples.equation_heat import HeatEquationAlgorithm
from unitarylab.library.equation.examples.equation_maxwell import MaxwellEquationAlgorithm

返回值差异

所有 20 个示例的返回字典都包含 status、message、grid、plot 和 circuit。物理解字段取决于问题：

问题类型	常见字段
一维标量方程	`x`、`u`
二维标量方程	`x`、`y`、`u`
Maxwell	`x`、`E`、`B`
一维弹性波	`x`、`v`、`sigma`
二维弹性波	`x`、`y`、`v1`、`v2`、`s11`、`s12`、`s22`
OU 过程	`t`、`y_expli`、`y_int`
多尺度椭圆	`x`、`u_list`
多尺度输运	`x`、`Ujj`、`Urr`

因此，上层程序应根据所选算法读取结果字段，不应假设所有算法都返回 result["u"]。

规模与使用建议

在使用 nx 的示例中，nx 表示空间寄存器量子比特数，空间网格规模约为 $2^{n x}$ 。
na 表示 Schrödingerization 辅助寄存器量子比特数，辅助离散规模约为 $2^{na}$ 。
增大 nx、na 会显著增加矩阵、状态和线路资源，不能把它们当作普通线性网格点数量使用。
先使用示例默认的 classical 配置验证方程、边界、初值和输出目录。
切换 Trotter 或 block 前，先确认算法表中声明支持，并从较小的 nx、na 开始。
使用量子方法时，根据算法签名传入 backend、device 和 dtype；只支持 classical 的算法不要传入这些参数。
长时间或批量任务应显式设置独立的 algo_dir，避免日志和结果文件相互覆盖。