simpy

SimPy

対象範囲

アクティブなエンティティがイベントを生成し、リソースを取り合うプロセスベースの離散イベントモデルにこのスキルを使用します。対象には、待ち行列、生産システム、ロジスティクス、ネットワーク、サービス業務、在庫、その他のイベント駆動型システムが含まれます。

SimPy はイベントスケジューラーとモデリング用プリミティブを提供します。科学的に妥当な概念モデル、入力分布、ウォームアップ期間、実行時間、反復回数、推定対象、因果解釈を選ぶことはありません。これらは SimPy API の動作ではなく、シミュレーション研究の方法論として扱ってください。

現行リリースとインストール

確認日：2026-07-23：

• 最新の安定版：SimPy 4.1.2。2026-05-24 に PyPI でリリースされ、ソースタグ 4.1.2 はコミット f4381649 を指しています。
• パッケージのメタデータでは Python >=3.8 が必要とされ、CPython 3.8〜3.14 と PyPy が分類されています。SimPy にランタイム依存関係はありません。
• 4.1.2 では Python 3.13/3.14 のサポートと、最新のインタープリター向けテスト修正が追加されています。
• 上流プロジェクトとこのスキルは MIT ライセンスです。

再現可能な環境を作成します。

uv venv --python 3.13
source .venv/bin/activate
uv pip install "simpy==4.1.2"
python -c "import importlib.metadata; print(importlib.metadata.version('simpy'))"

latest のドキュメントビルドに黙って置き換えないでください。未リリースの開発版について記述されている可能性があります。references/sources.md にあるバージョン指定付きの 4.1.2 のリンクを使用してください。

モデルのワークフロー

1. 目的と推定対象を定義します。 意思決定や問い、システムの境界、エンティティ、リソース、状態、出力、時間単位、終了イベントまたは定常状態の目標を明示します。
2. まず概念モデルを作成します。 仮定、分布、経路選択、優先順位、初期条件、省略したメカニズムを記録します。
3. ジェネレーターを実装します。 SimPy のプロセスは、イベントを生成する Python ジェネレーターです。ジェネレーターオブジェクトを env.process(...) に登録します。
4. 実行に上限を設けます。 本番実行ごとに、時間、エンティティ数、イベント数、反復回数に明示的な上限を設定します。無限プロセスを含むモデルで env.run() を呼び出してはいけません。
5. 乱数ストリームを分離します。 論理的に異なる確率的要因には個別のローカル RNG インスタンスを使用し、シードの一覧を保存します。
6. 意図を持って計測します。 対象の状態遷移後に観測し、時間加重区間を実行時間の終了時点で閉じ、モニタリングがイベントの順序を変えないことをテストします。
7. 検証と妥当性確認を行います。 決定論的なエッジケース、保存則、トレース、待ち行列の処理規律、解析的ベンチマークをテストします。目的に照らし、システムの証拠や専門家の知見と比較します。
8. 独立した反復を実行します。 同一実行内の相関するエンティティではなく、反復ごとの推定値から区間を求めます。
9. 限界を報告します。 初期化、未完了のエンティティ、実行時間、シード／ストリーム、精度、感度、妥当性確認の証拠を含めます。シミュレーション上の関連を因果関係の主張にすり替えてはいけません。

推論に関する主張を行う前に、references/simulation-methodology.md を読んでください。

最小限の上限付きモデル

import random
import simpy

HORIZON = 480.0
arrival_rng = random.Random(101)
service_rng = random.Random(202)
env = simpy.Environment()
server = simpy.Resource(env, capacity=2)
completed = []

def customer(arrival):
    with server.request() as request:
        yield request
        wait = env.now - arrival
        yield env.timeout(service_rng.expovariate(1 / 6.0))
    completed.append((env.now, wait))

def arrivals():
    for _ in range(10_000):  # Entity cap.
        delay = arrival_rng.expovariate(1 / 4.0)
        if env.now + delay >= HORIZON:
            return
        yield env.timeout(delay)
        env.process(customer(env.now))

env.process(arrivals())
env.run(until=HORIZON)

数値で指定した実行時間の区間は左閉右開です。480.0 にちょうどスケジュールされた通常イベントは処理されません。未完了のエンティティは、完了した観測として黙って扱わず、報告してください。

コアセマンティクス

環境と決定論的な順序付け

Environment は単一スレッドで動作します。キューはシミュレーション時刻、イベントの優先度、単調増加するイベント ID の順に並びます。そのため、同じ時刻かつ同じ優先度のイベントは、スケジュールされた順に FIFO で処理されます。モデルのプロセスは並行性を表現できますが、コールバックは逐次かつ決定論的に実行されます。

• env.now：単位のないシミュレーションクロックです。単位を 1 つ選び、記録してください。
• env.peek()：次のイベント時刻、または無限大を返します。
• env.step()：イベントを 1 つ処理します。キューが空の場合は EmptySchedule を発生させます。
• env.active_process：現在実行中のプロセスです。それ以外の場合は None です。
• env.run()：キューを空にします。繰り返し実行されるプロセスや終わらないプロセスがある場合は安全ではありません。

env.run(until=number) と env.run(until=event) は、境界での動作が同じではありません。

• 数値を指定すると、緊急停止イベントがスケジュールされ、指定した時刻ちょうどに発生する通常のイベントは処理されません。
• Event 条件を指定すると、その停止コールバックの実行時に、そのイベントの値が返されます。同じ時刻に発生する他のイベントの順序は、優先度とスケジュール順によって決まります。
• 4.1.2 では、Environment.step() は StopSimulation の後に残ったコールバックを、対象を再スケジュールすることで保持します。そのため、env.run(until=target) の後、値が返されていても、次に step()／run() を実行するまで target.processed が False のままになることがあります。実行後の完了判定に processed だけを使用しないでください。

references/events.md と references/monitoring.md を参照してください。

Event、Timeout、Process、Condition

• Event は「未発火」から「発火済み／スケジュール済み」、さらに「処理済み」へと一度だけ遷移します。succeed(value) または fail(exception) で、一度だけ発火させられます。
• Timeout は作成時に発火し、now + delay にスケジュールされます。手動で再度成功させることはできません。
• env.process(generator) は Process を作成します。ジェネレーターは yield したイベントの値を受け取って再開します。ジェネレーターから戻ると、Process はその戻り値で成功します。捕捉されなかった例外が発生すると、失敗します。
• AnyOf／a | b と AllOf／a & b は ConditionValue を返します。これはイベントオブジェクトをキー、その値を値とする、順序付きの辞書形式のマッピングです。元のイベントオブジェクトを使ってメンバーシップを確認してください。スカラー値が返ると想定しないでください。
• AnyOf は、条件を満たさなかったイベントをキャンセルしません。それらのリクエストを放棄する場合は、保留中のリソースリクエストを明示的にキャンセルしてください。通常のタイムアウトはスケジュールされたままです。

割り込み

process.interrupt(cause) は緊急の割り込みをスケジュールし、対象のジェネレーターに simpy.Interrupt を送出します。割り込みの可能性がある処理を yield する箇所でこれを捕捉し、interrupt.cause を確認して残りの処理を更新した後、再開するか、元のイベントを再度 yield するか、終了してください。

プロセスに割り込みをかけると、現在の対象からその再開コールバックが削除されますが、対象イベント自体はキャンセルされません。プロセスは、自身や終了済みのプロセスに割り込みをかけることはできません。references/process-interaction.md を参照してください。

共有リソース

種類	意味
Resource	FIFO 方式のセマフォのような使用枠
PriorityResource	数値の小さい優先度を先にする、キューに入ったリクエスト
PreemptiveResource	優先度キューに加えて、現在の利用者を任意でプリエンプト
Container	同種の数値レベル。容量／素材が足りない場合、put／get は待機
Store	Python オブジェクトを FIFO 方式で扱う
FilterStore	リクエストの述語を満たす、最初に利用可能になったアイテム
PriorityStore	比較可能なアイテムを優先度順に返す

リクエストにはコンテキストマネージャーを使用します。

def job(env, resource):
    with resource.request() as request:
        yield request
        yield env.timeout(3)

終了時には、取得済みのリクエストを解放し、まだ保留中のリクエストをキャンセルします。例外の巻き戻し中も同様です。保留中の put／get／リクエストを手動で保持する場合、割り込みやタイムアウトによってプロセスが処理を放棄するときは、cancel() を呼び出してください。

PreemptiveResource.request(priority=..., preempt=True) では、数値が小さいほど優先度が高くなります。プリエンプトされたプロセスには、Preempted オブジェクトを原因とする Interrupt が送られます。cause.by はプリエンプトした Process、cause.usage_since は使用開始時刻、cause.resource はリソースです。キュー内の優先度は preempt フラグより優先されます。プリエンプトするリクエストとしないリクエストを混在させる場合は、明示的にテストしてください。

ブロックされる操作、キューのルール、例については、references/resources.md を参照してください。

モニタリングとステップ実行

状態遷移時に、ドメイン固有の観測を明示的に行うことを推奨します。汎用的なリソースのモニタリングには、ラッパーまたはサブクラスから count、queue、level、items、put_queue、get_queue を調べられます。イベントのトレースでは、schedule() と step() が中心的なフックになります。

キューの測定はタイミングに左右されます。

• リクエストメソッドの呼び出し前の状態、呼び出し後の状態、許可コールバック、解放コールバックは、同じシミュレーション時刻でもそれぞれ異なる場合があります。
• サンプル平均は時間ではなく、イベントの観測値に重み付けします。左連続な状態経路の下側の面積を計算し、経過時間で割ってください。
• 初期サンプルと最終サンプルを追加し、分析期間の終点で最後の区間を閉じてください。
• env._queue、リソースの _env、モンキーパッチは実装の詳細です。SimPy のバージョンを固定し、計測処理を分離して、アップグレード後に回帰テストを実施してください。
• すべてのイベントをトレースすると、実行時間とメモリ使用量が増加します。トレース記録数に上限を設けてください。

scripts/resource_monitor.py と references/monitoring.md を使用してください。

リアルタイム実行

simpy.rt.RealtimeEnvironment(initial_time=0, factor=1.0, strict=True) は、シミュレーション単位 1 つを壁時計時間の factor 秒に対応付けます。strict モードでは、計算が遅れると step()／run() が RuntimeError を送出します。strict=False は遅延を許容しますが、タイミングの精度は回復しません。まず Environment でロジックを開発し、その後、プラットフォームを考慮した余裕のある許容誤差で、独立したタイミングテストを実行してください。references/real-time.md を参照してください。

同梱の安全な CLI

すべての CLI は、組み込みの固定キューモデルを使用するか、ローカルの成果物を要約します。不明な JSON キー、URL、シンボリックリンク、有限でない数値、サイズ超過の入力、上限のない時間／イベント／エンティティ／反復回数は拒否します。設定テキストの評価、ユーザーの Python コードの実行、プラグインのインポート、ネットワークサービスの呼び出しは一切行いません。

# Inspect all options.
python skills/simpy/scripts/bounded_queue_scenario.py --help
python skills/simpy/scripts/replication_runner.py --help
python skills/simpy/scripts/event_trace_summary.py --help
python skills/simpy/scripts/validate_simulation_config.py --help

# Deterministic built-in scenario.
python skills/simpy/scripts/bounded_queue_scenario.py

# Independent replications with replication-level Student-t intervals.
python skills/simpy/scripts/replication_runner.py

# Validate only; no simulation runs.
python skills/simpy/scripts/validate_simulation_config.py config.json

反復実行ツールは、反復回数が 1 回の区間を拒否します。その区間は、設定されたモデルのもとでのモンテカルロ不確実性を定量化するものであり、モデルの妥当性を検証するものでも、因果効果を特定するものでもありません。references/cli-guide.md を参照してください。

テスト

順序、境界時刻、条件、割り込み、すべてのリソース規則、保存則、イベント／エンティティ上限、シードの再現性、モニターの非干渉性について、決定論的な単体テストを使用してください。確率的テストを追加する場合は、固定シードを使った大まかな分布チェックにとどめ、厳密なサンプル推定値に依存する脆弱なテストは避けてください。

バイトコード成果物を生成せず、正確にバージョン固定された環境でスキルのテストスイートを実行してください。

PYTHONDONTWRITEBYTECODE=1 uv run --isolated --no-project \
  --python 3.13 --with "simpy==4.1.2" \
  python -m unittest discover -s tests/simpy -v

参考資料

• references/events.md — スケジューラー、ライフサイクル、実行境界、条件
• references/process-interaction.md — ジェネレーター、共有イベント、中断
• references/resources.md — Resource、Container、Store のすべてのバリエーション
• references/monitoring.md — 時間の重み付け、キューのタイミング、トレーシング、ステップ実行
• references/real-time.md — factor、厳密モード、ドリフト、タイミングテスト
• references/simulation-methodology.md — 反復、ウォームアップ、検証、CI
• references/cli-guide.md — スキーマ、境界、出力、安全な CLI の例
• references/sources.md — 日付付きの公式資料および一次資料