跳到内容
DispatchAtlas
搜索

活动引擎

dispatchatlas.lab 拥有跨基准提供者与求解器注册表的可复现活动编排。它验证活动配置、估计 运行成本、捕获运行时环境、持久化检查点、归类失败，并恢复未完成的运行而不重复已完成的工作。

可运行示例： examples/run_experiment.py 驱动一个烟雾试点、一个停止-规则消融，以及一个种子-敏感性扫描；examples/inspect_engine.py 检视主机-感知的 worker 规模设定与可组合的终止准则。

配置

活动声明基准选择器、求解器 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 声明显式的每-求解器种子重复，而确定性求解器保持每个问题与目标 一个已记录种子。

执行

将 CampaignRunner 与一个基准提供者、一个求解器注册表，以及 FileResultRepository 一起使用。默认 runner 接入捆绑的烟雾基准提供者与求解器注册表。

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)

执行模式：

模式行为
sequential一次运行一个确定性单元。
parallel使用至多 ResourceBudget.max_workers 个 worker 线程。
bounded-resource使用 max_workers 与 max_concurrent_runs 中较小者。
replay从已记录种子重新执行已完成的运行，并验证每个重算的内容哈希与持久记录相符；任何分歧即失败关闭。

活动种类与运行-计数策略

一个活动声明一个 kind。下面的目录表由实验-设计分类法生成，因此其总数可从行本身计数。

Generated from the experiment-design taxonomy: 6 campaign kinds.

Showing 6 of 6 campaign kinds.

Campaign kinds — 6 rows, build-inlined from the public campaign-kind bundle.
KindRole
comparativeCompares at least two solvers under identical termination, equal computational budgets, and one equal per-algorithm tuning budget.
ablationIsolates one named mechanism per configuration so analysis can attribute that mechanism's contribution.
sensitivityMeasures how results respond when one campaign input, such as the stopping policy, varies.
hyperparameterExplores solver hyperparameter settings under a declared tuning budget.
pilotRuns a smaller preparatory design that exercises the full campaign pipeline; the default kind.
targetedRealizes one report-specific experiment design over a deterministic benchmark subset.

运行-计数策略在 pilot 与 full 阶段强制一个每（随机-求解器，实例）单元至少三十次独立 运行的统计-功效下限，遵循关于可靠比较随机化算法所需样本量的既定指导 （Arcuri & Briand 2014）；确定性求解器运行一次。一个 smoke 活动标记低于-下限的计数而非拒绝它，从而快速检查保持廉价，而不静默地交付一个 功效不足的设计。

双停止协议

一个活动在固定-预算协议（迭代或时钟-时间）与固定-目标协议（在达到目标目标时终止）二者 之下报告每个随机-求解器结果。经 stopping_protocols 在一个活动上声明二者；每个单元在每个 协议下规划同时共享一个固定种子，从而两份报告直接可比。每次完成的运行在其诊断中以 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）。活动失败关闭，除非 它比较至少两个求解器并声明一个调优预算；该保证记录于计划元数据中的 fair_comparison* 键之下。

安全-最大-worker 拓扑

probe_capacity 选择保持在资源预算之内的最大 worker 计数，限制每个精确求解器的内部线程 池，使 worker 乘以线程绝不超额订阅主机，固定线性-代数线程-池环境以防止嵌套池，并对 sequential 与 replay 模式回退到一个确定性 worker。每次运行由恰好一个 worker 拥有并持久化 到其自己的按-run-id-索引记录，因此聚合是仅-合并：merge_only_aggregation 按 id 排序运行 并哈希其内容-哈希字符串，产生一个无论 worker 完成顺序如何皆位-稳定的活动哈希。

命令-行接口

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——每个已完成运行一条 记录，其中 idx 是从运行计划分配的零-基重复索引
  • results/{campaign_id}/{solver_id}/{benchmark_id}/failures/run_{idx}.attempt-{N}.json ——每个失败尝试一条记录
  • .checkpoints/{campaign_id}.json——活动检查点
  • logs/{campaign_id}_{timestamp}.log——每-活动执行日志
  • ENVIRONMENT.md——执行环境的工作区-级 Markdown 快照（主机、OS、Python、仓库提交与 分支、捕获时间、CPU 计数、机器），在每次活动初始化时被覆盖

每条运行记录在其确定性科学载荷上被内容-哈希；存储于记录上的时钟计时与资源测量是来源并 留在哈希之外，因此 replay 验证不受运行-到-运行计时变化的影响。检查点列出已完成、失败与 待处理运行 id，从而后续 resume() 调用跳过已完成工作。并行活动随每个 worker 完成而持久 化已完成结果记录，并在活动末尾写出最终检查点；resume 仍在调度剩余工作之前从磁盘发现已 完成记录。

环境捕获

活动环境戳记包含操作系统、Python 版本、平台标签、包版本、CPU 计数、机器/处理器事实、 当前 Git 提交、配置哈希，以及种子策略。主机名、凭据与环境变量不被捕获。

失败处理

配置、领域、不-支持-能力，以及缺失可选依赖错误是终端性的。其他运行时异常在重试预算耗尽 之前是可恢复的。每个失败尝试在重试或恢复之前被持久化。

证据构建器

使用 tools/build_campaign_evidence.py 从一份已记录配置构建候选基准目录、完整比较活动、 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-跟踪源树之外。仅通过发布与披露关卡提升其输出。