キャンペーンエンジン

dispatchatlas.lab は、ベンチマークプロバイダーとソルバーレジストリにまたがる再現可能な キャンペーンオーケストレーションを所有します。キャンペーン設定を検証し、実行コストを 見積もり、ランタイム環境をキャプチャし、チェックポイントを永続化し、失敗を分類し、完了した 作業を重複させずに不完全な実行を再開します。

実行可能な例: examples/run_experiment.py はスモークパイロット、停止-規則アブレーション、シード-感度スイープを駆動します; examples/inspect_engine.py はホスト-対応ワーカーサイジングと合成可能な終了基準を検査します。

設定

キャンペーンはベンチマークセレクター、ソルバー id、目的、シードポリシー、停止基準、開示 ラベル、リソース予算、リトライポリシー、実行モード、出力リポジトリを宣言します。

from dispatchatlas.core import DisclosureLabel, TerminationPolicy
from dispatchatlas.lab import (
    CampaignConfig,
    ExecutionMode,
    OutputPolicy,
    ResourceBudget,
)
 
config = CampaignConfig(
    campaign_id="smoke-campaign",
    benchmark_ids=("dispatchatlas-smoke",),
    solver_ids=("earliest-start", "ndso-core"),
    objectives=("makespan",),
    root_seed=20260527,
    seed_namespace="docs.campaign.smoke",
    stop=TerminationPolicy(max_iterations=5),
    output=OutputPolicy("experiments"),
    resources=ResourceBudget(max_workers=2, max_concurrent_runs=2),
    execution_mode=ExecutionMode.BOUNDED,
    disclosure_labels=(DisclosureLabel.PUBLIC,),
)

OutputPolicy.root_dir は実験ワークスペースルートであり、キャンペーン-ごとの ディレクトリではありません: 各実行はそのルート内の results/{campaign}/{solver}/{benchmark}/ の下に着地します。

検証は選択されたベンチマーク問題とソルバー id を決定的な実行 id に展開します。完全- キャンペーン計画はコスト見積もりのために dry-run できますが、実行は統計設計承認が記録 されるまでブロックされたままです。シードされた確率的ソルバーは solver_seed_replicates を介して明示的なソルバー-ごとのシードレプリケートを宣言でき、決定的ソルバーは問題と目的 ごとに 1 つの記録されたシードに留まります。

実行

CampaignRunner をベンチマークプロバイダー、ソルバーレジストリ、FileResultRepository とともに使用します。既定のランナーはバンドルされたスモークベンチマークプロバイダーと ソルバーレジストリを配線します。

from pathlib import Path
 
from dispatchatlas.lab import default_campaign_runner
 
runner = default_campaign_runner(Path("experiments"))
plan = runner.validate(config)
budget = runner.dry_run(plan)
index = runner.run(plan)

実行モード:

キャンペーン種別と実行-数ポリシー

キャンペーンは kind を宣言します。下のカタログ表は実験-設計分類法から生成されるので、 その合計は行そのものから数えられます。

実行-数ポリシーは、pilot と full 段階で（確率的-ソルバー、インスタンス）セルあたり 少なくとも 30 回の独立実行という統計-検出力フロアを強制し、ランダム化アルゴリズムの信頼 できる比較に必要なサンプルサイズに関する確立された指針に従います （Arcuri & Briand 2014）; 決定的ソルバーは 1 回実行 します。smoke キャンペーンはフロア-未満の数を拒否するのではなくフラグするので、素早い チェックは検出力不足の設計を静かに出荷することなく安価なままです。

デュアル停止プロトコル

キャンペーンは各確率的-ソルバー結果を、固定-予算プロトコル（反復または実時間）と固定- 目標プロトコル（目標目的で終了）の両方の下で報告します。stopping_protocols を介して 1 つのキャンペーンに両方を宣言します; 各セルは固定シードを共有しつつ各プロトコルの下で 計画されるので、2 つの報告は直接比較可能です。各完了実行は、その診断の stopping_protocol キーの下に自身のプロトコルを記録します。

from dispatchatlas.core import TerminationPolicy
from dispatchatlas.lab import StoppingProtocol, StoppingProtocolKind
 
protocols = (
    StoppingProtocol(
        name="fixed-budget",
        kind=StoppingProtocolKind.FIXED_BUDGET,
        stop=TerminationPolicy(max_iterations=200),
    ),
    StoppingProtocol(
        name="fixed-target",
        kind=StoppingProtocolKind.FIXED_TARGET,
        stop=TerminationPolicy(max_iterations=2000, target_objective=100.0),
    ),
)

公正な比較

comparative キャンペーンは各ソルバーを同一の終了、等しい計算予算、等しいアルゴリズム- ごとの TuningBudget の下で演習し、セル-ごとの固定シードを実行マニフェストに記録します。 ソルバー間でチューニング予算を均等化することは確立されたベンチマーキング実践に従っており、 それは不均等なチューニング努力が本来公正な比較を交絡させると主張します （Bartz-Beielstein et al. 2020）。キャンペーンは、 少なくとも 2 つのソルバーを比較しチューニング予算を宣言しない限りフェイルクローズします; 保証は計画メタデータの fair_comparison* キーの下に記録されます。

安全-最大-ワーカートポロジー

probe_capacity はリソース予算内に留まる最大のワーカー数を選択し、各厳密ソルバーの内部 スレッドプールをキャップしてワーカー掛けるスレッドがホストを決して過剰サブスクライブ しないようにし、ネストしたプールを防ぐために線形-代数スレッド-プール環境をピンし、 sequential と replay モードには 1 つの決定的ワーカーにフォールバックします。各実行は ちょうど 1 つのワーカーが所有し、自身の run-id-キー付きレコードに永続化されるので、集約は マージ-のみです: merge_only_aggregation は実行を id でソートしそのコンテンツ-ハッシュ 文字列をハッシュし、ワーカーの完了順序に関わらずビット-安定なキャンペーンハッシュを 生成します。

コマンド-ラインインターフェース

dispatchatlas-lab コマンドは、JSON 設定ファイルとして宣言されたキャンペーンを検証、 コスト計算、実行、再開、再生します:

dispatchatlas-lab validate --config examples/campaign-config.json
dispatchatlas-lab dry-run --config examples/campaign-config.json
dispatchatlas-lab run --config examples/campaign-config.json
dispatchatlas-lab resume --config examples/campaign-config.json
dispatchatlas-lab replay --config examples/campaign-config.json

チェックポイントと結果

ファイル-バックされたリポジトリは OutputPolicy.root_dir を実験ワークスペースルートとして 扱い、階層的な実行-レベルレイアウトを書きます:

• results/{campaign_id}/plan.json と results/{campaign_id}/environment.json
• results/{campaign_id}/{solver_id}/{benchmark_id}/run_{idx}.json — 完了実行ごとに 1 レコード、ここで idx は実行計画から割り当てられたゼロ-基底レプリケートインデックス
• results/{campaign_id}/{solver_id}/{benchmark_id}/failures/run_{idx}.attempt-{N}.json — 失敗試行ごとに 1 レコード
• .checkpoints/{campaign_id}.json — キャンペーンチェックポイント
• logs/{campaign_id}_{timestamp}.log — キャンペーン-ごとの実行ログ
• ENVIRONMENT.md — 実行環境のワークスペース-レベル Markdown スナップショット（ホスト、 OS、Python、リポジトリコミットとブランチ、キャプチャ時刻、CPU 数、マシン）、各 キャンペーン初期化で上書き

各実行レコードはその決定的科学ペイロード上で content-hashed されます; レコードに保存される 実時間タイミングとリソース測定は来歴でありハッシュの外に留まるので、replay 検証は実行- 対-実行のタイミング変動に影響されません。チェックポイントは完了・失敗・保留の実行 id を 列挙するので、後の resume() 呼び出しは完了作業をスキップします。並列キャンペーンは各 ワーカーが終わるごとに完了結果レコードを永続化しキャンペーン終了時に最終チェックポイントを 書きます; resume は残りの作業をスケジュールする前にディスクから完了レコードを発見します。

環境キャプチャ

キャンペーン環境スタンプはオペレーティングシステム、Python バージョン、プラットフォーム タグ、パッケージバージョン、CPU 数、マシン/プロセッサ事実、現在の Git コミット、設定 ハッシュ、シードポリシーを含みます。ホスト名、認証情報、環境変数はキャプチャされません。

失敗処理

設定、ドメイン、非対応-能力、欠落オプション依存のエラーは終端的です。他のランタイム例外は リトライ予算が尽きるまで回復可能です。各失敗試行はリトライまたは再開の前に永続化されます。

エビデンスビルダー

tools/build_campaign_evidence.py を使い、1 つの記録された設定から候補ベンチマーク カタログ、完全な比較キャンペーン、NDSO アブレーション、感度チェック、エビデンスバンドル、 ポータルデータセットを構築します:

uv run python tools/build_campaign_evidence.py `
  --output-root .\experiments `
  --problem-count-per-profile 30 `
  --stochastic-seeds 10 `
  --campaign-suffix local

ビルダーは、カタログ物質化、キャンペーン計画、実行、分析、バンドルエクスポート、レポート 書き込みのフェーズ進捗を stderr に出力します。ビルダーは生成されたエビデンスを意図的に Git-追跡ソースツリーの外に書きます。その出力はリリースと開示のゲートを通じてのみ昇格して ください。