Mesin kampanye

dispatchatlas.lab memiliki orkestrasi kampanye reproduktibel lintas penyedia benchmark dan registry solver. Ia memvalidasi konfigurasi kampanye, mengestimasi biaya eksekusi, menangkap lingkungan runtime, mempersisten checkpoint, mengklasifikasi kegagalan, dan melanjutkan eksekusi yang tidak lengkap tanpa menduplikasi pekerjaan yang selesai.

Contoh yang dapat dijalankan: examples/run_experiment.py menggerakkan pilot asap, ablasi aturan-berhenti, dan sapuan sensitivitas-benih; examples/inspect_engine.py menginspeksi penentuan ukuran worker sadar-host dan kriteria terminasi yang dapat-dikomposisi.

Konfigurasi

Kampanye mendeklarasikan selektor benchmark, id solver, tujuan, kebijakan benih, kriteria berhenti, label pengungkapan, anggaran sumber daya, kebijakan percobaan-ulang, mode eksekusi, dan sebuah repositori keluaran.

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 adalah akar ruang kerja eksperimen, bukan direktori per-kampanye: setiap eksekusi mendarat di bawah results/{campaign}/{solver}/{benchmark}/ di dalam akar itu.

Validasi memperluas masalah benchmark yang dipilih dan id solver menjadi id eksekusi deterministik. Rencana kampanye-penuh dapat di-dry-run untuk estimasi biaya, tetapi eksekusi tetap terblokir sampai persetujuan desain statistik dicatat. Solver stokastik ber-benih dapat mendeklarasikan replika benih per-solver eksplisit via solver_seed_replicates, sementara solver deterministik tetap pada satu benih tercatat per masalah dan tujuan.

Eksekusi

Gunakan CampaignRunner dengan penyedia benchmark, registry solver, dan FileResultRepository. Runner default mengkabeli penyedia benchmark asap terbundel dan registry solver.

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)

Mode eksekusi:

Mode	Perilaku
`sequential`	Menjalankan satu unit deterministik pada satu waktu.
`parallel`	Menggunakan hingga `ResourceBudget.max_workers` utas worker.
`bounded-resource`	Menggunakan yang lebih kecil dari `max_workers` dan `max_concurrent_runs`.
`replay`	Mengeksekusi-ulang eksekusi yang selesai dari benih tercatat dan memverifikasi bahwa setiap hash konten yang dihitung-ulang cocok dengan rekaman yang dipersisten; gagal-menutup pada divergensi apa pun.

Jenis kampanye dan kebijakan jumlah-eksekusi

Sebuah kampanye mendeklarasikan sebuah kind. Tabel katalog di bawah dihasilkan dari taksonomi desain-eksperimen, sehingga totalnya dapat dihitung dari baris itu sendiri.

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.

Kebijakan jumlah-eksekusi menegakkan lantai daya-statistik berupa setidaknya tiga puluh eksekusi independen per sel (solver-stokastik, instance) pada tahap pilot dan full, mengikuti panduan mapan tentang ukuran sampel yang diperlukan untuk perbandingan andal algoritma teracak (Arcuri & Briand 2014); solver deterministik berjalan sekali. Sebuah kampanye smoke menandai jumlah di-bawah-lantai alih-alih menolaknya, sehingga pemeriksaan cepat tetap murah tanpa diam-diam mengapalkan desain ber-daya-kurang.

Protokol berhenti dual

Sebuah kampanye melaporkan setiap hasil solver-stokastik di bawah baik protokol anggaran-tetap (iterasi atau waktu-dinding) maupun protokol target-tetap (terminasi pada tujuan target). Deklarasikan keduanya pada satu kampanye melalui stopping_protocols; setiap sel direncanakan di bawah setiap protokol sambil berbagi satu benih tetap, sehingga kedua laporan langsung dapat-dibandingkan. Setiap eksekusi yang selesai mencatat protokolnya dalam diagnostiknya di bawah kunci 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),
    ),
)

Perbandingan adil

Sebuah kampanye comparative melatih setiap solver di bawah terminasi identik, anggaran komputasi setara, dan satu TuningBudget per-algoritma setara, dengan benih tetap per-sel yang dicatat dalam manifes eksekusi. Menyetarakan anggaran tuning lintas solver mengikuti praktik benchmarking mapan, yang berpendapat bahwa upaya tuning tak-setara mengaburkan perbandingan yang seharusnya adil (Bartz-Beielstein et al. 2020). Kampanye gagal-menutup kecuali ia membandingkan setidaknya dua solver dan mendeklarasikan anggaran tuning; jaminan dicatat dalam metadata rencana di bawah kunci fair_comparison*.

Topologi max-worker aman

probe_capacity memilih jumlah worker terbesar yang tetap di dalam anggaran sumber daya, membatasi pool utas internal setiap solver eksak sehingga worker dikali utas tidak pernah melebih-langganani host, menyematkan lingkungan pool-utas aljabar-linear untuk mencegah pool bersarang, dan jatuh-kembali ke satu worker deterministik untuk mode sequential dan replay. Setiap eksekusi dimiliki oleh tepat satu worker dan dipersisten ke rekamannya sendiri yang berkunci-run-id, sehingga agregasi adalah hanya-gabung: merge_only_aggregation mengurutkan eksekusi berdasarkan id dan meng-hash string hash-konten-nya, menghasilkan hash kampanye yang bit-stabil terlepas dari urutan penyelesaian worker.

Antarmuka baris-perintah

Perintah dispatchatlas-lab memvalidasi, menghitung biaya, menjalankan, melanjutkan, dan memutar-ulang sebuah kampanye yang dideklarasikan sebagai berkas konfigurasi 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

Checkpoint dan hasil

Repositori berdukungan-berkas memperlakukan OutputPolicy.root_dir sebagai akar ruang kerja eksperimen dan menulis tata letak tingkat-eksekusi hierarkis:

results/{campaign_id}/plan.json dan results/{campaign_id}/environment.json
results/{campaign_id}/{solver_id}/{benchmark_id}/run_{idx}.json — satu rekaman per eksekusi selesai, di mana idx adalah indeks replika berbasis-nol yang ditetapkan dari rencana eksekusi
results/{campaign_id}/{solver_id}/{benchmark_id}/failures/run_{idx}.attempt-{N}.json — satu rekaman per percobaan gagal
.checkpoints/{campaign_id}.json — checkpoint kampanye
logs/{campaign_id}_{timestamp}.log — log eksekusi per-kampanye
ENVIRONMENT.md — snapshot Markdown tingkat-ruang-kerja dari lingkungan eksekusi (host, OS, Python, commit dan branch repositori, waktu tangkap, jumlah CPU, mesin), ditimpa di setiap inisialisasi kampanye

Setiap rekaman eksekusi di-content-hash atas muatan ilmiah deterministiknya; pengaturan waktu-dinding dan pengukuran sumber daya yang disimpan pada rekaman adalah provenans dan tetap di luar hash, sehingga verifikasi replay tidak terpengaruh variasi waktu eksekusi-ke-eksekusi. Checkpoint mendaftar id eksekusi selesai, gagal, dan tertunda, sehingga panggilan resume() berikutnya melewati pekerjaan yang selesai. Kampanye paralel mempersisten rekaman hasil selesai saat setiap worker menyelesaikan dan menulis checkpoint akhir di akhir kampanye; resume tetap menemukan rekaman selesai dari disk sebelum menjadwalkan pekerjaan tersisa.

Penangkapan lingkungan

Cap lingkungan kampanye mencakup sistem operasi, versi Python, tag platform, versi paket, jumlah CPU, fakta mesin/prosesor, commit Git saat ini, hash konfigurasi, dan kebijakan benih. Hostname, kredensial, dan variabel lingkungan tidak ditangkap.

Penanganan kegagalan

Galat konfigurasi, domain, kapabilitas-tak-didukung, dan dependensi opsional yang hilang bersifat terminal. Pengecualian runtime lain dapat-dipulihkan sampai anggaran percobaan-ulang habis. Setiap percobaan gagal dipersisten sebelum percobaan-ulang atau pelanjutan.

Pembangun bukti

Gunakan tools/build_campaign_evidence.py untuk membangun katalog benchmark kandidat, kampanye komparatif penuh, ablasi NDSO, pemeriksaan sensitivitas, paket bukti, dan kumpulan data portal dari satu konfigurasi tercatat:

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

Pembangun memancarkan progres fase ke stderr untuk materialisasi katalog, perencanaan kampanye, eksekusi, analisis, ekspor paket, dan penulisan laporan. Pembangun dengan sengaja menulis bukti yang dihasilkan di luar pohon sumber terlacak-Git. Promosikan keluarannya hanya melalui gate rilis dan pengungkapan.