Motor de campanhas

dispatchatlas.lab é dono da orquestração de campanhas reproduzíveis através de provedores de benchmark e registros de solvers. Ele valida a configuração de campanha, estima o custo de execução, captura o ambiente de runtime, persiste pontos de verificação, classifica falhas, e retoma execuções incompletas sem duplicar o trabalho concluído.

Exemplos executáveis: examples/run_experiment.py conduz um piloto de fumaça, uma ablação de regra-de-parada, e uma varredura de sensibilidade-de-semente; examples/inspect_engine.py inspeciona o dimensionamento de workers ciente-do-host e os critérios de terminação componíveis.

Configuração

As campanhas declaram seletores de benchmark, ids de solver, objetivos, política de sementes, critérios de parada, rótulos de divulgação, orçamentos de recursos, política de retentativas, modo de execução, e um repositório de saída.

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 é a raiz do espaço de trabalho de experimentos, não um diretório por-campanha: cada execução aterrissa sob results/{campaign}/{solver}/{benchmark}/ dentro dessa raiz.

A validação expande os problemas de benchmark selecionados e os ids de solver em ids de execução determinísticos. Os planos de campanha-completa podem ser executados em dry-run para estimativas de custo, mas a execução permanece bloqueada até que a aprovação de design estatístico seja registrada. Os solvers estocásticos semeados podem declarar réplicas de semente por-solver explícitas via solver_seed_replicates, enquanto os solvers determinísticos permanecem em uma semente registrada por problema e objetivo.

Execução

Use CampaignRunner com um provedor de benchmark, um registro de solvers, e FileResultRepository. O runner padrão cabeia o provedor de benchmark de fumaça e o registro de solvers empacotados.

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 execução:

Modo	Comportamento
`sequential`	Executa uma unidade determinística por vez.
`parallel`	Usa até `ResourceBudget.max_workers` threads de worker.
`bounded-resource`	Usa o menor de `max_workers` e `max_concurrent_runs`.
`replay`	Re-executa execuções concluídas a partir de sementes registradas e verifica que cada hash de conteúdo recomputado coincide com o registro persistido; falha fechando em qualquer divergência.

Tipos de campanha e política de contagem-de-execuções

Uma campanha declara um kind. A tabela de catálogo abaixo é gerada a partir da taxonomia de design-de-experimentos, de modo que seu total é contável a partir das próprias linhas.

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.

A política de contagem-de-execuções impõe um piso de potência-estatística de ao menos trinta execuções independentes por célula (solver-estocástico, instância) nas etapas pilot e full, seguindo a orientação estabelecida sobre os tamanhos de amostra necessários para a comparação confiável de algoritmos randomizados (Arcuri & Briand 2014); os solvers determinísticos executam uma vez. Uma campanha smoke sinaliza uma contagem abaixo-do-piso em vez de rejeitá-la, de modo que as verificações rápidas permanecem baratas sem enviar silenciosamente um design com-pouca-potência.

Protocolos de parada duais

Uma campanha reporta cada resultado de solver-estocástico sob tanto um protocolo de orçamento-fixo (iterações ou tempo-de-relógio) quanto um protocolo de alvo-fixo (terminar em um objetivo alvo). Declare ambos em uma campanha através de stopping_protocols; cada célula é planejada sob cada protocolo compartilhando uma semente fixa, de modo que os dois relatórios são diretamente comparáveis. Cada execução concluída registra seu protocolo em seus diagnósticos sob a chave 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),
    ),
)

Comparação justa

Uma campanha comparative exercita cada solver sob terminação idêntica, orçamentos computacionais iguais, e um TuningBudget por-algoritmo igual, com sementes fixas por-célula registradas no manifesto de execução. Igualar o orçamento de tuning através dos solvers segue a prática de benchmarking estabelecida, que sustenta que um esforço de tuning desigual confunde uma comparação de outro modo justa (Bartz-Beielstein et al. 2020). A campanha falha fechando a menos que compare ao menos dois solvers e declare um orçamento de tuning; a garantia é registrada nos metadados do plano sob as chaves fair_comparison*.

Topologia de max-worker seguro

probe_capacity seleciona a maior contagem de workers que permanece dentro do orçamento de recursos, limita o pool de threads interno de cada solver exato de modo que workers vezes threads nunca super-inscreva o host, fixa o ambiente do pool-de-threads de álgebra-linear para prevenir pools aninhados, e recorre a um worker determinístico para os modos sequential e replay. Cada execução é propriedade de exatamente um worker e é persistida em seu próprio registro indexado-por-run-id, de modo que a agregação é apenas-mesclagem: merge_only_aggregation ordena as execuções por id e faz hash de suas cadeias de hash-de-conteúdo, produzindo um hash de campanha que é bit-estável independentemente da ordem de conclusão dos workers.

Interface de linha-de-comando

O comando dispatchatlas-lab valida, custeia, executa, retoma, e reproduz uma campanha declarada como um arquivo de configuração 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

Pontos de verificação e resultados

O repositório respaldado-por-arquivos trata OutputPolicy.root_dir como a raiz do espaço de trabalho de experimentos e escreve a disposição hierárquica a nível-de-execução:

results/{campaign_id}/plan.json e results/{campaign_id}/environment.json
results/{campaign_id}/{solver_id}/{benchmark_id}/run_{idx}.json — um registro por execução concluída, onde idx é o índice de réplica de base-zero atribuído a partir do plano de execução
results/{campaign_id}/{solver_id}/{benchmark_id}/failures/run_{idx}.attempt-{N}.json — um registro por tentativa falha
.checkpoints/{campaign_id}.json — o ponto de verificação da campanha
logs/{campaign_id}_{timestamp}.log — o log de execução por-campanha
ENVIRONMENT.md — um instantâneo Markdown a nível-de-espaço-de-trabalho do ambiente de execução (host, OS, Python, commit e branch do repositório, hora de captura, contagem de CPU, máquina), sobrescrito a cada inicialização de campanha

Cada registro de execução é content-hashed sobre sua carga útil científica determinística; a temporização de relógio e as medições de recursos armazenadas no registro são proveniência e permanecem fora do hash, de modo que a verificação de replay não é afetada pela variação de temporização execução-a-execução. Os pontos de verificação listam ids de execução concluídos, falhos, e pendentes, de modo que uma chamada posterior a resume() pula o trabalho concluído. As campanhas paralelas persistem os registros de resultado concluídos à medida que cada worker termina e escrevem o ponto de verificação final no fim da campanha; resume ainda descobre os registros concluídos do disco antes de agendar o trabalho restante.

Captura de ambiente

Os carimbos de ambiente de campanha incluem sistema operacional, versão de Python, etiqueta de plataforma, versões de pacote, contagem de CPU, fatos de máquina/processador, commit de Git atual, hash de configuração, e política de sementes. Hostnames, credenciais, e variáveis de ambiente não são capturados.

Tratamento de falhas

Os erros de configuração, de domínio, de capacidade-não-suportada, e de dependência opcional faltante são terminais. Outras exceções de runtime são recuperáveis até que o orçamento de retentativas se esgote. Cada tentativa falha é persistida antes da retentativa ou retomada.

Construtor de evidência

Use tools/build_campaign_evidence.py para construir catálogos de benchmark candidatos, campanhas comparativas completas, ablações NDSO, verificações de sensibilidade, pacotes de evidência, e conjuntos de dados do portal a partir de uma configuração registrada:

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

O construtor emite o progresso de fase para stderr para materialização de catálogo, planejamento de campanha, execução, análise, exportação de pacotes, e escrita de relatório. O construtor escreve intencionalmente evidência gerada fora das árvores de fonte rastreadas-por-Git. Promova suas saídas apenas através dos gates de lançamento e divulgação.