Campañas reproducibles

El espacio de trabajo experiments/ contiene todo lo que produce una campaña y todo lo necesario para reproducirla. La separación es estricta: las recetas se rastrean, las salidas son locales. Las configuraciones de campaña y los scripts ejecutores viven en el control de versiones; cada salida pesada — benchmarks generados, registros de ejecución, logs, puntos de control, paquetes de evidencia y la instantánea de entorno — permanece en la máquina que la produjo y se regenera bajo demanda a partir de la receta.

🗂️ Disposición

Los directorios de salida existen localmente y el ejecutor de campaña los recrea automáticamente cuando faltan; nada bajo ellos se prepara nunca para commit.

🧱 Dos capas, una fuente de verdad

1. Capa de reproducibilidad (granular). Cada ejecución es un registro JSON en results/{campaign_id}/{solver_id}/{benchmark_id}/run_{idx}.json. La ruta misma es el índice — campaña, luego solver, luego benchmark, luego réplica — de modo que cualquier porción de la evidencia es direccionable sin una base de datos. Los registros llevan campos de primera clase de tiempo, convergencia, solución y esfuerzo del solver; nada analítico se oculta en notas de forma libre.
2. Capa de curación (por niveles). evidence-bundles/{campaign_id}-{tier}/ contiene las exportaciones por niveles de divulgación derivadas de los registros de ejecución. Los identificadores de nivel provienen del vocabulario fijo seguro para el público — core, speed, quality, platform — y un paquete siempre se deriva de los registros a nivel de ejecución, nunca una fuente de verdad independiente.

🔁 Contrato de reproducibilidad

• Cada campaña declara una semilla maestra; la semilla de cada ejecución se deriva deterministamente de ella y de la posición de la ejecución — misma configuración, mismas semillas, mismos registros, bit por bit.
• .checkpoints/{campaign_id}.json registra el hash de la configuración. Una configuración sin cambios se reanuda desde el punto de control y omite las ejecuciones completadas; cualquier cambio de configuración invalida el punto de control por completo.
• ENVIRONMENT.md toma una instantánea de host, sistema operativo, Python y el commit del repositorio en tiempo de ejecución, de modo que cada resultado es rastreable hasta el código y la máquina exactos que lo produjeron.
• Los logs son de solo-añadir por ejecución.

Estas prácticas — semilla por ejecución, captura de configuración y entorno para que un resultado pueda regenerarse a partir de su receta — siguen estándares reconocidos para documentar y reproducir experimentos computacionales (ACM Artifact Review and Badging, Version 1.1, 2020; Gundersen & Kjensmo 2018).

El manifiesto de reproducibilidad también justifica el umbral de 30 ejecuciones con una declaración de potencia derivada: en el umbral, con un nivel bilateral de 0.05 y una potencia de 0.80, el diseño emparejado detecta efectos estandarizados de aproximadamente 0.523 o mayores bajo la aproximación de Wilcoxon ajustada por ARE (Noether 1987; marco: Campelo y Takahashi 2019). La frase se recalcula a partir del umbral en tiempo de renderizado, de modo que nunca puede desviarse del umbral que justifica. Dos descriptores de protocolo adicionales la acompañan: una entrada de escalado-de-presupuesto que registra cómo crece el presupuesto de evaluación con el tamaño de instancia (el protocolo escalado-con-el-tamaño de Vallada, Ruiz y Framiñan 2015, registrado por el manifiesto de comparación-justa del laboratorio como una regla escalada-con-la-evaluación o como fija-por-campaña), y una entrada de paridad-de-ajuste que porta el presupuesto de ajuste igual por algoritmo que declara cada campaña comparativa (LaTorre, Molina, Osaba, Poyatos, Del Ser y Herrera 2021); una paridad no declarada se renderiza honestamente como no declarada.

🏃 Cómo una campaña escribe en el espacio de trabajo

1. Crea o ajusta una configuración de campaña bajo configs/ (smoke-pilot.json es el punto de partida rastreado).

2. Ejecútala a través del ejecutor de campaña — programáticamente como en los tutoriales, mediante un script de receta rastreado (uv run python experiments/scripts/run_smoke_pilot.py), o a través de la interfaz de línea de comandos:

   uv run dispatchatlas-lab run --config experiments/configs/smoke-pilot.json

3. El ejecutor valida la configuración en un plan determinista, escribe results/{campaign_id}/plan.json y environment.json, luego persiste un registro content-hasheado por cada ejecución completada más cualquier intento fallido.

4. Inspecciona los registros de ejecución bajo results/ y reanuda, reproduce o re-ejecuta desde la misma configuración. Volver a ejecutar la misma configuración reproduce los mismos registros bit por bit; una configuración cambiada invalida el punto de control en lugar de reutilizarlo en silencio.

La página del motor de campañas documenta la validación, los presupuestos de ejecución en seco, los modos de ejecución, los reintentos, la reanudación y la verificación por reproducción en su totalidad.

📦 De los registros de ejecución a los paquetes de evidencia

La ruta de exportación convierte un directorio de campaña completado en un paquete curado bajo evidence-bundles/{campaign_id}-{tier}/:

uv run dispatchatlas export `
  --campaign-dir .\experiments\results\smoke-pilot `
  --target-dir .\experiments `
  --authorized-output-root .\experiments `
  --tier core

tools/build_campaign_evidence.py impulsa la misma ruta a escala, construyendo catálogos de benchmarks, campañas, análisis y paquetes para cada nivel a partir de una configuración registrada. La página de paquetes de evidencia describe los niveles; exportaciones de análisis describe el contenido estadístico.

🔒 Límite seguro para el público

Las páginas públicas nunca leen este espacio de trabajo directamente: el sitio de documentación y el portal de resultados consumen solo exportaciones comprometidas y filtradas por divulgación producidas a partir de la capa curada. Los registros de programa privados en el espacio de trabajo son ignorados por el control de versiones y nunca llegan a una superficie pública.