PEARSim

PEARSim

テキストファイル、コマンドライン、または AI エージェントから実行できる、ヘッドレスで決定論的なパワーエレクトロニクスシミュレーターです。モデルは YAML 形式で、実行結果はハッシュマニフェスト付きのアーティファクトを格納したディレクトリになります。ツールが出力する数値はすべて、その根拠となったモデル、リクエスト、ソルバー設定まで追跡できます。PEAR Power が公開しています。

警告

初期アルファ版です。設計承認、保護設定、安全性解析、または規制関連の証拠には使用しないでください。 以下の主張の適用範囲は製品の一部であり、読み飛ばしてよい免責事項ではありません。能力が実証されていない場合、このツールはその旨を示し、推測を拒み、その拒否を記録します。

目次： インストール · 5 分で試す · AI エージェントから · 現在シミュレーションできる内容 · 結果の証明方法 · 意図的に対応していないこと · 再現性 · 使い方 · コントリビューション

PEARSim を選ぶ理由

1. 証拠を主張するのではなく、保持します。 ソルバーとは独立して記述された閉形式解、オープンな第 2 のエンジン（ngspice）、実行ごとのエネルギー収支などの物理的不変条件を用いて結果を検証します。比較記録はリポジトリ内に保存され、誰でも再生成できます。
2. 推測するのではなく、拒否します。 未知の能力は非対応として扱い、無効な回路は隠れた正則化ではなく、名前付きのエラーで失敗します。また、すべての結果には警告と信頼度が付属します。機能レジストリ（pear-sim capabilities）には、対応済み、実験的、または非対応の機能が明記されています。
3. 人だけでなく、エージェントにも対応しています。 同一のインターフェイスを CLI、型付き Python API、MCP サーバー経由で利用できるため、AI エージェントはモデルの作成、検証、シミュレーションを行い、簡潔で監査可能な結果を読み取れます。

インストール

メモ

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、ブラウザー、プロプライエタリーなシミュレーターは必要ありません。

5 分で試す

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 エージェントから（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/ に保存されます（--directory ではなく --project を使用してください。--directory を使うと、サーバーが PEARSim のチェックアウト内で実行されます）。

たとえば、*「48 V から 12 V、10 A の同期整流型バックコンバーターを 200 kHz で設計し、出力リップルを確認してください」*と依頼します。エージェントは付属のサンプルを基にモデルを作成し、検証してシミュレーションを実行し、数値とツールの警告を報告します。エージェント評価では、Claude Opus 5.5 が採点対象の実行 33 件中 33 件に合格しました（エンジニアリングタスク 11 件 × 3 回）。引用された数値はすべてシミュレーターと照合済みです。ほかのクライアントの設定、ツール一覧、安全規則（ファイルシステムの境界を閉じること、実行時間の制限、結果の簡潔化）については、エージェントインターフェイスをご覧ください。

形式全体が一目でわかるように、バックコンバーターの完全な例を示します。

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
インバーター	三相 2 レベル（6 ステップ、SPWM、SVPWM）、浮動中性点、弱電力系統、PLL をループ内に持つ系統追従型	inverter_three_phase_spwm.yaml、grid_following_converter.yaml
マルチレベル	三相 3 レベル NPC および 5 レベル DNPC（DC 中点の平衡化を含む）	npc_three_phase.yaml、npc5_three_phase.yaml
電気機械	PMSM（正弦波逆起電力）、突極型および同期リラクタンス機、磁束マップ ψ(i_d, i_q)、H ブリッジを用いた DC 駆動（電気機械機能は実験的）	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、スイッチングエネルギー）、フォスター熱回路網、空冷および液冷、効率マップ、レインフロー計数	buck_with_loss_cards.yaml、traction_inverter_liquid_cooled.yaml
単一の過渡現象を超える解析。 ニュートン・シューティング法による周期定常状態解析（インダクター・スター型トポロジーを含む）、宣言された補償器を対象とする小信号ループゲイン解析と位相余裕・ゲイン余裕の評価 — ZOH と計算遅延項を含みます。デジタル制御コンバーターで連続時間のボード線図を使うと、数十度も楽観的になるためです — モード共振の監査、イベントに同期したフーリエ解析／THD、範囲を限定したパラメーターおよび公差コーナーのスイープに対応します。スイープでは各点を並列実行します（--jobs の既定値はコア数から 1 を引いた数）。保持される結果はジョブ数に依存しません。

多数の設計を一度に処理。 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 指数を使用し、いずれもブートストラップによる 95 % 区間を示します（docs/sensitivity.md）。

再利用。 宣言したサブサーキットを使えば、ブリッジを一度記述してインスタンス化できます。12 パルス整流器では、three_phase_diode_bridge の定義を 2 回使用します。展開は決定的で、読み込み時に行われるため、階層構造は表現上のものであり、物理に影響しません。同一回路をフラット形式で記述しても階層形式で記述しても、物理ハッシュは一致し、波形もビット単位で同一になります。

---

結果の実証方法

このプロジェクトが存在する理由はここにあります。上記の主張はすべて、独立した 3 種類の証拠のいずれかに基づいており、その証拠は単に主張するのではなく、保存されています。

1. 閉形式解。 解析的な RC／RL／RLC 過渡現象、変換比、Foster インピーダンス、R-L 位相制御整流器の消弧角、ソルバーとは独立して記述された降圧／昇圧／反転型降圧昇圧コンバーターの標準周期オラクル（オラクル層はカーネルをインポートしません）。
2. もう 1 つのオープンエンジン。 線形サブセットに対する ngspice 差分アダプターです。相対誤差の許容値とリサンプリング項を明示しています。誰でも再実行できます。ngspice をインストールして uv run pytest tests/test_ngspice_oracle.py を実行してください。
3. 物理的不変量。 実行ごとのエネルギー収支、KCL／KVL 構造、モード網羅の観測結果、認識済みトポロジーに対する解析的セルフチェックです。

比較記録は validation/oracle-records/ にあります。それぞれの記録には、宣言された許容値と実測された偏差が記載され、すべての記録はこのリポジトリ内のテストで再生成できなければなりません。2 つのシミュレーター間の一致は、実装が主張どおりのモデルを解いていることを示す検証であり、ハードウェアとの比較による妥当性確認ではありません。ここでの主張に実測値は使われていません。機能に独立した比較結果がない場合は、その機能の項目に明記しています。

未対応の機能も含めた、すべての機能の機械可読ステータス：

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 ソルバーではありません。 コンデンサループ、一般的なインダクタカットセット、任意の浮遊状態トポロジーは、隠れた gmin や漏れで暗黙に正則化するのではなく、名前付きの TopologyError で拒否されます。文書化された限定的なゼロ電流パスとインダクタスター型パスには対応しています。それ以外はフェイルクローズします。
• 有界なアクティブセットです。 ダイオードのアクティブセット探索には上限があります（デバイス数 64、候補数の上限あり）。上限に達すると、推測で結果を返すのではなく、最初の原因を含むエラーになります。
• マージンが示すのは、宣言された補償器を CCM における 1 つの 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）

パラメーター探索では、同じ回路を何百回も実行して、3つの数値を読み取ります。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 バンドルでは、その旨を4か所――コンソール、warnings.json（EVIDENCE_MODE_LEAN、重大度は warning）、summary.json、run.json（evidence_mode）――に記録します。また、evidence_mode はどちらのモードでも書き込まれるため、フルバンドルでも黙って範囲を暗示するのではなく、対象範囲が明示されます。まず --lean でスクリーニングし、最終候補はそれを付けずに再実行してください。提示するのはその結果です。

4つのハッシュで結果をひも付けます。ソース、解決済みの物理モデル、リクエスト、実行です。同じ回路の異なる表記は同じ物理ハッシュを共有し、許容誤差を変更するとリクエストハッシュが変わります。これにより、「この2つのリビジョン間で、実際に何か変わったのか？」を機械的に判定できます。pear-sim compare を参照してください。

メトリクスはトポロジーセグメント上の連続時間積分です。リクエストされたグリッド上で計算される値には sample_* という名前が付くため、両者を混同することはありません。適応型ソルバーはプラットフォームやバージョンによって内部ステップが異なるため、比較には明示的な出力グリッドと宣言済みの許容誤差を使用してください。バイト単位の一致で比較してはいけません。

終了コード：0 適用可能なブロッキングチェックがすべて合格 · 1 ブロッキング状態が fail / not_comparable / not_run の証拠が保持された · 2 リクエスト、入力、トポロジー、または出力先が無効

---

設計ループ層（開発中）

単一のモデルを実行するだけでなく、モデルを検証するだけではなく設計を 選択 するために必要な要素をプロジェクトで拡充しています。これらはまだ初期段階であり、実験的な機能として示されています。

• 設計仕様 — ハード制約とソフト制約を分離し、デフォルトを勝手に設定するのではなく、質問する型付きオブジェクトとしての要件です。
• トポロジーライブラリ — トポロジーごとに1つの YAML ファイルを用意します。前提条件、データとして表現したスイッチングサイクル、既知の制限事項の必須リストを含みます（空リストも主張に当たるため、この形式では受け付けません）。
• 勾配エンジン — 厳密な周期写像上で計算する、定常状態メトリクスの設計パラメーター（デューティ比、デッドタイム、L、C、負荷、位相シフト）に対する感度です。自然転流にはソルテーションを適用します。方向を示しますが、合格を判定するのは引き続きオラクルだけです。

進捗と未解決の項目については、コンポーネントロードマップとイシュートラッカーを参照してください。

---

使用方法

pear-sim --help をコマンドリファレンスとしてご利用ください。上記の4つのコマンド以外にも、次のコマンドがあります。 catalog、capabilities、spec、render、evaluate、analyze、compare、sweep、batch、sensitivity、 verify、review、topology、doctor、mcp。

3つのインターフェースで契約は共通です。CLI、型付き Python API（pear_sim.api、 ドキュメント）、MCP サーバー（エージェントインターフェース）のいずれを使っても、 同じシナリオからビット単位で同一の run_sha256 が生成されます。

pear-sim doctor は、バージョン、パッケージの整合性、利用可能なオラクルバックエンド、浮動小数点の決定性プローブを報告します。2台のマシンで結果が異なる場合は、まず実行してください。

作業のレビュー：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 で実行されます。

---

実装上の注意

カーネルはイベント駆動型の区分線形方式です。2つのスイッチングイベントの間では、回路は修正節点解析によって構成される線形時不変システムとなります。イベント（スケジュールされたゲートエッジと自然なダイオード転流）は、時間刻みで飛び越すのではなく、正確な時刻として特定されます。これにより、コンデンサー電圧とインダクター電流の連続性が保たれ、実行が決定論的になり、定常状態、小信号平均化、感度解析を同じ正確な周期写像で行えます。詳細と主な選択の理由については、 アーキテクチャ と ADR をご覧ください。コンパイル済みコアは、同じモデル形式、CLI、MCP 契約を維持するオプションのバックエンドとして計画されています。

コントリビューション

コントリビューションを歓迎します。まず CONTRIBUTING.md をお読みください。要点は次のとおりです。 すべての変更は、公に利用できる数学、標準、オープンライセンスのソース、または独自の成果に基づく必要があります。プロプライエタリーコードや逆コンパイルしたコード、コンポーネントライブラリやデモモデルのコピー、商用ツールのモデルファイルは使用できません。すべてのバグ修正は、失敗するテストから始めます。また、新しい機能は、その主張の範囲を正直に示して登録します。

別途明示しない限り、このプロジェクトへの収録を意図して提出されたコントリビューションには、追加の条件を付さず Apache License 2.0 が適用されます。

製品名は PEARSim です。配布物と実行ファイルは pear-sim、インポートパッケージは pear_sim です。詳しくは ADR 0003 をご覧ください。

ライセンス

Copyright 2026 PEAR Power and the PEARSim contributors.

Apache License, Version 2.0 の下でライセンスされています。このライセンスは、ソフトウェアの出所を説明するために必要な場合を除き、PEAR Power または PEARSim の名称やロゴを使用する許可を与えるものではありません。サードパーティのデータセット、サンプル、オプションのバックエンドには、それぞれ独自の表示条件が適用されます。

このコードの再利用

PEARSim は、商用利用を含め、コピー、変更、再配布できます。その場合は、LICENSE と NOTICE ファイル、およびコピーした各ソースファイルの冒頭にある SPDX-License-Identifier／著作権ヘッダーを保持し、変更したファイルに印を付けてください。これは、手作業、スクリプト、AI コーディングエージェントのいずれで移動したコードにも同様に適用されます。

src/ と rust/ 配下の製品ソースファイルには、固定 GUID を含む PEARSim provenance mark 行も記載されています。この行は実行時には影響しませんが、コピーの追跡に役立ちます。ヘッダーの他の部分とともに保持してください。