Kampagnen-Engine

dispatchatlas.lab besitzt die reproduzierbare Kampagnen-Orchestrierung über Benchmark-Provider und Solver-Registries hinweg. Es validiert die Kampagnenkonfiguration, schätzt die Laufkosten, erfasst die Runtime-Umgebung, persistiert Prüfpunkte, klassifiziert Fehler, und nimmt unvollständige Läufe wieder auf, ohne abgeschlossene Arbeit zu duplizieren.

Ausführbare Beispiele: examples/run_experiment.py treibt einen Smoke-Piloten, eine Stopp-Regel-Ablation, und einen Seed-Sensitivitäts-Sweep; examples/inspect_engine.py inspiziert die host-bewusste Worker-Dimensionierung und die komponierbaren Terminierungskriterien.

Konfiguration

Kampagnen deklarieren Benchmark-Selektoren, Solver-ids, Ziele, Seed-Richtlinie, Stopp-Kriterien, Offenlegungslabels, Ressourcenbudgets, Wiederholungsrichtlinie, Ausführungsmodus, und ein Ausgabe-Repository.

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 ist die Wurzel des Experimente-Arbeitsbereichs, kein Pro-Kampagne-Verzeichnis: jeder Lauf landet unter results/{campaign}/{solver}/{benchmark}/ innerhalb dieser Wurzel.

Die Validierung expandiert die ausgewählten Benchmark-Probleme und Solver-ids in deterministische Lauf-ids. Vollkampagnen-Pläne können für Kostenschätzungen dry-run ausgeführt werden, aber die Ausführung bleibt gesperrt, bis die statistische Design-Genehmigung aufgezeichnet ist. Seed-gesäte stochastische Solver können explizite Pro-Solver-Seed-Replikate via solver_seed_replicates deklarieren, während deterministische Solver bei einem aufgezeichneten Seed pro Problem und Ziel bleiben.

Ausführung

Verwende CampaignRunner mit einem Benchmark-Provider, einer Solver-Registry, und FileResultRepository. Der Standard-Runner verdrahtet den gebündelten Smoke-Benchmark-Provider und die Solver-Registry.

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)

Ausführungsmodi:

Kampagnen-Arten und Lauf-Anzahl-Richtlinie

Eine Kampagne deklariert eine kind. Die Katalogtabelle unten wird aus der Experiment-Design-Taxonomie generiert, sodass ihre Summe aus den Zeilen selbst zählbar ist.

Die Lauf-Anzahl-Richtlinie erzwingt einen statistischen-Power-Boden von mindestens dreißig unabhängigen Läufen pro (stochastischer-Solver, Instanz)-Zelle in den Stufen pilot und full, der etablierten Anleitung zu den für den zuverlässigen Vergleich randomisierter Algorithmen nötigen Stichprobengrößen folgend (Arcuri & Briand 2014); deterministische Solver laufen einmal. Eine smoke-Kampagne markiert eine Unter-Boden-Anzahl, statt sie abzulehnen, sodass schnelle Prüfungen günstig bleiben, ohne ein unter-mächtiges Design still auszuliefern.

Duale Stopp-Protokolle

Eine Kampagne berichtet jedes stochastische-Solver-Ergebnis sowohl unter einem Festbudget-Protokoll (Iterationen oder Wandzeit) als auch einem Festziel-Protokoll (Terminierung bei einem Zielobjektiv). Deklariere beide auf einer Kampagne via stopping_protocols; jede Zelle wird unter jedem Protokoll geplant, während sie einen festen Seed teilt, sodass die zwei Berichte direkt vergleichbar sind. Jeder abgeschlossene Lauf zeichnet sein Protokoll in seinen Diagnosen unter dem Schlüssel stopping_protocol auf.

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),
    ),
)

Fairer Vergleich

Eine comparative-Kampagne übt jeden Solver unter identischer Terminierung, gleichen Rechenbudgets, und einem gleichen Pro-Algorithmus-TuningBudget aus, mit Pro-Zelle-festen-Seeds, die im Lauf-Manifest protokolliert sind. Das Angleichen des Tuning-Budgets über die Solver folgt der etablierten Benchmarking-Praxis, die hält, dass ungleicher Tuning-Aufwand einen sonst fairen Vergleich konfundiert (Bartz-Beielstein et al. 2020). Die Kampagne schlägt schließend fehl, sofern sie nicht mindestens zwei Solver vergleicht und ein Tuning-Budget deklariert; die Garantie wird in den Plan-Metadaten unter den fair_comparison*-Schlüsseln aufgezeichnet.

Sichere-Max-Worker-Topologie

probe_capacity wählt die größte Worker-Anzahl, die innerhalb des Ressourcenbudgets bleibt, deckelt den internen Thread-Pool jedes exakten Solvers, sodass Worker mal Threads den Host nie übersubskribiert, pinnt die Umgebung des Linear-Algebra-Thread-Pools, um verschachtelte Pools zu verhindern, und fällt für die Modi sequential und replay auf einen deterministischen Worker zurück. Jeder Lauf gehört genau einem Worker und wird in seinem eigenen run-id-indizierten Datensatz persistiert, sodass die Aggregation nur-Merge ist: merge_only_aggregation sortiert Läufe nach id und hasht ihre Inhalts-Hash-Strings, was einen Kampagnen-Hash erzeugt, der bit-stabil ist, unabhängig von der Worker-Abschlussreihenfolge.

Kommandozeilen-Schnittstelle

Der Befehl dispatchatlas-lab validiert, kostet, führt aus, nimmt wieder auf, und wiederholt eine als JSON-Konfigurationsdatei deklarierte Kampagne:

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

Prüfpunkte und Ergebnisse

Das datei-gestützte Repository behandelt OutputPolicy.root_dir als die Wurzel des Experimente-Arbeitsbereichs und schreibt die hierarchische Auf-Lauf-Ebene-Anordnung:

• results/{campaign_id}/plan.json und results/{campaign_id}/environment.json
• results/{campaign_id}/{solver_id}/{benchmark_id}/run_{idx}.json — ein Datensatz pro abgeschlossenem Lauf, wobei idx der null-basierte Replikat-Index ist, der aus dem Laufplan zugewiesen wird
• results/{campaign_id}/{solver_id}/{benchmark_id}/failures/run_{idx}.attempt-{N}.json — ein Datensatz pro fehlgeschlagenem Versuch
• .checkpoints/{campaign_id}.json — der Kampagnen-Prüfpunkt
• logs/{campaign_id}_{timestamp}.log — das Pro-Kampagne-Ausführungslog
• ENVIRONMENT.md — ein Arbeitsbereich-Ebene-Markdown-Schnappschuss der Ausführungsumgebung (Host, OS, Python, Repository-Commit und -Branch, Erfassungszeit, CPU-Anzahl, Maschine), bei jeder Kampagnen-Initialisierung überschrieben

Jeder Lauf-Datensatz wird über seine deterministische wissenschaftliche Nutzlast content-hashed; Wandzeit-Timing und Ressourcenmessungen, die auf dem Datensatz gespeichert sind, sind Provenienz und bleiben außerhalb des Hashes, sodass die Replay-Verifizierung von der Lauf-zu-Lauf-Timing-Variation unberührt bleibt. Prüfpunkte listen abgeschlossene, fehlgeschlagene, und ausstehende Lauf-ids, sodass ein späterer resume()-Aufruf abgeschlossene Arbeit überspringt. Parallele Kampagnen persistieren abgeschlossene Ergebnis-Datensätze, sobald jeder Worker fertig ist, und schreiben den finalen Prüfpunkt am Kampagnenende; resume entdeckt weiterhin abgeschlossene Datensätze von der Festplatte, bevor verbleibende Arbeit geplant wird.

Umgebungserfassung

Kampagnen-Umgebungsstempel umfassen Betriebssystem, Python-Version, Plattform-Tag, Paketversionen, CPU-Anzahl, Maschinen-/Prozessor-Fakten, aktuellen Git-Commit, Konfigurations-Hash, und Seed-Richtlinie. Hostnames, Anmeldedaten, und Umgebungsvariablen werden nicht erfasst.

Fehlerbehandlung

Konfigurations-, Domänen-, Nicht-unterstützte-Fähigkeit-, und fehlende-optionale- Abhängigkeit-Fehler sind terminal. Andere Runtime-Ausnahmen sind wiederherstellbar, bis das Wiederholungsbudget erschöpft ist. Jeder fehlgeschlagene Versuch wird vor der Wiederholung oder Wiederaufnahme persistiert.

Beleg-Builder

Verwende tools/build_campaign_evidence.py, um Kandidaten-Benchmark-Kataloge, vollständige vergleichende Kampagnen, NDSO-Ablationen, Sensitivitätsprüfungen, Belegpakete, und Portal-Datensätze aus einer aufgezeichneten Konfiguration zu bauen:

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

Der Builder emittiert Phasen-Fortschritt nach stderr für Katalog-Materialisierung, Kampagnenplanung, Ausführung, Analyse, Paket-Export, und Berichtsschreibung. Der Builder schreibt generierten Beleg absichtlich außerhalb der Git-verfolgten Quellbäume. Befördere seine Ausgaben nur durch die Release- und Offenlegungsgates.