PEARSim

PEARSim

一款无界面、确定性的电力电子仿真器，可通过文本文件、命令行或 AI Agent 驱动。模型采用 YAML 格式，仿真结果存放在包含哈希清单的目录中，工具输出的每个数值都可以追溯到生成该结果的模型、请求和求解器设置。由 PEAR Power 发布。

警告

**目前处于早期 Alpha 阶段。请勿用于设计签核、保护设置、安全分析或合规性证据。**下文的能力声明边界是产品的一部分，并非可以略过的免责声明：对于尚未验证的能力，本工具会明确说明、拒绝猜测并记录拒绝行为。

目录： 安装 · 五分钟上手 · 通过 AI Agent 使用 · 当前支持的仿真内容 · 结果如何得到验证 · 明确不支持的内容 · 可复现性 · 使用指南 · 贡献

为什么选择 PEARSim

1. **保留证据，而非仅作声明。**结果会与独立于求解器编写的闭式解、开源的第二个引擎（ngspice）以及每次运行的物理不变量（例如能量平衡）进行核验。对比记录保存在代码库中，任何人都可以重新生成。
2. **遇到未知情况时拒绝，而非猜测。**未知能力会被视为不支持；无效电路会返回明确命名的错误，而不是进行隐藏的正则化；每项结果都附带警告和置信度等级。能力注册表（pear-sim capabilities）会说明哪些能力受支持、处于实验阶段或不受支持。
3. **既为 Agent 打造，也为人打造。**CLI、类型化 Python API 和 MCP 服务使用同一套契约，因此 AI Agent 可以编写、验证和仿真模型，并读取精简且可审计的结果。

安装

说明

首个 PyPI 版本尚未发布。在发布之前，请从源代码检出版本安装：

git clone https://github.com/PEAR-power/pear-sim && cd pear-sim
uv sync --locked --extra dev        # or: pip install -e ".[mcp]"

发布后：

pip install pear-sim                # the simulator: CLI and Python API
pip install "pear-sim[mcp]"         # plus the MCP server (pear-sim mcp)
uvx pear-sim-mcp                    # or run the MCP server without installing anything

需要在 Linux、macOS 或 Windows 上使用 Python 3.11+。运行时依赖包括 numpy、scipy、PyYAML 和 jsonschema——无需 Docker、浏览器或专有仿真器。

五分钟上手

pear-sim lint examples/buck.yaml                      # validate model + topology
pear-sim explain examples/buck.yaml --json            # resolved values, assumptions, limits
pear-sim simulate examples/buck.yaml --out runs/buck  # portable run bundle
pear-sim report runs/buck --out reports/buck          # offline HTML, no network

（从源代码检出版本运行时，请在命令前加上 uv run。）

报告是一个独立的离线 HTML 文件，包含运行元数据和哈希、所有警告、波形（每个快速切换信号还会绘制未经抽取的缩放视图，以便清楚显示 PWM）、物理审计、开关时间线、损耗和结温（前提是声明了器件卡），以及来源信息。

### 来自 AI Agent（MCP）

PEARSim 随附一个 MCP 服务，因此 Claude、Codex、Cursor 或任何其他 MCP 客户端都可以替你编写、验证和仿真模型：

claude mcp add pear-sim -- uvx pear-sim-mcp                              # after the PyPI release
claude mcp add pear-sim -- uv run --project /path/to/pear-sim pear-sim mcp   # from a checkout

从你自己的项目目录运行：服务可以从该目录读取模型，运行结果也会写入该目录下的 .pear-sim/。（请使用 --project，而不是 --directory：后者会将服务移入 PEARSim 检出目录。）

然后可以提出类似这样的要求：“设计一个 48 V 转 12 V、10 A、200 kHz 的同步降压转换器，并检查输出纹波。” Agent 会从随附的示例开始，验证模型、运行仿真，并报告数值以及工具的警告——在我们的 Agent 评估中，Claude Opus 5.5 在 33 次评分运行（11 项工程任务 × 3）中全部通过，且每个引用的数值都经过仿真器核对。其他客户端的配置、工具列表和安全规则（文件系统边界封闭、时间限制、精简结果）：Agent 接口。

以下是一个完整的降压转换器示例，让你一次看清整个格式：

schema: pear-sim/v0.1
name: buck_ccm

parameters:
  vin: 100 V
  fsw: 20 kHz
  duty: 40 %
  load: 10 ohm

circuit:
  ground: gnd
  components:
    - {id: vin,  type: voltage_source, p: in,  n: gnd, value: "${vin}"}
    - {id: q1,   type: ideal_switch,   p: in,  n: sw,  control: pwm, initial: on}
    - {id: d1,   type: diode,          p: gnd, n: sw,  initial: off}
    - {id: l1,   type: inductor,       p: sw,  n: out, value: 1 mH,   initial_current: 4 A}
    - {id: c1,   type: capacitor,      p: out, n: gnd, value: 100 uF, initial_voltage: 40 V}
    - {id: load, type: resistor,       p: out, n: gnd, value: "${load}"}

controls:
  pwm: {type: pwm, frequency: "${fsw}", duty: "${duty}", phase: 0 s}

analysis:
  transient: {start: 0 s, stop: 2 ms, output_step: 1 us, solver: dopri5, rtol: 1.0e-8, atol: 1.0e-10}

outputs: [v(out), i(l1), i(q1), i(d1)]

单位明确且经过检查（100 uF、20 kHz、40 %）。这里没有表达式语言：${1/fsw} 是错误，而不是一项功能——无法命名的值就无法审计。完整规范：模型格式。

---

当前可仿真的内容

内核。 事件驱动的分段 LTI 状态空间（采用二极管有效集的改进节点分析）。开关时刻会被精确定位，而不是跨过：预定的栅极边沿和自然换流都会成为精确事件，电容电压和电感电流在事件前后保持连续。

领域	已支持功能	起始示例
DC-DC	CCM/BCM/DCM 下的降压、升压、反相降压-升压，支持二极管自然关断	examples/buck.yaml、boost.yaml、buck_dcm.yaml
隔离型	DAB（移相）、带谐振槽路的半桥 LLC	dab_phase_shift.yaml、llc_resonant.yaml
整流器	半波整流、变压器上的 6 脉波整流、带耦合绕组组的 12 脉波 Y-y-d 整流、移相控制晶闸管	rectifier_12pulse_yyd.yaml、thyristor_phase_controlled.yaml
逆变器	三相两电平（六步、SPWM、SVPWM）、浮动中性点、弱电网、带环路 PLL 的电网跟随型逆变器	inverter_three_phase_spwm.yaml、grid_following_converter.yaml
多电平	三相三电平 NPC 和五电平 DNPC，包括直流中点平衡	npc_three_phase.yaml、npc5_three_phase.yaml
电机	PMSM（正弦反电动势）、凸极同步电机和同步磁阻电机、磁链图 ψ(i_d, i_q)、带 H 桥的直流驱动（电机功能为实验性）	pmsm_inverter_drive.yaml、synrm_torque_test.yaml、dc_drive_hbridge.yaml
磁性元件	互感、耦合绕组组（3×3 及更大）、饱和电感	transformer_rl.yaml、rl_sat_inductor.yaml
器件	理想或分段线性开关和二极管（on_resistance、forward_voltage）、作为开关 + 体二极管的 MOSFET	sync_buck_mosfet.yaml
控制	固定 PWM、带死区的互补 PWM、三相 SPWM/SVPWM、电平移位 NPC 调制、采样 PI 和 dq 电流环、带有 pi 模块的信号块层	synchronous_buck_complementary.yaml、buck_closed_loop_signals.yaml
损耗与热	器件卡（导通 LUT、开关能量）、Foster 网络、风冷和液冷、效率图、雨流计数	buck_with_loss_cards.yaml、traction_inverter_liquid_cooled.yaml
**超越单次瞬态的分析：**通过 Newton 射击法求周期稳态（包括电感星形拓扑）、针对明确声明的补偿器分析小信号环路增益及相位裕度／增益裕度——包含 ZOH 和计算延迟项，因为对数字控制转换器绘制连续 Bode 图会乐观地高估数十度——模态谐振审计、事件对齐的傅里叶／THD 分析、有界参数和容差角点扫描。扫描点并行运行（--jobs，默认使用除一个以外的所有核心）；保留的结果不受作业数量影响。

一次设计多个方案。 pear-sim batch 可筛选多达 2 000 个设计（拉丁超立方、网格或列表），根据声明的目标和约束进行排名（例如：器件损耗最低，同时输出纹波低于 0.5 V，且每个结温都低于 125 °C），并对入围方案进行完整重跑，检查其是否能复现筛选结果。胜出者是样本中的最佳方案，而非全局最优解。参见 docs/batch.md。 可选的 Rust 编译内核（--backend rust，docs/rust-core.md）通过逐步移植 SciPy 的 RK45 来积分各段；Python 引擎仍是参考实现，并且 CI 会针对所有已覆盖示例与之核对。 pear-sim sensitivity 可回答在声明的范围内，哪些参数会影响哪些输出：Morris 筛选或 Sobol 指数，每项均附带 bootstrap 95 % 区间（docs/sensitivity.md）。

复用。 声明式子电路让你只需编写一次桥式电路定义，即可多次实例化：十二脉波整流器使用两次同一个 three_phase_diode_bridge 定义。展开过程具有确定性，并在加载时完成，因此层级结构只用于呈现，不影响物理特性——同一电路的扁平写法和层级写法会产生相同的物理哈希和逐位一致的波形。

---

如何证明结果

这正是本项目存在的意义。上述每项声明都基于三类彼此独立的证据之一，而且证据会被保留，而非仅仅声称存在：

1. 闭式解。 解析 RC/RL/RLC 瞬态、转换比、Foster 阻抗、R-L 相位控制整流器的熄弧角，以及独立于求解器编写的降压／升压／反相降压-升压电路规范周期基准（基准层不会导入内核）。
2. 另一个开放引擎。 针对线性子集的 ngspice 差分适配器，其中明确声明了相对误差预算和重采样项。任何人都可以重新运行：安装 ngspice 并运行 uv run pytest tests/test_ngspice_oracle.py。
3. 物理不变量。 每次运行的能量平衡、KCL/KVL 结构、模式覆盖观察结果，以及针对已识别拓扑的解析自检。

比较记录位于 validation/oracle-records/：每条记录都包含相对于所声明容差实际测得的偏差，并且每条记录都必须能由本仓库中的测试重新生成。两个模拟器达成一致属于验证（实现求解了它所声称的模型），而非基于硬件的确认——这里没有任何声明依赖测量结果。如果某项功能完全没有独立比较，其功能条目会明确说明。

每项功能（包括不受支持的功能）的机器可读状态：

uv run pear-sim capabilities --json
uv run pear-sim capabilities --id analysis.steady_state.shooting

---

它刻意不做的事

在相信某个数值之前，请先阅读本节。

• 最多只支持分段线性器件。 开关或二极管默认为理想器件；除非你为其设置 on_resistance / forward_voltage，此时导通关系会在电路方程中表示为 v = V_f + R_on·i。这里没有反向恢复、开关瞬态、温度依赖或 EMI，也没有寄生参数，除非你将其声明为 电路元件（ESR 和 DCR 是串联电阻）。开关损耗会在仿真运行结束后根据已声明的卡片计算，因此这类耗散不会反馈到求解结果中——我们有意断开了电热闭环，雅可比矩阵对此也有明确体现。
• 没有器件目录。 此仓库中随附的所有器件卡片都是虚构的。损耗或温度数值的准确性完全取决于对应卡片，而此工具无法判断卡片是否为虚构。
• 不是通用 DAE 求解器。 电容回路、通用电感割集以及任意浮动状态拓扑都会被拒绝，并返回带有名称的 TopologyError；不会通过隐藏的 gmin 或漏电参数进行静默正则化。我们支持范围有限且有文档说明的零电流和电感星形路径；其他情况都会安全失败。
• 有界的活动集。 二极管活动集搜索有界（最多 64 个器件，并设有候选预算）；预算耗尽时会报错并附带首个原因，绝不会猜测。
• 裕度是对已声明补偿器的验证，基于 CCM 下单个 PWM 桥臂的平均模型；它不是闭环证明：你声明补偿器，工具会告知其意味着什么。闭环时域仿真使用信号块层（包括 pi 块），这是另一种独立的仿真实现。
• 模态和覆盖率报告只是观测结果，不是结论。 如果运行中自然换流次数为零，意味着未测试该覆盖率——绝不代表机制已通过。
• 完全不在范围内：实时仿真/HIL、生产代码生成、FEM/PCB/场仿真、商业仿真器的原生模型文件，以及与其他仿真器逐位完全一致的复现。

对于未知能力，我们会按不支持处理。如果你能让工具在上述范围之外生成看似可靠的数值，那就是值得报告的错误。

---

可复现性

simulate 会拒绝覆盖非空目录，并写入一个可移植的文件包： run.json（清单、哈希、平台）、model.resolved.json、waveforms.csv、 events.jsonl、metrics.json、physics-audit.json、mode-coverage.json、 confidence-card.json、warnings.json、summary.json，以及一个包含每个文件 SHA-256 和字节数的 artifact-manifest.json。当模型需要时，还会生成拓扑和分析专用工件 （analytic-checks.json、gate-drive.json、resonance.json、losses-thermal.json、 harmonics.json、modulation-cycles.jsonl 等）。

Lean 运行（--lean）

参数搜索会对同一电路运行数百次，并读取三个数值；它不会读取第 417 次运行的能量平衡。simulate --lean 就是为这种运行设计的：它会跳过逐个组件的功率积分，以及已报告的末半段时间窗之外的密集状态极值搜索，而这两项占据了运行的大部分成本。

它减少的是声明，而不是精度。Lean 运行仍会报告的所有内容——波形、metrics.json、mode-coverage.json、已发布的 state_extrema——都来自完全相同的代码路径，与完整运行逐位一致；积分过程本身未作改动，因此步进序列和轨迹完全相同。被省略的内容会整体省略，绝不使用近似值：physics-audit.json 会标记 status: not_computed，而已报告时间窗之外的逐区间极值会设为 null，并标注 state_extrema_method: not_computed_in_lean_evidence_mode。

Lean 结果包会在四处说明这一点——控制台、warnings.json（EVIDENCE_MODE_LEAN，严重性为 warning）、summary.json 和 run.json（evidence_mode）——而且两种模式都会写入 evidence_mode，因此完整结果包会明确说明其范围，而不是保持沉默、任人推断。先用 --lean 进行筛选，再不带该选项重新运行入围方案：这才是你要展示的运行结果。

四种哈希共同标识一项结果：源代码、已解析的物理模型、请求和运行。同一电路的两种写法会共享一个物理哈希；容差变化则会改变请求哈希。这样一来，“这两个修订版本之间到底有没有实际变化？”就成了一个可机械判定的问题——参见 pear-sim compare。

指标是拓扑分段上的连续时间积分；在请求网格上计算的内容会以 sample_* 命名，以免混淆。自适应求解器在不同平台和版本上会采取不同的内部步长，因此比较应基于明确声明输出网格和容差，而不是逐字节相等。

退出代码：0 所有适用的阻断检查均已通过 · 1 已保留证据，但存在阻断性 fail / not_comparable / not_run · 2 请求、输入、拓扑或目标位置无效。

---

设计循环层（开发中）

除了运行单个模型外，该项目还在逐步构建选择设计所需的组件，而不只是检查设计。以下内容仍处于早期阶段，并标记为实验性：

• 设计规范 — 将需求表示为类型化对象，区分硬约束和软约束，并通过提问而非擅自设定默认值来明确需求。
• 拓扑库 — 每种拓扑对应一个 YAML 文件：前置条件、以数据表示的开关周期，以及一份必填的已知限制列表（空列表也是一种声明，因此该格式不接受空列表）。
• 梯度引擎 — 在精确周期映射上计算稳态指标对设计参数（占空比、死区时间、L、C、负载、相移）的灵敏度，并对自然换流使用盐跃法。它提供方向；只有 oracle 能判定是否通过。

方向和待处理事项：参见组件路线图和问题跟踪器。

---

使用说明

pear-sim --help 是命令参考。除上述四个命令外，还有： catalog、capabilities、spec、render、evaluate、analyze、compare、sweep、batch、sensitivity、 verify、review、topology、doctor、mcp。

三个接口，同一契约：CLI、类型化 Python API（pear_sim.api， 文档）和 MCP 服务（Agent 接口）——通过任何一个接口使用同一场景，都会生成位级一致的 run_sha256。

pear-sim doctor 会报告版本、软件包完整性、可用的 oracle 后端以及浮点确定性探测结果——如果两台机器的结果不同，请先运行它。

审核工作：review prepare 会生成一个与哈希绑定的数据包，记录模拟内容；annotate 会追加哈希链式评论；check 会验证完整性和决策绑定关系。这是一种可审计的传输格式——不是签名机构，也不代表组织授权；审核者身份未经验证。

开发：每次提交都必须通过 uv run pytest（约 1,200 个测试）和 uv run ruff check .。贡献规则：CONTRIBUTING.md 和 AGENTS.md；架构说明见 docs/architecture.md。

CI 在 Linux（Python 3.11 和 3.13）、Windows 和 macOS 上运行。

---

实现说明

内核采用事件驱动的分段线性方法：两个开关事件之间，电路是由改进节点分析组装而成的线性时不变系统；事件——计划中的栅极边沿和自然发生的二极管换流——会被定位为精确时刻，而不会跨过事件逐步推进。这样可确保电容电压和电感电流连续，使运行结果具有确定性，并让稳态、小信号平均和灵敏度分析使用相同的精确周期映射。主要设计选择的详情及原因见 架构说明和 ADR。计划将编译型内核作为可选后端，在相同的模型格式、CLI 和 MCP 契约下提供。

贡献

欢迎贡献——请先阅读 CONTRIBUTING.md。简而言之：每项更改都应以公开的数学原理、标准、采用开放许可的来源或你自己的成果为依据；不得使用专有或反编译代码、复制的组件库或演示模型，也不得使用商业工具中的模型文件；每个缺陷修复都必须从一个失败测试开始；新增功能必须明确说明其声明边界，不得夸大。

除非你明确声明另有安排，否则任何有意提交以纳入本项目的贡献，均按照 Apache License 2.0 许可，且不附加任何条款或条件。

产品名称为 PEARSim；发行包和可执行文件为 pear-sim，导入包为 pear_sim——详见 ADR 0003。

许可证

版权所有 2026 PEAR Power 和 PEARSim 贡献者。

本项目根据 Apache License, Version 2.0 授权。除描述软件来源所必需的情形外，该许可证不授予使用 PEAR Power 或 PEARSim 名称或徽标的权限。第三方数据集、示例和可选后端仍适用各自的声明。

复用此代码

你可以复制、修改和重新分发 PEARSim，包括用于商业用途。进行这些操作时，请保留 LICENSE 和 NOTICE 文件，以及每个复制的源文件顶部的 SPDX-License-Identifier / 版权声明，并标记你修改过的文件。无论代码是手动、通过脚本还是由 AI 编码 Agent 移动，此要求均适用。

src/ 和 rust/ 下的产品源文件还带有一行含固定 GUID 的 PEARSim provenance mark。它不会影响运行时行为；它用于追踪副本。请将它与其余声明一并保留。