Pular para o conteúdo

Formato de saída

Estas páginas constituem a referência completa de esquemas de todos os arquivos que o novomodelo run grava: nomes de colunas, tipos Arrow, anulabilidade, unidades, campos JSON e o checkpoint binário. Esta página apresenta a árvore do diretório de saída, os marcadores de sucesso e o layout de partições Hive; o esquema de cada arquivo está na página do respectivo grupo.

Se você está começando com as saídas do Novo Modelo, comece por Convergência e diagnóstico. Essa página explica como ler os resultados programaticamente e avaliar a convergência. As páginas de grupo destinam-se a quem precisa da definição precisa dos esquemas — para escrever parsers, montar painéis ou implementar verificações de compatibilidade.


A tabela lista cada arquivo que o novomodelo run pode gravar, na ordem da árvore de diretórios abaixo, com a página que o documenta.

ArquivoPágina
training/metadata.jsonArquivos de metadados
training/convergence.parquetSaídas do treinamento
training/dictionaries/Saídas do treinamento
training/dictionaries/codes.jsonSaídas do treinamento
training/dictionaries/entities.csvSaídas do treinamento
training/dictionaries/variables.csvSaídas do treinamento
training/dictionaries/bounds.parquetSaídas do treinamento
training/timing/iterations.parquetSaídas do treinamento
training/solver/iterations.parquetSaídas do treinamento
training/solver/retry_histogram.parquetSaídas do treinamento
training/scaling_report.jsonSaídas do treinamento
training/hydro_models.jsonArtefatos dos modelos hidrelétricos
training/model_provenance.jsonArquivos de metadados
training/cut_selection/iterations.parquetSaídas do treinamento
training/_SUCCESSFormato de Saída
policy/manifest.binCheckpoint da política
policy/cuts/NNN.binCheckpoint da política
policy/basis/NNN.binCheckpoint da política
policy/states/NNN.binCheckpoint da política
simulation/metadata.jsonArquivos de metadados
simulation/paths.parquetSaídas da simulação
simulation/scenario_summary.parquetSaídas da simulação
simulation/costs/Saídas da simulação
simulation/hydros/Saídas da simulação
simulation/hydro_bus_generation/Saídas da simulação
simulation/thermals/Saídas da simulação
simulation/exchanges/Saídas da simulação
simulation/buses/Saídas da simulação
simulation/pumping_stations/Saídas da simulação
simulation/contracts/Saídas da simulação
simulation/non_controllables/Saídas da simulação
simulation/inflow_lags/Saídas da simulação
simulation/in_transit/Saídas da simulação
simulation/transit_seed/Saídas da simulação
simulation/anticipated_lanes/Saídas da simulação
simulation/violations/generic/Saídas da simulação
simulation/solver/iterations.parquetSaídas da simulação
simulation/solver/retry_histogram.parquetSaídas da simulação
simulation/_SUCCESSFormato de Saída
anticipated/fixed_deliveries.parquetSaídas da simulação
generic_constraints/resolved_echo.parquetSaídas da simulação
hydro_models/fpha_hyperplanes.parquetArtefatos dos modelos hidrelétricos
hydro_models/evaporation_models.parquetArtefatos dos modelos hidrelétricos
hydro_models/fpha_deviation_points.parquetArtefatos dos modelos hidrelétricos
stochastic/inflow_seasonal_stats.parquetArtefatos estocásticos
stochastic/inflow_ar_coefficients.parquetArtefatos estocásticos
stochastic/inflow_annual_component.parquetArtefatos estocásticos
stochastic/correlation.jsonArtefatos estocásticos
stochastic/fitting_report.jsonArtefatos estocásticos
stochastic/noise_openings.parquetArtefatos estocásticos
stochastic/load_seasonal_stats.parquetArtefatos estocásticos

Uma execução completa do novomodelo run produz a estrutura de diretórios a seguir. Nem todo diretório de entidade aparece em todas as execuções: o novomodelo run só grava diretórios para os tipos de entidade presentes no caso. Por exemplo, um caso sem usinas elevatórias não produz simulation/pumping_stations/.

<output_dir>/
training/
metadata.json
convergence.parquet
dictionaries/
codes.json
entities.csv
variables.csv
bounds.parquet
timing/
iterations.parquet
solver/
iterations.parquet
retry_histogram.parquet
scaling_report.json
hydro_models.json (sempre)
model_provenance.json (sempre)
cut_selection/
iterations.parquet (quando há método de seleção ou max_active_per_stage definido)
_SUCCESS # após training/metadata.json
policy/ # em policy.path (padrão ./policy), resolvido em relação ao diretório de saída
manifest.bin # global do estudo; FlatBuffers, gravado por último
cuts/ # indexado por conjunto de cortes
000.bin
001.bin
...
NNN.bin
basis/ # indexado por nó
000.bin
001.bin
...
NNN.bin
states/ # indexado por conjunto de cortes; com exports.states ou level1
000.bin
001.bin
...
NNN.bin
simulation/
metadata.json
paths.parquet
scenario_summary.parquet
costs/
scenario_id=0000/
data.parquet
scenario_id=0001/
data.parquet
...
hydros/
scenario_id=0000/data.parquet
...
hydro_bus_generation/
scenario_id=0000/data.parquet
...
thermals/
scenario_id=0000/data.parquet
...
exchanges/
scenario_id=0000/data.parquet
...
buses/
scenario_id=0000/data.parquet
...
pumping_stations/
scenario_id=0000/data.parquet
...
contracts/
scenario_id=0000/data.parquet
...
non_controllables/
scenario_id=0000/data.parquet
...
inflow_lags/
scenario_id=0000/data.parquet
...
in_transit/ # quando há trecho com tempo de viagem declarado
scenario_id=0000/data.parquet
...
transit_seed/ # quando há trecho com tempo de viagem declarado
scenario_id=0000/data.parquet
...
anticipated_lanes/ # quando o estudo declara post_study_stages
scenario_id=0000/data.parquet
...
violations/
generic/
scenario_id=0000/data.parquet
...
solver/
iterations.parquet
retry_histogram.parquet
_SUCCESS # após simulation/metadata.json
anticipated/ # quando existe compromisso pós-horizonte decidido antes do estudo
fixed_deliveries.parquet
generic_constraints/ # quando o estudo tem restrições genéricas
resolved_echo.parquet
hydro_models/
fpha_hyperplanes.parquet (quando um ajuste calculado produz planos)
evaporation_models.parquet (quando alguma usina tem evaporação)
fpha_deviation_points.parquet (quando exports.fpha_deviation_points = true e existe ponto de desvio)
stochastic/ # somente quando exports.stochastic = true (desativado por padrão)
inflow_seasonal_stats.parquet (sempre, quando exportado)
inflow_ar_coefficients.parquet (sempre, quando exportado)
inflow_annual_component.parquet (sempre, quando exportado)
correlation.json (sempre, quando exportado)
fitting_report.json (quando houve estimação)
noise_openings.parquet (sempre, quando exportado)
load_seasonal_stats.parquet (quando algum modelo de carga tem std_mw > 0)

Todo arquivo Parquet de saída é gravado com compressão ZSTD (nível 3), codificação por dicionário e grupos de linhas de no máximo 100 000 linhas.


O novomodelo run grava seus arquivos em uma ordem fixa. training/_SUCCESS é um arquivo vazio gravado por último quando houve treinamento (training), e simulation/_SUCCESS, um arquivo gravado por último quando houve simulação:

  1. Antes do início do treinamento: quando o treinamento vai ser executado, o training/_SUCCESS obsoleto e os arquivos condicionais do treinamento (training/cut_selection/, arquivos de training/solver/, anticipated/fixed_deliveries.parquet, hydro_models/*.parquet, generic_constraints/resolved_echo.parquet) são removidos; quando a simulação vai ser executada, simulation/_SUCCESS e toda saída de simulação anterior (cada árvore simulation/<family>/, arquivos de simulation/solver/, paths.parquet, scenario_summary.parquet e metadata.json) são removidos; em seguida, são gravados training/hydro_models.json, training/model_provenance.json, as exportações de stochastic/ (quando exports.stochastic = true) e training/scaling_report.json.
  2. Durante o treinamento: checkpoints periódicos em policy.path quando policy.checkpointing.enabled é true.
  3. Após o treinamento: o checkpoint da política em policy.path (policy/ por padrão; manifest.bin por último dentro dele), depois training/dictionaries/, training/convergence.parquet, training/timing/iterations.parquet e training/metadata.json, depois hydro_models/fpha_hyperplanes.parquet, hydro_models/evaporation_models.parquet, hydro_models/fpha_deviation_points.parquet, generic_constraints/resolved_echo.parquet, anticipated/fixed_deliveries.parquet, training/solver/iterations.parquet, training/solver/retry_histogram.parquet e training/cut_selection/iterations.parquet, cada um somente quando a execução tem conteúdo para ele, e então training/_SUCCESS.
  4. Durante a simulação: as partições de entidades em simulation/, à medida que os cenários são executados.
  5. Após a simulação: simulation/metadata.json, simulation/solver/iterations.parquet, simulation/solver/retry_histogram.parquet, simulation/paths.parquet e simulation/scenario_summary.parquet, e então simulation/_SUCCESS.

Uma exportação de stochastic/ nunca é removida, e uma execução somente de treinamento preserva uma árvore simulation/ anterior, incluindo seu _SUCCESS.

Um marcador _SUCCESS, portanto, sinaliza que sua fase terminou de gravar; os arquivos de stochastic/ não são cobertos por nenhum dos marcadores. Ele não é um veredito sobre a execução: quando o treinamento é interrompido por falha, o novomodelo run grava o checkpoint da política em <policy.path>.partial, sem tocar em policy.path (ver Execução com falha), todas as saídas do treinamento (convergence.termination_reason é "error") e training/_SUCCESS, e então encerra com o código do erro (ver Códigos de saída). Uma execução que falha antes da última gravação de uma fase deixa essa fase sem marcador.

O status de saída do novomodelo run é o sinal do resultado da execução. Um cenário cujas partições de saída não puderam ser gravadas não o altera: o cenário é contabilizado em scenarios.failed de simulation/metadata.json, e a execução ainda assim grava simulation/_SUCCESS e encerra com 0. Um script que precise da saída de todos os cenários deve verificar scenarios.failed.


Todas as saídas Parquet da simulação usam particionamento Hive: os resultados de cada cenário são armazenados em um diretório chamado scenario_id=NNNN/ contendo um único arquivo data.parquet. scenario_id é ao mesmo tempo o diretório de partição Hive e uma coluna explícita Int32 não nula dentro de cada arquivo Parquet de entidade (a coluna inicial do eixo compartilhado (scenario_id, stage_id, node_id) — ver Eixo de nós e saídas do grafo da política). Uma junção tripla entre arquivos de entidades, ou uma junção com simulation/paths.parquet / simulation/scenario_summary.parquet, é, portanto, uma junção sobre colunas comuns, e não uma interpretação de nomes de diretório.

Todas as principais ferramentas de dados colunares entendem esse layout e conseguem ler um diretório simulation/<entity>/ inteiro como uma única tabela, seja inferindo scenario_id a partir dos nomes dos diretórios de partição, seja lendo-o diretamente da coluna no arquivo — ambos coincidem por construção. Receitas de leitura com Polars e pandas estão em Convergência e diagnóstico — Leitura de uma tabela inteira; os filtros de cenário em R e DuckDB estão em Filtragem para um único cenário.

Os IDs de cenário são inteiros com base zero. O número de partições scenario_id=NNNN/ gravadas é scenarios.completed em simulation/metadata.json.