spice

SPICE シミュレーションスキル

kicad スキルの回路図アナライザーが検出したサブ回路の SPICE テストベンチを自動生成して実行します。ngspice、LTspice、Xyce に対応しており、シミュレーターは自動検出されます。計算値（フィルター周波数、分圧比、オペアンプのゲイン）を実際のシミュレーション結果と照合して検証し、構造化レポートを生成します。

このスキルは、一般的なシミュレーションのワークフローを逆転させます。シミュレーションソースの作成と解析の設定をユーザーに要求するのではなく（KiCad ユーザーの約 2.5％しか行っていません）、アナライザーが検出したサブ回路から、対象を絞ったテストベンチを自動生成します。

関連スキル

スキル	目的
kicad	回路図／PCB の解析 — このスキルが使用するアナライザー JSON を生成します
digikey	ビヘイビアモデル用のパラメトリック仕様、データシートのダウンロード
mouser	パラメトリック仕様（副次ソース）、データシートのダウンロード
lcsc	パラメトリック仕様（認証不要）、データシートのダウンロード
element14	パラメトリック仕様（海外向け）、データシートのダウンロード
emc	EMC の事前適合性評価 — このスキルのシミュレーター基盤を使用して、SPICE で拡張した PDN インピーダンスおよび EMI フィルター解析を行います

引き継ぎのガイダンス： kicad スキルの analyze_schematic.py は、フラットな findings[] 配列にサブ回路の検出結果を含む解析 JSON を生成します（detector フィールドで絞り込みます）。このスキルはその JSON を読み取り、シミュレーション可能なサブ回路の SPICE テストベンチを生成し、検出したシミュレーター（ngspice／LTspice／Xyce）を実行して、構造化された検証レポートを生成します。必ず最初に回路図アナライザーを実行してください。設計レビューでは、アナライザーの実行後、最終レポートの作成前にシミュレーションを実行してください。シミュレーション結果はレポートの検証セクションに記載します。emc スキルは、このスキルのシミュレーターバックエンドを再利用して、SPICE で拡張した PDN インピーダンスおよび EMI フィルターの挿入損失チェックを行います。ngspice が利用可能な場合、--spice-enhanced フラグによって EMC スキルのこれらのチェックが自動的に有効になります。

要件

• SPICE シミュレーター — 次のいずれか（自動検出され、最初に見つかったものを使用します）：
  • ngspice — sudo apt install ngspice（Linux）／brew install ngspice（macOS）／ngspice.sourceforge.io（Windows）。最も一般的な選択肢です。
  • LTspice — analog.com/ltspice から無料で入手できます。Windows で広く使われており、Linux では wine 経由で動作します。
  • Xyce — xyce.sandia.gov から入手できます。大規模回路向けの並列 SPICE です。
  • --simulator ngspice|ltspice|xyce または SPICE_SIMULATOR 環境変数で指定できます。
• Python 3.10 以降 — 標準ライブラリのみを使用し、pip の依存関係はありません
• 回路図アナライザーの JSON — analyze_schematic.py --output で生成します

シミュレーターがインストールされていない場合は、シミュレーションを問題なくスキップし、その旨をレポートに記載してください。シミュレーターがないことをエラーとして扱わないでください。これは任意の機能強化です。

ワークフロー

ステップ 1：回路図アナライザーを実行する

python3 <kicad-skill-path>/scripts/analyze_schematic.py design.kicad_sch --analysis-dir analysis/

ステップ 2：SPICE シミュレーションを実行する

--analysis-dir analysis/ を指定します。スクリプトはマニフェストの現在の実行から schematic.json を自動的に解決し、同じ実行フォルダーに spice.json を書き込みます。また、中間生成物の .cir／.raw ファイルは、デフォルトで <run>/spice_work/ に保存します。

# Recommended: auto-resolve schematic + write spice.json into the current run
python3 <skill-path>/scripts/simulate_subcircuits.py --analysis-dir analysis/

# Explicit form — positional or --schematic path
python3 <skill-path>/scripts/simulate_subcircuits.py analysis.json --output sim_report.json

# Simulate specific types only
python3 <skill-path>/scripts/simulate_subcircuits.py --analysis-dir analysis/ --types rc_filters,voltage_dividers

# Keep simulation files for debugging (default: <run>/spice_work/ when --analysis-dir is set, else a temp dir)
python3 <skill-path>/scripts/simulate_subcircuits.py --analysis-dir analysis/ --workdir ./spice_runs

# Increase timeout for complex circuits (default: 5s per subcircuit)
python3 <skill-path>/scripts/simulate_subcircuits.py --analysis-dir analysis/ --timeout 10

# Omit file paths from output (cleaner for reports)
python3 <skill-path>/scripts/simulate_subcircuits.py --analysis-dir analysis/ --compact

ステップ 2b（任意）：PCB の寄生成分を考慮したシミュレーション

回路図と PCB の両方がある場合は、アナログ回路の結果をより正確にするため、寄生成分を注釈したシミュレーションを実行します。

# Analyze PCB with full trace segment detail
python3 <kicad-skill-path>/scripts/analyze_pcb.py design.kicad_pcb --full --output pcb.json

# Extract parasitic R/L/C from PCB geometry
python3 <skill-path>/scripts/extract_parasitics.py pcb.json --output parasitics.json

# Run simulation with PCB parasitics injected into testbenches
python3 <skill-path>/scripts/simulate_subcircuits.py analysis.json --parasitics parasitics.json --output sim_report.json

--parasitics を指定すると、テストベンチに部品間の配線抵抗とビアのインダクタンスが含まれます。レポートには寄生成分による影響が表示されます。たとえば、「48mΩ の配線抵抗により、RC フィルターの fc が 0.3％低下」のように示されます。

寄生成分を考慮したシミュレーションを使用する場合： 高インピーダンスのフィードバック回路（100kΩ 超）、LC フィルターや RF マッチング回路、長いアナログ信号配線、または配線インダクタンスが重要となる高周波回路を含む設計では、使用を検討してください。インピーダンスの低い電源レギュレーションを備えた一般的なデジタル設計では、理想シミュレーションで十分です。

ステップ 2c（オプション）：モンテカルロ公差解析

サブ回路ごとに、許容差の範囲内で部品の値をランダム化して N 回シミュレーションを実行します。統計的な分布と感度解析をレポートします。どの部品が出力のばらつきに最も影響しているかを確認できます。

# Run 100 Monte Carlo trials per subcircuit
python3 <skill-path>/scripts/simulate_subcircuits.py analysis.json --monte-carlo 100 --output sim_report.json

# Use uniform distribution (conservative worst-case envelope) instead of Gaussian
python3 <skill-path>/scripts/simulate_subcircuits.py analysis.json --monte-carlo 100 --mc-distribution uniform

# Set random seed for reproducibility (default: 42)
python3 <skill-path>/scripts/simulate_subcircuits.py analysis.json --monte-carlo 100 --mc-seed 123

公差の取得元： まず、部品の値の文字列から公差を抽出します（例：「680K 1%」→ 1%、「22uF/6.3V/20%/X5R」→ 20%）。値の文字列に公差が指定されていない場合は、デフォルト値を使用します。抵抗器は 5%、コンデンサは 10%、インダクタは 20% です。

出力： 各シミュレーション結果に tolerance_analysis セクションが追加され、次の情報が含まれます。

• statistics：主要な出力指標（fc、Vout、ゲインなど）の平均、標準偏差、最小値、最大値、3 シグマ範囲、ばらつき率
• sensitivity：部品ごとの寄与率。どの部品がばらつきを支配しているかを示します（例：「C3（公差 10%）は fc のばらつきの 68% に寄与し、R5（公差 5%）は 32% に寄与」）
• components：公差を設定できる部品の一覧と、解決された公差値

モンテカルロを使用する場面： フィードバックネットワーク（レギュレータの出力精度）、高精度の分圧器、仕様限界に近い RC／LC フィルター、公差の積み重ねによって動作が許容範囲を外れる可能性がある回路で使用します。N=100 の場合、シミュレーション 1 回あたり約 5～50 ミリ秒として、サブ回路ごとに約 0.5～5 秒かかります。

ステップ 3：結果を解釈してユーザーに提示する

JSON レポートを読み、結果を設計レビューに反映します。詳しくは、以下の「結果の解釈」および「ユーザーへの提示」のセクションを参照してください。

シミュレーション対象

スクリプトは、解析ツールの findings[] 配列からサブ回路を選択します（検出器の種類ごとにグループ化されています）。すべての検出結果がシミュレーション可能なわけではありません。意味のある結果を生成できない構成（コンパレータ、オープンループのオペアンプ、アクティブ発振器など）はスキップされます。

検出器	解析	測定内容	モデルの忠実度	信頼性
rc_filters	AC スイープ	-3dB 周波数、fc での位相	正確（理想的な受動部品）	高 — 数学的に正確
lc_filters	AC スイープ	共振周波数、Q 値、帯域幅	ほぼ正確（理想的な L/C + ESR）	高 — ESR による Q の誤差は小さい
voltage_dividers	DC 動作点	出力電圧、誤差率	正確（理想的な受動部品）	高 — 負荷なし
feedback_networks	DC 動作点	FB ピン電圧、レギュレータの Vout	正確（理想的な受動部品）	高 — power_regulators の相互参照
opamp_circuits	AC スイープ	ゲイン、-3dB 帯域幅	部品ごとのモデルまたは理想モデル	振る舞いモデルでは高、理想モデルでは中
crystal_circuits	AC インピーダンス	負荷容量の検証	近似（汎用 BVD）	中
transistor_circuits	DC スイープ	しきい値電圧、オン状態電流	近似（汎用 FET／BJT）	中
current_sense	DC 動作点	50mV／100mV の降下時の電流	正確（理想抵抗器）	高
protection_devices	DC スイープ	ダイオードの有無、クランプ開始点	近似（汎用ダイオード）	低
decoupling_analysis	AC インピーダンス	PDN インピーダンスの特性	正確 + ESR の推定値	受動部品については高
power_regulators	DC 動作点	フィードバック分圧器の Vout	正確（理想的な受動部品）	高
rf_matching	AC スイープ	整合ネットワークの共振	正確（理想的な L/C）	高
bridge_circuits	DC スイープ	FET スイッチングの検証	近似（汎用モデル）	中
snubber_circuits	AC インピーダンス	スナバの減衰周波数	正確（理想的な R/C）	高
rf_chains	ゲイン予算	ステージごとのゲイン／損失の推定	ヒューリスティック	低 — 役割ベース
bms_systems	DC 動作点	セルバランス抵抗器の検証	正確	高
inrush_analysis	過渡解析	突入電流のプロファイル	近似	中

シミュレーション対象外

• コンパレーター／オープンループのオペアンプ — 検証するフィードバックネットワークがないため、スキップします
• 自励発振器 — 単体で動作するモジュールであり、外部から検証するものがありません
• レギュレーターの制御ループ安定性 — 補償器の完全なモデルが必要です（動作モデルでカバーするのは DC フィードバックのみです）
• レベルシフターの FET — 2 つの FET を一緒にモデル化する必要があるため、スキップします
• ハイサイド電源スイッチ — ソースとドレインの両方が電源レールに接続されているため、負荷のコンテキスト全体が必要です
• ヒューズとバリスタ — メーカー固有のモデルが必要です
• 値が解析されていない部品 — parse_value() で R/C/L の値を抽出できない場合、検出をスキップします

出力形式

{
  "summary": {"total": 5, "pass": 3, "warn": 1, "fail": 0, "skip": 1},
  "simulation_results": [
    {
      "subcircuit_type": "rc_filter",
      "components": ["R5", "C3"],
      "filter_type": "low-pass",
      "status": "pass",
      "expected": {"fc_hz": 15915, "type": "low-pass"},
      "simulated": {"fc_hz": 15878, "phase_at_fc_deg": -0.78},
      "delta": {"fc_error_pct": 0.23},
      "cir_file": "/tmp/spice_sim_xxx/rc-filter_R5_C3.cir",
      "log_file": "/tmp/spice_sim_xxx/rc-filter_R5_C3.log",
      "elapsed_s": 0.004
    }
  ],
  "workdir": "/tmp/spice_sim_xxx",
  "total_elapsed_s": 0.032,
  "simulator": "ngspice"
}

ステータス値とその意味：

ステータス	意味	対応
pass	シミュレーションで、アナライザーの検出結果が許容範囲内であることを確認できました	確認済みとして報告します。対応は不要です。
warn	シミュレーションで、軽微なずれ、モデルの制約、またはエッジケースなど、注意すべき点が示されました	状況を添えて報告します。「warn」は、実際に存在するものの軽微な問題を示すことがよくあります（例：理想オペアンプモデルによるわずかなゲイン誤差）。
fail	シミュレーション結果がアナライザーの結果と矛盾しています — 周波数が異なる、大きなゲイン誤差がある、予期しない動作をする	調査します。実際の設計上の問題、アナライザーによるトポロジーの誤検出、またはテストベンチ生成のバグの可能性があります。.cir ファイルとログを確認してください。
skip	シミュレーションを実行できませんでした — データ不足、未対応の構成、シミュレーターエラー	レポートに記載します。理由を note フィールドで確認してください。

結果の解釈

受動回路（RC フィルター、LC フィルター、分圧器）

これらのシミュレーションでは理想的な部品モデルを使用するため、シミュレーション結果は数学的に厳密です。アナライザーの計算値から大きく（>1%）ずれている場合、次のいずれかにバグがあることを示しています：

• アナライザーのトポロジー検出（例：どのネットが入力で、どのネットが出力かを誤認した）
• テストベンチの生成（トポロジーの再構築エラー）
• アナライザーの値の解析（部品値の解析誤り）

実際のプロジェクトでテストしたところ、受動回路のシミュレーション誤差は一貫して <0.3% であり、アナライザーの計算が正確であることを実質的に確認できました。ここでの「pass」は、計算されたカットオフ周波数、共振周波数、または分圧比が正確であることを意味します。

これらのシミュレーションでは分からないこと： 実際の回路がこのように動作するかどうかです。シミュレーションでは、後段の負荷、PCB の寄生成分、温度の影響を考慮しない、理想的な独立サブ回路を使用します。1.65V で完全にシミュレーションできる分圧器でも、入力インピーダンスの高い ADC に負荷されると実際には 1.62V になる場合があります。しかし、この負荷の影響は実際の回路動作であり、アナライザーのエラーではありません。

オペアンプ回路

認識されている部品（ルックアップテーブルにある一般的なオペアンプ約 100 種類）については、このスキルは GBW、スルーレート、入力オフセット、出力振幅が正しい部品ごとの動作モデルを使用します。認識されていない部品については、理想モデル（Aol=1e6、GBW=10MHz）にフォールバックします。

レポートの model_note フィールドに、使用されたモデルが示されます：

• "LM358 behavioral (lookup:LM358, GBW=1.0MHz)" — 部品ごとのモデルで、帯域幅の結果は正確です
• "ideal opamp (Aol=1e6, GBW~10MHz)" — フォールバックであり、帯域幅の結果は概算です

動作モデルを使用すると、シミュレーションで帯域幅の制約が正しく反映されます。ゲイン=-100 の LM358 の帯域幅は約 10 kHz（GBW が 1 MHz であることから正しい値）ですが、理想モデルでは誤解を招く約 100 kHz という結果が報告されます。

動作モデルがあるオペアンプでは、ゲイン帯域幅の制約に関する警告は参考情報です。部品の GBW が回路に制約を与える箇所を示しています。これらは設計上有益な知見であり、シミュレーションエラーではありません。

水晶振動子回路

水晶振動子のシミュレーションでは、負荷コンデンサーの選定を検証します。実効負荷容量が、水晶振動子に指定された CL に対して妥当な範囲にあるかを確認します。特定の水晶振動子のデータではなく、一般的なパラメーターを使用した汎用のバターワース・ファン・ダイク等価回路モデルを使用します。主な目的は、負荷コンデンサーの欠落や大きな選定ミスを検出することであり、周波数を正確に予測することではありません。

シミュレーションが失敗またはスキップされた場合

まず note フィールドを確認してください。よくある原因は次のとおりです。

Note	Cause	Fix
「-3dB 周波数を測定できませんでした」	AC スイープ範囲に -3dB ポイントが含まれていません	フィルターの fc が非常に低い（<0.1 Hz）か、非常に高い（>100 MHz）か確認してください
「AC 測定に失敗しました」	テストベンチのトポロジーエラーです。回路が収束しません	.cir ファイルに浮遊ノードや接続の欠落がないか確認してください
「テストベンチの生成に失敗しました：KeyError」	アナライザーの検出に必要なフィールドがありません	アナライザーの JSON を確認してください。検出結果が不完全な可能性があります
「ngspice/ltspice/xyce が失敗しました：...」	シミュレーターのエラーです	.log ファイルでエラーメッセージを確認してください

デバッグする際は、--workdir を使用してシミュレーションファイルを保持してください。.cir ファイルは標準的な SPICE ネットリストで、手動で実行することも（ngspice -b file.cir）、LTspice/Xyce で開くこともできます。.log ファイルには、シミュレーターの標準出力／標準エラー出力が含まれています。

ユーザーへの結果の提示

設計レビュー報告書にシミュレーション結果を含める際は、次のパターンに従ってください。

シミュレーションに合格した場合（信頼性を高める情報）

### RC Filter R5/C3 (fc=15.9kHz lowpass) -- Confirmed
Simulated fc=15.9kHz, <0.3% from calculated. Phase=-45 deg at fc as expected.

合格した結果は簡潔にまとめてください。アナライザーがすでに報告した内容を確認するものです。数が多い場合はまとめてください。

警告の場合（状況の説明が必要）

### Opamp U4A (inverting gain=-10)
Simulated gain=20.0dB at 1kHz, matching expected -10x. Bandwidth 98.8kHz
(ideal model). Note: LM358 GBW is ~1MHz, so actual bandwidth would be
~100kHz — verify signal frequency stays below 85kHz for <1dB gain error.

失敗の場合（調査が必要）

### RC Filter R12/C8 -- MISMATCH
Simulated fc=3.2kHz vs expected 15.9kHz (80% deviation). This likely indicates
the analyzer misidentified the filter topology — R12 may be serving a different
purpose (pull-up, not series filter element). Manually verify the circuit
around R12/C8 in the schematic.

スキップの場合（未確認の範囲を明記）

### Crystal Y1 (32.768kHz) -- Not simulated
Active oscillator module — no external load caps to validate.

シミュレーションセクションの要約行

## Simulation Verification (4 pass, 1 warn, 0 fail, 1 skip)
Verified 5 subcircuits in 0.03s. All passive circuits confirmed.
One opamp result requires interpretation (see U4A above).

モデルの精度に関するリファレンス

使用されている動作モデル、その精度範囲、および既知の制限について詳しくは、references/simulation-models.md をお読みください。次の場合は、このリファレンスを参照してください。

• ユーザーがシミュレーション結果の精度に疑問を呈した場合
• オペアンプまたは水晶振動子のシミュレーションで予想外の動作が見られる場合
• 「理想モデル」の意味を具体的に説明する必要がある場合

スクリプトのリファレンス

Script	Purpose
scripts/simulate_subcircuits.py	メインオーケストレーター — CLI エントリーポイント。JSON を読み込み、テストベンチを生成し、シミュレーターを実行してレポートを作成します
scripts/spice_templates.py	検出器の種類ごとのテストベンチジェネレーター — 検出器名ごとに 1 つの関数を用意します
scripts/spice_models.py	動作モデルの定義（理想オペアンプ、汎用半導体）、ネットのサニタイズ、工学表記のフォーマット
scripts/spice_results.py	シミュレーション出力の解析と、合格／警告／失敗／スキップの判定ロジックによる種類ごとの評価
scripts/spice_simulator.py	シミュレーターのバックエンド — ngspice、LTspice、Xyce の自動検出とバッチ実行
scripts/spice_part_library.py	約 100 種類の一般的なオペアンプ、LDO、コンパレーター、電圧リファレンス、水晶振動子ドライバーの電気仕様のルックアップテーブル
scripts/spice_model_generator.py	仕様辞書からパラメーター化された動作 .subckt を生成
scripts/spice_model_cache.py	回路図と同じ階層にある spice/models/ 内のプロジェクトローカルモデルキャッシュ
scripts/spice_spec_fetcher.py	販売代理店 API（LCSC、DigiKey、element14、Mouser）、構造化されたデータシート抽出、および PDF の正規表現を使用したパラメーター仕様の照会
scripts/extract_parasitics.py	PCB 解析 JSON から配線の R、ビアの L、結合 C を計算

部品ごとの動作モデル

アナライザーが認識済みのMPN（LM358、TL072、MCP6002など）を持つオペアンプを検出すると、このスキルは汎用の理想オペアンプではなく、部品ごとの動作モデルを使用します。このモデルには、部品のデータシートに記載された実際のGBW、スルーレート、入力オフセット、出力振幅が反映されます。

モデル解決の優先順位：

1. プロジェクトキャッシュ（<project>/spice/models/）— 以前に解決されたモデル
2. v1.4の型付きデータシート情報 — datasheetsスキルのlookup(mpn, cache_dir=<project>/datasheets/extracted)を介して取得します。opamp.gbw、opamp.slew_rateなどを、信頼度ゲート付きのSpecValueインスタンスとして含むDatasheetFactsを返します。利用可能な場合に推奨されるソースです。
3. 販売代理店のAPI仕様 — LCSC（認証不要）、DigiKey、element14、Mouserに問い合わせ、実際のパラメトリックデータを取得します
4. v1.3の構造化データシート抽出 — <project>/datasheets/extracted/から抽出済み仕様を読み込みます（旧形式の辞書型JSONで、品質スコアを付与）。v1.4のキャッシュで見つからない場合にも引き続き参照される、二重読み込みの互換パスです。
5. データシートPDFの正規表現抽出 — <project>/datasheets/から読み込み、テキストパターンマッチングで抽出します（最後の手段）
6. 組み込み検索テーブル — オフライン時のフォールバックとして、一般的な部品約100種類を収録
7. 理想モデルへのフォールバック — どのソースでもMPNを認識できない場合に使用します

レポートのmodel_noteフィールドには、使用されたモデルが示されます。例："LM358 behavioral (lookup:LM358, GBW=1.0MHz)"と"ideal opamp (Aol=1e6, GBW~10MHz)"。

モデルは、回路図ファイルと同じ場所にあるspice/ディレクトリにプロジェクト単位でキャッシュされます（datasheets/と同じ方式です）。これにより、モデルを設計データと同じ場所に保管でき、基板のリビジョンやサブプロジェクトにも自然に対応できます。

既知の制限事項

• 分圧器は無負荷でシミュレーションされます。 アナライザーが計算する比率は、負荷を考慮しないR_bot/(R_top+R_bot)です。負荷抵抗を追加すればシミュレーションはより「現実的」になりますが、アナライザーの計算値との比較で誤った「エラー」が発生します。この機能の目的は計算を検証することであり、回路全体をモデル化することではありません。
• LCフィルターのQ値には、推定されたインダクターのESRが使われます。 インダクターのデフォルトQ値は100と仮定されます。実際のインダクターのQ値は、10（電源用インダクター）から300以上（RF用インダクター）までさまざまです。Q値にかかわらず、共振周波数は正確です。
• オペアンプの電源レールはネット名から推定されます。 電源ネットに電圧がラベル付けされていない場合、デフォルトで+/-5Vになることがあります。VCCのみが見つかった場合は単電源設計と判断されます（VEEはデフォルトで0Vになります）。
• 部品ごとのモデルは一般的な部品約100種類に対応しています。 一般的でないオペアンプやLDOは、理想モデルにフォールバックします。spice_part_library.pyに項目を追加すれば、検索テーブルを拡張できます。
• GBWを現実的に設定した高利得オペアンプ回路では、帯域幅の制限により、1 kHzの測定点で予想より低い利得が示されることがあります。これは物理的に正しい動作です（モデルがGBWの制限を正しく反映しています）が、利得を正確に比較するには、より低い周波数で測定する必要がある場合があります。
• アナライザーからのネット名が__unnamed_Nになることがあります。 これはラベルのない配線に対するKiCad内部のネット名です。シミュレーションでは正しく機能しますが、.cirファイルの可読性が低下します。