Moteur de campagnes

dispatchatlas.lab possède l'orchestration de campagnes reproductibles à travers les fournisseurs de benchmarks et les registres de solveurs. Il valide la configuration de campagne, estime le coût d'exécution, capture l'environnement de runtime, persiste les points de contrôle, classe les échecs, et reprend les exécutions incomplètes sans dupliquer le travail terminé.

Exemples exécutables : examples/run_experiment.py pilote un pilote de test, une ablation de règle-d'arrêt, et un balayage de sensibilité-de-graine ; examples/inspect_engine.py inspecte le dimensionnement de workers conscient-de-l'hôte et les critères de terminaison composables.

Configuration

Les campagnes déclarent des sélecteurs de benchmark, des ids de solveur, des objectifs, une politique de graines, des critères d'arrêt, des étiquettes de divulgation, des budgets de ressources, une politique de réessai, un mode d'exécution, et un dépôt de sortie.

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 est la racine de l'espace de travail des expériences, pas un répertoire par-campagne : chaque exécution atterrit sous results/{campaign}/{solver}/{benchmark}/ à l'intérieur de cette racine.

La validation développe les problèmes de benchmark sélectionnés et les ids de solveur en ids d'exécution déterministes. Les plans de campagne-complète peuvent être exécutés en dry-run pour des estimations de coût, mais l'exécution reste bloquée jusqu'à ce que l'approbation de conception statistique soit enregistrée. Les solveurs stochastiques ensemencés peuvent déclarer des réplicas de graine par-solveur explicites via solver_seed_replicates, tandis que les solveurs déterministes restent à une graine enregistrée par problème et objectif.

Exécution

Utilisez CampaignRunner avec un fournisseur de benchmarks, un registre de solveurs, et FileResultRepository. Le runner par défaut câble le fournisseur de benchmarks de test et le registre de solveurs empaquetés.

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)

Modes d'exécution :

Mode	Comportement
`sequential`	Exécute une unité déterministe à la fois.
`parallel`	Utilise jusqu'à `ResourceBudget.max_workers` fils de worker.
`bounded-resource`	Utilise le plus petit de `max_workers` et `max_concurrent_runs`.
`replay`	Ré-exécute les exécutions terminées à partir de graines enregistrées et vérifie que chaque hachage de contenu recalculé correspond à l'enregistrement persisté ; échoue en position fermée à toute divergence.

Genres de campagne et politique de nombre-d'exécutions

Une campagne déclare un kind. La table de catalogue ci-dessous est générée à partir de la taxonomie de conception-d'expériences, de sorte que son total est dénombrable depuis les lignes elles-mêmes.

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.

La politique de nombre-d'exécutions impose un plancher de puissance-statistique d'au moins trente exécutions indépendantes par cellule (solveur-stochastique, instance) aux étapes pilot et full, suivant les conseils établis sur les tailles d'échantillon nécessaires à une comparaison fiable d'algorithmes randomisés (Arcuri & Briand 2014) ; les solveurs déterministes s'exécutent une fois. Une campagne smoke signale un nombre sous-le-plancher au lieu de le rejeter, de sorte que les vérifications rapides restent bon marché sans livrer silencieusement une conception sous-puissante.

Protocoles d'arrêt duaux

Une campagne rapporte chaque résultat de solveur-stochastique sous à la fois un protocole de budget-fixe (itérations ou temps-mural) et un protocole de cible-fixe (terminer sur un objectif cible). Déclarez les deux sur une campagne via stopping_protocols ; chaque cellule est planifiée sous chaque protocole en partageant une graine fixe, de sorte que les deux rapports sont directement comparables. Chaque exécution terminée enregistre son protocole dans ses diagnostics sous la clé 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),
    ),
)

Comparaison équitable

Une campagne comparative exerce chaque solveur sous une terminaison identique, des budgets computationnels égaux, et un TuningBudget par-algorithme égal, avec des graines fixes par-cellule enregistrées dans le manifeste d'exécution. Égaliser le budget de tuning à travers les solveurs suit la pratique de benchmarking établie, qui soutient qu'un effort de tuning inégal confond une comparaison par ailleurs équitable (Bartz-Beielstein et al. 2020). La campagne échoue en position fermée à moins de comparer au moins deux solveurs et de déclarer un budget de tuning ; la garantie est enregistrée dans les métadonnées du plan sous les clés fair_comparison*.

Topologie de max-worker sûr

probe_capacity sélectionne le plus grand nombre de workers qui reste à l'intérieur du budget de ressources, plafonne le pool de fils interne de chaque solveur exact de sorte que workers fois fils ne sur-souscrive jamais l'hôte, épingle l'environnement du pool-de-fils d'algèbre-linéaire pour prévenir les pools imbriqués, et se rabat sur un worker déterministe pour les modes sequential et replay. Chaque exécution appartient à exactement un worker et est persistée dans son propre enregistrement indexé-par-run-id, de sorte que l'agrégation est fusion-seule : merge_only_aggregation trie les exécutions par id et hache leurs chaînes de hachage-de-contenu, produisant un hachage de campagne qui est bit-stable indépendamment de l'ordre d'achèvement des workers.

Interface en ligne-de-commande

La commande dispatchatlas-lab valide, coûte, exécute, reprend, et rejoue une campagne déclarée comme un fichier de configuration 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

Points de contrôle et résultats

Le dépôt adossé-à-des-fichiers traite OutputPolicy.root_dir comme la racine de l'espace de travail des expériences et écrit la disposition hiérarchique au niveau-d'exécution :

results/{campaign_id}/plan.json et results/{campaign_id}/environment.json
results/{campaign_id}/{solver_id}/{benchmark_id}/run_{idx}.json — un enregistrement par exécution terminée, où idx est l'index de réplica à base-zéro assigné depuis le plan d'exécution
results/{campaign_id}/{solver_id}/{benchmark_id}/failures/run_{idx}.attempt-{N}.json — un enregistrement par tentative échouée
.checkpoints/{campaign_id}.json — le point de contrôle de la campagne
logs/{campaign_id}_{timestamp}.log — le log d'exécution par-campagne
ENVIRONMENT.md — un instantané Markdown au niveau-de-l'espace-de-travail de l'environnement d'exécution (hôte, OS, Python, commit et branche du dépôt, heure de capture, nombre de CPU, machine), écrasé à chaque initialisation de campagne

Chaque enregistrement d'exécution est content-hashed sur sa charge utile scientifique déterministe ; la temporisation murale et les mesures de ressources stockées sur l'enregistrement sont de la provenance et restent hors du hachage, de sorte que la vérification de replay n'est pas affectée par la variation de temporisation exécution-à-exécution. Les points de contrôle listent les ids d'exécution terminés, échoués, et en attente, de sorte qu'un appel ultérieur à resume() saute le travail terminé. Les campagnes parallèles persistent les enregistrements de résultat terminés à mesure que chaque worker finit et écrivent le point de contrôle final à la fin de la campagne ; resume découvre toujours les enregistrements terminés depuis le disque avant de planifier le travail restant.

Capture d'environnement

Les estampilles d'environnement de campagne incluent le système d'exploitation, la version de Python, l'étiquette de plateforme, les versions de paquet, le nombre de CPU, les faits de machine/processeur, le commit Git actuel, le hachage de configuration, et la politique de graines. Les hostnames, identifiants, et variables d'environnement ne sont pas capturés.

Gestion des échecs

Les erreurs de configuration, de domaine, de capacité-non-supportée, et de dépendance optionnelle manquante sont terminales. Les autres exceptions de runtime sont récupérables jusqu'à ce que le budget de réessai soit épuisé. Chaque tentative échouée est persistée avant le réessai ou la reprise.

Constructeur de preuves

Utilisez tools/build_campaign_evidence.py pour construire des catalogues de benchmarks candidats, des campagnes comparatives complètes, des ablations NDSO, des vérifications de sensibilité, des lots de preuves, et des jeux de données du portail à partir d'une configuration enregistrée :

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

Le constructeur émet la progression de phase vers stderr pour la matérialisation de catalogue, la planification de campagne, l'exécution, l'analyse, l'export de lots, et l'écriture de rapport. Le constructeur écrit intentionnellement la preuve générée hors des arbres de source suivis-par-Git. Promouvez ses sorties uniquement à travers les gates de publication et de divulgation.