캠페인 엔진

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 를 통해 명시적 솔버-별 시드 복제를 선언할 수 있으며, 결정적 솔버는 문제와 목표당 하나의 기록된 시드에 머뭅니다.

실행

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 단계에서 (확률적-솔버, 인스턴스) 셀당 최소 서른 번의 독립 실행이라는 통계-검정력 바닥을 강제하며, 무작위화 알고리즘의 신뢰할 수 있는 비교에 필요한 표본 크기에 관한 확립된 지침을 따릅니다 (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* 키 아래에 기록됩니다.

안전-최대-워커 토폴로지

probe_capacity 는 자원 예산 안에 머무는 가장 큰 워커 수를 선택하고, 각 정확 솔버의 내부 스레드 풀을 제한하여 워커 곱하기 스레드가 호스트를 결코 과잉-구독하지 않게 하며, 중첩 풀을 방지하기 위해 선형-대수 스레드-풀 환경을 고정하고, sequential 과 replay 모드에는 하나의 결정적 워커로 폴백합니다. 각 실행은 정확히 하나의 워커가 소유하고 자신의 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 — 완료 실행당 한 레코드, 여기서 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 수, 머신), 각 캠페인 초기화에서 덮어쓰임

각 실행 레코드는 그 결정적 과학 페이로드에 대해 content-hashed 됩니다; 레코드에 저장된 벽- 시간 타이밍과 자원 측정은 출처이며 해시 바깥에 머무르므로, replay 검증은 실행-대-실행 타이밍 변동에 영향받지 않습니다. 체크포인트는 완료·실패·대기 실행 id 를 나열하므로, 이후 resume() 호출은 완료 작업을 건너뜁니다. 병렬 캠페인은 각 워커가 끝날 때마다 완료 결과 레코드를 영속화하고 캠페인 종료 시 최종 체크포인트를 씁니다; 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-추적 소스 트리 바깥에 씁니다. 그 출력은 릴리스와 공개 게이트를 통해서만 승격하세요.