Движок кампаний

dispatchatlas.lab владеет воспроизводимой оркестрацией кампаний через провайдеров бенчмарков и реестры решателей. Он валидирует конфигурацию кампании, оценивает стоимость прогона, захватывает окружение runtime, персистирует контрольные точки, классифицирует сбои, и возобновляет неполные прогоны без дублирования завершённой работы.

Исполняемые примеры: examples/run_experiment.py ведёт smoke-пилот, абляцию правила-остановки, и развёртку чувствительности-к-зерну; examples/inspect_engine.py инспектирует host-осознанное определение размера workers и компонуемые критерии терминации.

Конфигурация

Кампании объявляют селекторы бенчмарков, 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. Раннер по умолчанию подключает упакованный smoke-провайдер бенчмарков и реестр решателей.

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.

Search campaign kinds

Showing 6 of 6 campaign kinds.

Campaign kinds — 6 rows, build-inlined from the public campaign-kind bundle.
Kind	Role
`comparative`	Compares at least two solvers under identical termination, equal computational budgets, and one equal per-algorithm tuning budget.
`ablation`	Isolates one named mechanism per configuration so analysis can attribute that mechanism's contribution.
`sensitivity`	Measures how results respond when one campaign input, such as the stopping policy, varies.
`hyperparameter`	Explores solver hyperparameter settings under a declared tuning budget.
`pilot`	Runs a smaller preparatory design that exercises the full campaign pipeline; the default kind.
`targeted`	Realizes 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 выбирает наибольший счёт workers, остающийся внутри бюджета ресурсов, ограничивает внутренний пул потоков каждого точного решателя так, что workers умножить на потоки никогда не пере-подписывает host, закрепляет окружение пула-потоков линейной-алгебры для предотвращения вложенных пулов, и откатывается к одному детерминированному worker для режимов sequential и replay. Каждый прогон принадлежит ровно одному worker и персистируется в свою собственную запись, индексируемую-по-run-id, так что агрегация — только-слияние: merge_only_aggregation сортирует прогоны по id и хеширует их строки хеша-содержимого, производя хеш кампании, который бит-стабилен независимо от порядка завершения workers.

Интерфейс командной-строки

Команда 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-снимок окружения выполнения на-уровне-рабочего-пространства (host, OS, Python, коммит и ветка репозитория, время захвата, число CPU, машина), перезаписываемый при каждой инициализации кампании

Каждая запись прогона content-hashed по своей детерминированной научной полезной нагрузке; настенное время и измерения ресурсов, хранимые на записи, — это происхождение и остаются вне хеша, так что верификация replay не затрагивается вариацией времени прогон-к-прогону. Контрольные точки перечисляют завершённые, неудачные, и ожидающие id прогонов, так что более поздний вызов resume() пропускает завершённую работу. Параллельные кампании персистируют завершённые записи результатов по мере завершения каждого worker и пишут финальную контрольную точку в конце кампании; resume всё ещё обнаруживает завершённые записи с диска перед планированием оставшейся работы.

Захват окружения

Штампы окружения кампании включают операционную систему, версию Python, тег платформы, версии пакетов, число CPU, факты машины/процессора, текущий Git-коммит, хеш конфигурации, и политику зёрен. Hostnames, учётные данные, и переменные окружения не захватываются.

Обработка сбоев

Ошибки конфигурации, домена, неподдерживаемой-возможности, и отсутствующей опциональной зависимости терминальны. Другие runtime-исключения восстановимы, пока не исчерпан бюджет повторов. Каждая неудачная попытка персистируется перед повтором или возобновлением.

Построитель доказательств

Используйте 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 деревьев исходников. Повышайте его выводы только через гейты выпуска и раскрытия.