Executando estudos
Leve um estudo do caso aos resultados: gere ou prepare o caso, valide-o,
execute-o com novomodelo run e leia o que a execução gravou.
Preparando um diretório do caso
Seção intitulada “Preparando um diretório do caso”Para partir de um exemplo funcional, gere o modelo (template) 1dtoy:
novomodelo init --template 1dtoy my_studyEle grava onze arquivos: os oito arquivos obrigatórios da estrutura mostrada abaixo,
system/hydro_production_models.json e os dois arquivos
scenarios/*_seasonal_stats.parquet. Um diretório de destino não vazio é
recusado, a menos que se informe --force.
Um diretório do caso é uma pasta que contém todos os arquivos de dados de entrada exigidos pelo Novo Modelo. A estrutura mínima obrigatória é:
my_study/ config.json penalties.json stages.json initial_conditions.json system/ buses.json hydros.json thermals.json lines.jsonOs oito arquivos são obrigatórios. Antes de executar, valide a entrada:
novomodelo validate /path/to/my_studyUma validação bem-sucedida imprime as contagens de entidades e sai com código 0:
Valid case: 1 buses, 1 hydros, 2 thermals, 0 linesQuando a validação detecta erros — como um campo obrigatório ausente ou um valor
fora da faixa —, ela imprime a quantidade de erros, depois uma linha error: por erro
(tipo, arquivo e campo), e sai com código 1. No caso abaixo, a primeira
hidrelétrica não tem o campo reservoir e tem max_turbined_m3s igual a -5.0. O relatório
mostra apenas o campo ausente, porque a leitura de system/hydros.json para
ali, antes que qualquer valor seja verificado. O valor negativo é reportado depois que o
campo é restaurado:
Validation: 1 errors, 0 warnings in my_studyerror: [SchemaViolation] system/hydros.json: field reservoir: missing field `reservoir` at line 31 column 5Corrija os erros reportados antes de prosseguir. Veja Formato do caso para o esquema completo.
Executando novomodelo run
Seção intitulada “Executando novomodelo run”novomodelo run /path/to/my_studyPor padrão, os resultados são gravados em <CASE_DIR>/output/. Para especificar outro
local:
novomodelo run /path/to/my_study --output /path/to/resultsAntes de gravar as saídas de uma fase, o novomodelo run
remove as saídas dessa fase deixadas pela execução anterior, conforme listado em
Formato de saída — Marcadores de sucesso; todos os
demais arquivos permanecem até que uma execução os regrave, de modo que a exportação stochastic/ de uma
execução anterior que definiu exports.stochastic permanece. Use um diretório --output novo, ou apague o antigo,
antes de comparar execuções. As execuções com partida a quente (warm-start), retomada e somente simulação leem o
checkpoint da política em policy.path dentro do diretório de saída; portanto, preserve esse
checkpoint quando planejar uma dessas execuções (Gerenciamento da política).
Etapas do ciclo de vida
Seção intitulada “Etapas do ciclo de vida”A figura acompanha um estudo desde o diretório do caso até as saídas; as três setas que saem do checkpoint da política são as formas de reaproveitá-lo.
O novomodelo run carrega o caso, executa o treinamento (training), a menos que training.enabled seja false, grava o checkpoint
da política em policy.path ao final do treinamento, executa a simulação quando ela está habilitada
e grava suas saídas. O novomodelo validate verifica o caso previamente, sem resolver.
Uma execução posterior do mesmo estudo pode partir a quente do checkpoint ou retomá-lo, ou simulá-lo
sem treinamento (Reaproveitando uma política salva), e outro
estudo pode importá-lo como sua fronteira terminal
(Gerenciamento da política — Cortes de fronteira).
Saída no terminal
Seção intitulada “Saída no terminal”Cabeçalho
Seção intitulada “Cabeçalho”A menos que se informe --quiet, um cabeçalho (banner) mostra a versão, seguido de um bloco Execution
com o solver, o backend de comunicação e o número de threads.
O novomodelo run grava o cabeçalho, os blocos de preparação, as linhas de progresso e os
resumos na saída padrão (stdout), e os avisos e erros na saída de erro (stderr), de modo que redirecionar apenas a stderr
captura somente os avisos e erros.
Use --quiet para suprimir o cabeçalho, as barras de progresso e os resumos.
O cabeçalho, o bloco Execution e os resumos vão para a stdout; os avisos vão para a
stderr, e os erros são sempre gravados na stderr, independentemente de --quiet.
Barras de progresso
Seção intitulada “Barras de progresso”Quando a stderr é um terminal, o treinamento mostra uma barra de progresso ao vivo na stderr com a
iteração corrente, os limites, o gap (em percentual, com cinco casas decimais) e os
tempos das simulações forward e backward. Quando a stderr é redirecionada ou encaminhada por pipe, o novomodelo imprime uma
linha por iteração na stdout, e a simulação informa sua contagem de cenários da
mesma forma. No modo --quiet, nenhum progresso é impresso.
Um trecho da saída de novomodelo run my_study sobre o caso gerado, com stdout
e stderr enviadas ao mesmo arquivo. Ele omite o
cabeçalho, a linha Host e as linhas de progresso entre a primeira e a última de cada fase:
Execution Solver: HiGHS 1.13.1 Backend: local Threads: 1 rayon threadLoading case: my_studySetup Load: 3ms Stochastic fit: 0ms Production fit: 0ms Evaporation fit: 0ms Broadcast: 0msHydro models Production: 1 constant Evaporation: 0 linearized, 1 withoutModel provenance Estimation path: user_stats_white_noise Seasonal stats: user_file AR coefficients: n/a Correlation: n/a Opening tree: estimated (moment matching: per_coordinate)Training starting... (max 128 iterations)Training 1/128 iter LB: 1.22821e7 UB: 2.12369e7 gap: 72.91002% fwd: 2ms / bwd: 2ms [00:00:00 < 00:00:00]Training 128/128 iter LB: 2.06161e7 UB: 5.79592e5 gap: -97.18865% fwd: 0ms / bwd: 2ms [00:00:00]Training complete in 0.4s (128 iterations, iteration_limit) Lower bound: 2.06161e7 $/stage Upper bound: 5.79592e5 +/- 0.00000e0 $/stage Gap: -97.18865% (started at 72.91002%) Policy rows: 384 active / 384 generated LP solves: 5632 (5632 first-try, 0 retried, 0 failed) Avg iter: 3ms Time split: Forward 2ms (<1%) solve 2ms · wait 0ms (0% of phase) Backward 194ms (43%) solve 194ms · wait 0ms (0% of phase) Serial 250ms (56%) bound 50ms · selection 0ms · other 200msWriting training outputs...Output written to my_study/output/ (0.0s)Simulation starting... (100 scenarios across 1 ranks × 1 threads)Simulation 1/100 scenarios LP: 1.3ms avg [00:00:00 < 00:00:00]Simulation 100/100 scenarios LP: 0.9ms avg [00:00:00]Simulation complete in 0.5s (100 scenarios) Completed: 100 Failed: 0 Expected cost: 1.28652e7 +/- 5.74102e6 (std: 2.92909e7) LP solves: 400 (400 first-try, 0 retried, 0 failed) Avg/scenario: 0.006s Time split: Solver 346ms (61%) Other 220ms (39%)Writing simulation outputs...Output written to my_study/output/ (0.0s)Cada fase imprime um resumo na stdout com:
- Treinamento: número de iterações e como o treinamento terminou, limites, gap, linhas da política, resoluções, tempo
- Simulação (quando habilitada): cenários solicitados, concluídos e com falha
- Diretório de saída: uma linha
Output written to <dir>/após cada fase que grava saídas, contendo o caminho exatamente como passado em--output(ou o padrão<CASE_DIR>/output/) — um caminho--outputrelativo é impresso como relativo, sem ser convertido em caminho absoluto
O caso gerado executa uma simulação forward por iteração, de modo que cada limite superior é o custo de uma única trajetória amostrada, e o gap pode ficar abaixo de zero. Convergência e diagnóstico explica como ler os limites.
Verificando os resultados
Seção intitulada “Verificando os resultados”Junto com as tabelas de resultados, o novomodelo run grava um registro legível por máquina de
cada fase executada: training/metadata.json quando o treinamento foi executado e
simulation/metadata.json quando a simulação foi executada. Consulte-os diretamente com jq:
jq '{status, bounds}' /path/to/my_study/output/training/metadata.jsonstatus vale "partial" quando uma solicitação de encerramento terminou a fase antecipadamente e
"complete" nos demais casos, inclusive após um
treinamento que falhou; por isso, um script deve verificar o código de saída do novomodelo run para saber
se a execução foi bem-sucedida (Verificando os códigos de saída). bounds contém os limites inferior e superior finais. O
gap de convergência fica em convergence:
jq '.convergence.final_gap_percent' /path/to/my_study/output/training/metadata.jsonconvergence.achieved é true quando os critérios de parada encerraram a execução e um critério gap
ou bound_stalling foi satisfeito naquela iteração, de modo que uma execução interrompida apenas por
iteration_limit ou time_limit registra false.
convergence.termination_reason indica o critério de parada que encerrou o treinamento
(iteration_limit, time_limit, bound_stalling ou gap),
vale graceful_shutdown quando apenas uma solicitação de encerramento o terminou, ou error
após um treinamento que falhou:
jq -r '.convergence.termination_reason' /path/to/my_study/output/training/metadata.jsonNo Python, novomodelo.results.load_results("/path/to/my_study/output") retorna
os dois arquivos de metadados como dicionários, e novomodelo.results.load_convergence /
novomodelo.results.load_simulation carregam as tabelas Parquet. Veja
Convergência e diagnóstico para a leitura da
trajetória de convergência e das saídas da simulação, e Formato de saída para todos os campos
de training/metadata.json e
simulation/metadata.json.
Reaproveitando uma política salva
Seção intitulada “Reaproveitando uma política salva”Uma execução grava o checkpoint de sua política em policy.path; uma execução posterior pode simulá-la,
iniciar o treinamento a partir dela ou retomá-la, e outro estudo pode usá-la como sua fronteira
terminal (Gerenciamento da política).
Simulação com uma política salva
Seção intitulada “Simulação com uma política salva”Defina training.enabled como false para simular uma política salva sem
treinar novamente. training.selection e training.stopping_rules continuam
obrigatórios. A configuração completa e as verificações de carga da política estão em
Gerenciamento da política — Modo Somente Simulação.
Partida a quente a partir de uma política salva
Seção intitulada “Partida a quente a partir de uma política salva”Defina policy.mode como "warm_start" para iniciar o treinamento a partir de uma política salva; o treinamento
acrescenta novos cortes aos já salvos. Veja
Gerenciamento da política — Partida a quente.
Retomando um treinamento interrompido
Seção intitulada “Retomando um treinamento interrompido”Defina policy.mode como "resume" para continuar um treinamento interrompido a partir do seu checkpoint.
O maior iteration_limit é um total que inclui as iterações já concluídas; portanto,
defina-o acima desse número. Veja
Gerenciamento da política — Retomada.
Treinamento em etapas
Seção intitulada “Treinamento em etapas”Quando o limite de tempo de relógio de um escalonador de tarefas é menor do que o treinamento exige, treine em
etapas: cada etapa posterior define policy.mode como "resume" e aumenta o
total de iteration_limit.
Veja Gerenciamento da política — Treinar em Etapas.
Fluxos de trabalho comuns
Seção intitulada “Fluxos de trabalho comuns”Somente treinamento
Seção intitulada “Somente treinamento”Para executar o treinamento sem simulação, defina simulation.enabled como false no
config.json:
{ "simulation": { "enabled": false } }Multithreading
Seção intitulada “Multithreading”Use --threads para acelerar o treinamento e a simulação com paralelismo dentro
de cada processo:
novomodelo run /path/to/my_study --threads 4O trecho abaixo compara uma thread com quatro no caso gerado, com
training.selection.forward_passes definido como 8 e simulation.selection.num_scenarios
definido como 1000. Cada bloco começa com o comando que o produziu, e o trecho mantém
apenas a linha Threads e a linha de conclusão de cada fase. Os tempos são de uma única máquina:
$ novomodelo run my_study --threads 1 Threads: 1 rayon threadTraining complete in 7.1s (128 iterations, iteration_limit)Simulation complete in 12.8s (1000 scenarios)
$ novomodelo run my_study --threads 4 Threads: 4 rayon threadsTraining complete in 3.2s (128 iterations, iteration_limit)Simulation complete in 5.0s (1000 scenarios)--threads define as threads de trabalho de cada processo (cada rank MPI). Recebe um
inteiro maior ou igual a 1, com padrão 1. O conjunto de threads resolve em paralelo os PLs da simulação forward,
da simulação backward e da simulação final, de modo que o ganho de velocidade é limitado pelo
trabalho paralelo disponível: as simulações forward por iteração, os estados visitados da
simulação backward e os cenários de simulação. No trecho, o treinamento roda cerca de duas vezes mais rápido com quatro threads e a simulação, cerca de duas vezes e meia: neste caso, as resoluções dos PLs ocupam a maior parte do tempo de relógio de cada fase, e elas são executadas em paralelo. Veja
Aceleradores de desempenho para o modelo de execução.
Backend de comunicação
Seção intitulada “Backend de comunicação”Um único novomodelo run usa o backend local (processo único); a execução sob um
lançador MPI (mpiexec, mpirun ou srun) distribui o trabalho entre os processos quando o binário é compilado com suporte a MPI (o binário novomodelo-mpi de Implantação em HPC e clusters); o binário padrão novomodelo oferece apenas o backend local, de modo que, sob um lançador, auto executa cada processo como um estudo independente de processo único.
Por padrão (--comm-backend auto), o novomodelo detecta o lançador e seleciona o
backend de acordo, de modo que nenhuma flag é necessária em nenhum dos casos. Passe
--comm-backend mpi para forçar o backend MPI — ele falha com uma mensagem clara em um
binário compilado sem suporte a MPI — ou --comm-backend local para forçar um único
processo mesmo sob um lançador.
Modo silencioso para scripts
Seção intitulada “Modo silencioso para scripts”novomodelo run /path/to/my_study --quietexit_code=$?if [ $exit_code -ne 0 ]; then echo "Study failed with exit code $exit_code" >&2fiSuprime o cabeçalho e a saída de progresso, adequado para scripts em lote.
Verificando os códigos de saída
Seção intitulada “Verificando os códigos de saída”O novomodelo run sai com 0 em caso de sucesso e com valor diferente de zero nos demais casos. O significado de cada código
está em Referência da CLI — Códigos de saída.
Solução de problemas lista as mensagens de erro com sua causa
e correção.
Exportando os artefatos estocásticos
Seção intitulada “Exportando os artefatos estocásticos”Defina exports.stochastic como true no config.json para gravar os artefatos do
pré-processamento estocástico em output/stochastic/ antes do início do treinamento:
{ "exports": { "stochastic": true }}A exportação contém o modelo estocástico usado pela execução. Artefatos estocásticos lista cada arquivo, a condição em que é gravado e seu esquema.
Fluxo de ida e volta
Seção intitulada “Fluxo de ida e volta”Um modelo exportado pode ser lido de volta como entrada. Execute uma vez com a exportação habilitada,
copie os arquivos de entrada exportados para scenarios/, declare a árvore de
aberturas e execute novamente:
# Passo 1: execução inicial com a exportação estocástica habilitada no config.jsonnovomodelo run my_case
# Passo 2: copiar os arquivos de entrada exportados para scenarios/S=my_case/output/stochasticcp "$S/noise_openings.parquet" "$S/inflow_seasonal_stats.parquet" \ "$S/inflow_ar_coefficients.parquet" "$S/inflow_annual_component.parquet" \ my_case/scenarios/O noise_openings.parquet exportado numera seus estágios pela posição com base 0,
de modo que a árvore copiada só é carregada quando os ids de estágio declarados no caso são 0, 1, 2,
…; com outros ids de estágio, a carga a recusa.
Mantenha inflow_annual_component.parquet na cópia mesmo quando ele não tiver linhas:
sem ele, um modelo com componente anual é lido de volta como um modelo PAR(p)
clássico com os mesmos coeficientes AR, o que é um modelo diferente e
pode fazer a carga falhar. Copie também correlation.json quando seu objeto profiles
não estiver vazio. Com os dois arquivos de afluência copiados, a nova execução não estima nada; assim,
sem correlation.json, ela não tem perfis de correlação, e o ruído que
sorteia é não correlacionado entre as hidrelétricas. Deixe o arquivo de fora quando profiles estiver
vazio, porque o carregador recusa um correlation.json sem perfil. Copie
load_seasonal_stats.parquet quando a exportação o tiver gravado.
O passo 3 declara a árvore de aberturas no config.json, acrescentando uma chave ao
objeto training.scenario_source existente. O novomodelo run lê
scenarios/noise_openings.parquet apenas quando training.scenario_source.openings
é {"source": "file"}; um arquivo copiado sem a declaração é ignorado, e
a árvore é gerada novamente:
{ "training": { "scenario_source": { "openings": { "source": "file" } } }}O passo 4 executa o estudo novamente com novomodelo run my_case. A nova execução lê o
modelo de afluências dos arquivos de afluência copiados, em vez de estimar qualquer parte dele
a partir de inflow_history.parquet, e lê a árvore de aberturas de
scenarios/noise_openings.parquet, em vez de gerá-la. O arquivo da árvore deve
conter num_openings aberturas para todos os estágios, caso contrário a carga falha; uma árvore que
a primeira execução limitou a menos aberturas, com um aviso, não passa nessa verificação. As
demais condições sobre o arquivo estão em
Arquivos de cenários.
Veja também
Seção intitulada “Veja também”- Teoria: Algoritmo da PDDE — o algoritmo de simulações forward/backward que este fluxo de trabalho treina e executa.
- Solução de problemas: Solução de problemas — mensagens de erro, sua causa e a correção
- Agentes de IA: Agentes de IA (novomodelo-mcp) — execute este fluxo de trabalho por meio de um cliente MCP