Motor de campañas

dispatchatlas.lab posee la orquestación de campañas reproducibles a través de proveedores de benchmarks y registros de solvers. Valida la configuración de campaña, estima el costo de ejecución, captura el entorno de runtime, persiste puntos de control, clasifica fallos, y reanuda ejecuciones incompletas sin duplicar el trabajo completado.

Ejemplos ejecutables: examples/run_experiment.py conduce un piloto de prueba, una ablación de regla-de-parada, y un barrido de sensibilidad-de-semilla; examples/inspect_engine.py inspecciona el dimensionamiento de workers consciente-del-host y los criterios de terminación componibles.

Configuración

Las campañas declaran selectores de benchmark, ids de solver, objetivos, política de semillas, criterios de parada, etiquetas de divulgación, presupuestos de recursos, política de reintentos, modo de ejecución, y un repositorio de salida.

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 es la raíz del espacio de trabajo de experimentos, no un directorio por-campaña: cada ejecución aterriza bajo results/{campaign}/{solver}/{benchmark}/ dentro de esa raíz.

La validación expande los problemas de benchmark seleccionados y los ids de solver en ids de ejecución deterministas. Los planes de campaña-completa pueden ejecutarse en dry-run para estimaciones de costo, pero la ejecución permanece bloqueada hasta que se registra la aprobación de diseño estadístico. Los solvers estocásticos sembrados pueden declarar réplicas de semilla por-solver explícitas vía solver_seed_replicates, mientras que los solvers deterministas permanecen en una semilla registrada por problema y objetivo.

Ejecución

Usa CampaignRunner con un proveedor de benchmarks, un registro de solvers, y FileResultRepository. El runner por defecto cablea el proveedor de benchmarks de prueba y el registro de solvers empaquetados.

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)

Modos de ejecución:

Modo	Comportamiento
`sequential`	Ejecuta una unidad determinista a la vez.
`parallel`	Usa hasta `ResourceBudget.max_workers` hilos de worker.
`bounded-resource`	Usa el menor de `max_workers` y `max_concurrent_runs`.
`replay`	Re-ejecuta ejecuciones completadas a partir de semillas registradas y verifica que cada hash de contenido recomputado coincida con el registro persistido; falla en cerrado ante cualquier divergencia.

Tipos de campaña y política de conteo-de-ejecuciones

Una campaña declara un kind. La tabla de catálogo de abajo se genera a partir de la taxonomía de diseño-de-experimentos, de modo que su total es contable desde las propias filas.

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 política de conteo-de-ejecuciones impone un piso de potencia-estadística de al menos treinta ejecuciones independientes por celda (solver-estocástico, instancia) en las etapas pilot y full, siguiendo la guía establecida sobre los tamaños de muestra necesarios para la comparación confiable de algoritmos aleatorizados (Arcuri & Briand 2014); los solvers deterministas se ejecutan una vez. Una campaña smoke marca un conteo bajo-el-piso en lugar de rechazarlo, de modo que las comprobaciones rápidas permanecen baratas sin enviar silenciosamente un diseño con-poca-potencia.

Protocolos de parada duales

Una campaña reporta cada resultado de solver-estocástico bajo tanto un protocolo de presupuesto-fijo (iteraciones o tiempo-de-reloj) como un protocolo de objetivo-fijo (terminar al alcanzar un objetivo meta). Declara ambos en una campaña a través de stopping_protocols; cada celda se planifica bajo cada protocolo compartiendo una semilla fija, de modo que los dos reportes son directamente comparables. Cada ejecución completada registra su protocolo en sus diagnósticos bajo la clave 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),
    ),
)

Comparación justa

Una campaña comparative ejercita cada solver bajo terminación idéntica, presupuestos computacionales iguales, y un TuningBudget por-algoritmo igual, con semillas fijas por-celda registradas en el manifiesto de ejecución. Igualar el presupuesto de tuning a través de los solvers sigue la práctica de benchmarking establecida, que sostiene que un esfuerzo de tuning desigual confunde una comparación de otro modo justa (Bartz-Beielstein et al. 2020). La campaña falla en cerrado a menos que compare al menos dos solvers y declare un presupuesto de tuning; la garantía se registra en los metadatos del plan bajo las claves fair_comparison*.

Topología de max-worker seguro

probe_capacity selecciona el mayor conteo de workers que permanece dentro del presupuesto de recursos, limita el pool de hilos interno de cada solver exacto de modo que workers por hilos nunca sobre-suscriba el host, fija el entorno del pool-de-hilos de álgebra-lineal para prevenir pools anidados, y recurre a un worker determinista para los modos sequential y replay. Cada ejecución es propiedad de exactamente un worker y se persiste en su propio registro indexado-por-run-id, de modo que la agregación es solo-fusión: merge_only_aggregation ordena las ejecuciones por id y hashea sus cadenas de hash-de-contenido, produciendo un hash de campaña que es bit-estable independientemente del orden de completitud de los workers.

Interfaz de línea-de-comandos

El comando dispatchatlas-lab valida, cuesta, ejecuta, reanuda, y reproduce una campaña declarada como un archivo de configuración 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

Puntos de control y resultados

El repositorio respaldado-por-archivos trata OutputPolicy.root_dir como la raíz del espacio de trabajo de experimentos y escribe la disposición jerárquica a nivel-de-run:

results/{campaign_id}/plan.json y results/{campaign_id}/environment.json
results/{campaign_id}/{solver_id}/{benchmark_id}/run_{idx}.json — un registro por ejecución completada, donde idx es el índice de réplica de base-cero asignado desde el plan de ejecución
results/{campaign_id}/{solver_id}/{benchmark_id}/failures/run_{idx}.attempt-{N}.json — un registro por intento fallido
.checkpoints/{campaign_id}.json — el punto de control de la campaña
logs/{campaign_id}_{timestamp}.log — el log de ejecución por-campaña
ENVIRONMENT.md — una instantánea Markdown a nivel-de-espacio-de-trabajo del entorno de ejecución (host, OS, Python, commit y rama del repositorio, hora de captura, conteo de CPU, máquina), sobrescrita en cada inicialización de campaña

Cada registro de ejecución es content-hashed sobre su carga útil científica determinista; la temporización de reloj y las mediciones de recursos almacenadas en el registro son procedencia y permanecen fuera del hash, de modo que la verificación de replay no se ve afectada por la variación de temporización ejecución-a-ejecución. Los puntos de control listan ids de ejecución completados, fallidos, y pendientes, de modo que una llamada posterior a resume() omite el trabajo completado. Las campañas paralelas persisten los registros de resultado completados a medida que cada worker termina y escriben el punto de control final al fin de la campaña; resume aún descubre los registros completados desde el disco antes de programar el trabajo restante.

Captura de entorno

Los sellos de entorno de campaña incluyen sistema operativo, versión de Python, etiqueta de plataforma, versiones de paquete, conteo de CPU, hechos de máquina/procesador, commit de Git actual, hash de configuración, y política de semillas. Hostnames, credenciales, y variables de entorno no se capturan.

Manejo de fallos

Los errores de configuración, de dominio, de capacidad-no-soportada, y de dependencia opcional faltante son terminales. Otras excepciones de runtime son recuperables hasta que el presupuesto de reintentos se agota. Cada intento fallido se persiste antes del reintento o reanudación.

Constructor de evidencia

Usa tools/build_campaign_evidence.py para construir catálogos de benchmarks candidatos, campañas comparativas completas, ablaciones NDSO, comprobaciones de sensibilidad, paquetes de evidencia, y conjuntos de datos del portal a partir de una configuración registrada:

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

El constructor emite el progreso de fase a stderr para materialización de catálogo, planificación de campaña, ejecución, análisis, exportación de paquetes, y escritura de informe. El constructor escribe intencionalmente evidencia generada fuera de los árboles de fuente rastreados-por-Git. Promueve sus salidas solo a través de los gates de lanzamiento y divulgación.