Pular para o conteúdo

Arquivos de metadados

Tanto training/metadata.json quanto simulation/metadata.json usam um protocolo de gravação atômica:

  1. Serializa o JSON em um arquivo temporário irmão .json.tmp.
  2. Renomeia atomicamente o arquivo .tmp para o caminho de destino.

Isso garante que os consumidores nunca vejam um arquivo parcial. Se um arquivo de metadados existe, ele contém um documento JSON completo e válido. Se uma execução for interrompida antes da gravação final, o arquivo irmão .tmp pode permanecer, mas o arquivo de destino reflete a última gravação concluída com sucesso.

status é "complete" ou "partial". Em training/metadata.json, é "partial" quando uma solicitação de encerramento terminou o treinamento (training) e nem os critérios de parada nem o limite de iterações o terminaram naquela iteração: um sinal enviado a novomodelo run, ou uma parada solicitada por um callback Python on_iteration. Em simulation/metadata.json, é "partial" para uma simulação final pulada após uma parada por sinal. Qualquer outro término registra "complete", inclusive um treinamento com falha; por isso, consulte convergence.termination_reason ("error" em caso de falha) e o código de saída. convergence.achieved é true quando os critérios de parada terminaram o treinamento com uma regra gap ou bound_stalling acionada naquela iteração. Para a simulação, consulte scenarios.failed.

Ambos os arquivos são JSON simples, de modo que o jq os lê diretamente. Para um script ou verificação de CI, veja Formato de saída na Referência da CLI.

A partir do Python, novomodelo.results.load_results(output_dir) retorna ambos os documentos de metadados em um único dict, juntamente com um indicador complete por fase — veja o Guia rápido em Python.


O arquivo de metadados do treinamento é gravado atomicamente ao final da execução do treinamento. Ele reúne em um único arquivo o contexto da execução, a configuração, o resultado da convergência, as estatísticas do conjunto de linhas (cortes), os limites da função objetivo, as estatísticas do solver de PL e as informações de distribuição. O bloco convergence registra como a execução terminou.

Metodologia: Determinismo e rastreabilidade · Critérios de parada

Exemplo (um novomodelo run do modelo 1dtoy; hostname e marcas de tempo substituídos):

{
"software": "novomodelo",
"software_version": "0.21.0",
"hostname": "<hostname>",
"solver": "highs",
"solver_version": "1.13.1",
"started_at": "<timestamp>",
"completed_at": "<timestamp>",
"duration_seconds": 0.437,
"status": "complete",
"configuration": {
"seed": null,
"max_iterations": 128,
"forward_passes": 1,
"stopping_mode": "any",
"policy_mode": "fresh"
},
"problem_dimensions": {
"num_stages": 4,
"num_hydros": 1,
"num_thermals": 2,
"num_buses": 1,
"num_lines": 0
},
"iterations": {
"completed": 128,
"converged_at": null
},
"convergence": {
"achieved": false,
"final_gap_percent": -97.18864856046982,
"termination_reason": "iteration_limit"
},
"row_pool": {
"total_generated": 384,
"total_active": 384,
"peak_active": 384,
"cuts_active": 384,
"rows_in_lp_total": 0,
"rows_in_lp_solve_count": 0,
"rows_in_lp_max": 0,
"total_loaded": 0
},
"bounds": {
"final_lower_bound": 20616141.776970606,
"final_upper_bound": 579592.1986224449,
"final_upper_bound_std": 0.0,
"final_upper_bound_kind": "statistical"
},
"solve_stats": {
"total_lp_solves": 5632,
"first_try": 5632,
"retried": 0,
"failed": 0,
"forward_solve_seconds": 0.04809124599999996,
"backward_solve_seconds": 0.22707765300000007,
"parallelism": 1
},
"setup": {
"load_seconds": 0.004459241,
"stochastic_fit_seconds": 0.00019873,
"production_fit_seconds": 0.000031599,
"evaporation_fit_seconds": 1.004e-6,
"broadcast_seconds": 0.000458009
},
"distribution": {
"backend": "local",
"world_size": 1,
"ranks_participated": 1,
"num_hosts": 1,
"threads_per_rank": 1,
"hosts": [
{
"hostname": "<hostname>",
"ranks": [0]
}
]
}
}

Campos de nível superior:

NomeTipoAnulávelUnidadesDescrição
softwarestringNão—Nome do software que produziu esta saída: "novomodelo".
software_versionstringNão—Versão desse software, por exemplo "0.21.0".
hostnamestringNão—Hostname da máquina que executou o treinamento.
solverstringNão—Solver de PL: "highs" ou "clp".
solver_versionstringSim—String de versão da biblioteca do solver de PL vinculada. Omitido quando não disponível.
started_atstringNão—Marca de tempo ISO 8601 do início do treinamento.
completed_atstringNão—Marca de tempo ISO 8601 da conclusão do treinamento.
duration_secondsnumberNãosDuração total do treinamento em tempo de relógio (wall-clock), em segundos.
statusstringNão—"partial" quando apenas uma solicitação de encerramento terminou o treinamento (então convergence.termination_reason é "graceful_shutdown"); "complete" nos demais casos, inclusive um treinamento com falha; convergence.termination_reason registra como a execução terminou ("error" quando o treinamento parou por falha).
production_fit_deviationobjectSim—Consolidação, para a execução, do desvio de ajuste do modelo de produção por entidade (informativo, nunca incluído em hash). Omitido quando a execução não ajustou nenhum modelo cujo desvio seja medido.

Campos de configuration:

NomeTipoAnulávelUnidadesDescrição
configuration.seedintegerSim—O training.tree_seed configurado; null quando ausente (a execução então usa 42).
configuration.max_iterationsintegerSim—Número máximo de iterações: o limit da primeira entrada iteration_limit de training.stopping_rules; sempre definido em um arquivo gravado por novomodelo run, pois a configuração deve conter uma regra iteration_limit.
configuration.forward_passesintegerSim—Número de trajetórias de cenários da simulação forward por iteração. null sob a seleção enumerated.
configuration.stopping_modestringNão—Como múltiplos critérios de parada se combinam: "any" ou "all".
configuration.policy_modestringNão—Modo de partida a quente (warm-start) da política: "fresh", "warm_start" ou "resume".

Campos de problem_dimensions:

NomeTipoAnulávelUnidadesDescrição
problem_dimensions.num_stagesintegerNão—Número de estágios: os estágios do estudo mais os eventuais estágios pré-estudo.
problem_dimensions.num_hydrosintegerNão—Número total de usinas hidrelétricas.
problem_dimensions.num_thermalsintegerNão—Número total de usinas termelétricas.
problem_dimensions.num_busesintegerNão—Número total de barramentos.
problem_dimensions.num_linesintegerNão—Número total de linhas de transmissão.

Campos de iterations:

NomeTipoAnulávelUnidadesDescrição
iterations.completedintegerNão—Número de iterações de treinamento concluídas.
iterations.converged_atintegerSim—Igual a completed quando achieved é true; null caso contrário.

Campos de convergence:

NomeTipoAnulávelUnidadesDescrição
convergence.achievedbooleanNão—true quando os critérios de parada configurados terminaram o treinamento e uma regra gap ou bound_stalling foi acionada naquela iteração, mesmo que termination_reason indique outra regra acionada na mesma iteração; false quando apenas iteration_limit ou time_limit foram acionados, quando apenas uma solicitação de encerramento terminou o treinamento e após uma falha.
convergence.final_gap_percentnumberSim%Gap de otimalidade entre os limites inferior e superior no término, em porcentagem. null quando o limite inferior final não é positivo.
convergence.termination_reasonstringNão—Nome do critério de parada que terminou a execução: "iteration_limit", "time_limit", "bound_stalling" ou "gap" (sob "all", a primeira regra diferente de iteration_limit, ou "iteration_limit" quando o maior limite encerrou a execução); "error" quando o treinamento parou por falha, caso em que novomodelo run termina com código diferente de zero; "graceful_shutdown" quando uma solicitação de encerramento terminou o treinamento e nem os critérios de parada nem o limite de iterações o terminaram naquela iteração (um SIGTERM ou SIGINT enviado a novomodelo run, ou um callback on_iteration de novomodelo.Study.train ou novomodelo.run.run que retorna um valor verdadeiro ou lança uma exceção).

Campos de row_pool:

NomeTipoAnulávelUnidadesDescrição
row_pool.total_generatedintegerNão—Total de linhas de corte geradas ao longo de toda a execução.
row_pool.total_activeintegerNão—Linhas de corte ainda ativas no conjunto de cortes ao término.
row_pool.peak_activeintegerNão—Maior número de linhas de corte ativas, somado sobre os conjuntos, na troca de cortes de uma iteração ou após sua etapa de seleção e limite. É no mínimo o maior cuts_active em training/convergence.parquet, que conta apenas após a gestão de linhas.
row_pool.cuts_activeintegerNão—Linhas de corte ativas ao término; o mesmo valor de total_active.
row_pool.rows_in_lp_totalintegerNão—Soma das linhas residentes no PL sobre todas as resoluções com seleção preguiçosa (lazy) da execução. Zero quando não houve seleção preguiçosa.
row_pool.rows_in_lp_solve_countintegerNão—Número de resoluções com seleção preguiçosa na execução. Zero quando não houve seleção preguiçosa.
row_pool.rows_in_lp_maxintegerNão—Maior número de linhas residentes no PL em uma única resolução com seleção preguiçosa. Zero quando não houve seleção preguiçosa.
row_pool.total_loadedintegerNão—Linhas de corte carregadas no início da execução, em vez de geradas pelo treinamento (a soma do warm_start_count de todos os conjuntos): os cortes que uma execução com partida a quente carrega de policy.path, mais eventuais cortes de policy.boundary. Uma execução retomada mantém a contagem da execução registrada, pois os cortes gerados por aquela execução continuam contados como gerados. Subconjunto de total_generated. 0 em uma execução nova sem policy.boundary.

Campos de bounds:

NomeTipoAnulávelUnidadesDescrição
bounds.final_lower_boundnumberNão—Limite inferior final da função objetivo no término.
bounds.final_upper_boundnumberSim—Valor final do limite superior; sempre um número em um arquivo gravado por novomodelo run.
bounds.final_upper_bound_stdnumberSim—Desvio-padrão amostral dos custos dos cenários da simulação forward da última iteração concluída. null quando final_upper_bound_kind é "exact".
bounds.final_upper_bound_kindstringNão—Regime do limite superior da execução: "exact" sob a seleção enumerated, "statistical" sob a seleção sampled; o mesmo valor de upper_bound_kind em todas as linhas de training/convergence.parquet. Sob "exact", o gap entre os limites é um certificado de otimalidade válido apenas quando a medida de risco é a mesma em todos os estágios; sob uma medida que varia por estágio, final_upper_bound é o custo esperado da política, que pode ficar abaixo de final_lower_bound (veja Gerenciamento de cortes — quando os limites e certificados são válidos).

Campos de solve_stats:

NomeTipoAnulávelUnidadesDescrição
solve_stats.total_lp_solvesintegerSim—Número total de resoluções de PL realizadas durante o treinamento.
solve_stats.first_tryintegerSim—Número de resoluções de PL bem-sucedidas na primeira tentativa.
solve_stats.retriedintegerSim—Número de resoluções de PL bem-sucedidas após uma ou mais novas tentativas.
solve_stats.failedintegerSim—Número de resoluções de PL que falharam definitivamente.
solve_stats.forward_solve_secondsnumberSimsSegundos acumulados (wall-clock) nas resoluções de PL da fase forward.
solve_stats.backward_solve_secondsnumberSimsSegundos acumulados (wall-clock) nas resoluções de PL da fase backward.
solve_stats.parallelismintegerSim—Número de workers usados durante o treinamento: as threads de trabalho por processo (rank MPI) vezes o número de processos MPI.

Cada resolução de PL da execução é contada uma única vez, qualquer que seja o processo e o worker que a executou; assim, um estudo informa os mesmos total_lp_solves, first_try, retried e failed para qualquer número de processos MPI, e first_try + retried + failed é igual a total_lp_solves. A linha LP solves do resumo do treinamento imprime as mesmas contagens. Sob MPI, forward_solve_seconds e backward_solve_seconds também são totais sobre todos os processos e workers, com cada resolução contada uma vez. As resoluções do limite inferior entram nas contagens de resultado, mas em nenhum dos campos de tempo.

Campos de distribution:

NomeTipoAnulávelUnidadesDescrição
distribution.backendstringNão—Backend de comunicação: "mpi" ou "local".
distribution.world_sizeintegerNão—Número total de processos no comunicador. 1 em execuções de processo único.
distribution.ranks_participatedintegerNão—Número de processos que participaram do cálculo.
distribution.num_hostsintegerNão—Número de hosts físicos distintos.
distribution.threads_per_rankintegerNão—Threads de trabalho por processo.
distribution.mpi_librarystringSim—Versão da implementação MPI (ex.: "Open MPI v4.1.6"). Omitido no backend local.
distribution.mpi_standardstringSim—Versão do padrão MPI (ex.: "MPI 4.0"). Omitido no backend local.
distribution.thread_levelstringSim—Nível de segurança de threads MPI negociado. Omitido no backend local.
distribution.slurm_job_idstringSim—ID do job SLURM quando executado sob SLURM. Omitido nos demais casos.
distribution.hostsarrayNão—Atribuição de processos por host. Uma entrada por host físico. Em execuções locais de processo único, contém uma única entrada com ranks: [0].
distribution.hosts[].hostnamestringNão—Hostname desta entrada.
distribution.hosts[].ranksarrayNão—Array de inteiros: ranks globais, em ordem crescente, atribuídos a este host.

Campos de setup (informativos):

NomeTipoAnulávelUnidadesDescrição
setup.load_secondsnumberNãosSegundos (wall-clock) gastos na carga do caso de entrada.
setup.stochastic_fit_secondsnumberNãosSegundos (wall-clock) gastos no ajuste do processo estocástico.
setup.production_fit_secondsnumberNãosSegundos (wall-clock) gastos no ajuste do modelo de produção (hiperplanos da FPHA).
setup.evaporation_fit_secondsnumberNãosSegundos (wall-clock) gastos no ajuste do modelo de evaporação.
setup.broadcast_secondsnumberNãosSegundos (wall-clock) gastos na difusão (broadcast) dos dados de preparação entre os processos MPI.

Esses valores não são determinísticos: variam de uma execução para outra conforme a carga da máquina e são excluídos de qualquer verificação de paridade.

Campos de production_fit_deviation (ausentes quando a execução não ajustou nenhum modelo cujo desvio seja medido):

NomeTipoAnulávelUnidadesDescrição
production_fit_deviation.n_entriesintegerNão—Número de entradas por entidade resumidas na consolidação.
production_fit_deviation.mean_absnumberNão—Média aritmética das magnitudes do desvio absoluto médio de cada entrada.
production_fit_deviation.max_absnumberNão—Máximo das magnitudes do desvio absoluto máximo de cada entrada.
production_fit_deviation.worst_relativenumberNão—Maior desvio relativo (adimensional) por entrada entre todas as entradas.
production_fit_deviation.worst_entryobjectSim—A entrada com o maior desvio relativo. null quando não há entradas.

Campos de production_fit_deviation.worst_entry:

NomeTipoAnulávelUnidadesDescrição
production_fit_deviation.worst_entry.entity_idintegerNão—Identificador da entidade à qual pertence a pior entrada.
production_fit_deviation.worst_entry.stage_idintegerNão—Id declarado (em stages.json) do primeiro estágio coberto pela pior entrada.
production_fit_deviation.worst_entry.relativenumberNão—Desvio relativo (adimensional) da pior entrada.
production_fit_deviation.worst_entry.mean_absnumberNão—Magnitude do desvio absoluto médio da pior entrada.
production_fit_deviation.worst_entry.max_absnumberNão—Magnitude do desvio absoluto máximo da pior entrada.

O arquivo de metadados da simulação é gravado atomicamente quando a simulação final é concluída, e também quando uma parada por sinal termina o treinamento antes de uma simulação configurada: a simulação é então pulada, e o arquivo registra status "partial", scenarios.completed 0 e cost null, seguido de simulation/_SUCCESS. Ele contém o contexto da execução, as contagens de cenários concluídos, estatísticas agregadas de custo, estatísticas do solver de PL e informações de distribuição.

Metodologia: Determinismo e rastreabilidade

Exemplo (o mesmo novomodelo run do modelo 1dtoy; hostname e marcas de tempo substituídos):

{
"software": "novomodelo",
"software_version": "0.21.0",
"hostname": "<hostname>",
"solver": "highs",
"solver_version": "1.13.1",
"started_at": "<timestamp>",
"completed_at": "<timestamp>",
"duration_seconds": 0.565,
"status": "complete",
"scenarios": {
"total": 100,
"completed": 100,
"failed": 0
},
"cost": {
"mean_cost": 12865159.706109216,
"std_cost": 29290918.998702876
},
"solve_stats": {
"total_lp_solves": 400,
"first_try": 400,
"retried": 0,
"failed": 0,
"solve_seconds": 0.3042452130000002,
"parallelism": 1
},
"distribution": {
"backend": "local",
"world_size": 1,
"ranks_participated": 1,
"num_hosts": 1,
"threads_per_rank": 1,
"hosts": [
{
"hostname": "<hostname>",
"ranks": [0]
}
]
}
}

Campos de nível superior:

NomeTipoAnulávelUnidadesDescrição
softwarestringNão—Nome do software que produziu esta saída: "novomodelo".
software_versionstringNão—Versão desse software, por exemplo "0.21.0".
hostnamestringNão—Hostname da máquina que executou a simulação.
solverstringNão—Solver de PL: "highs" ou "clp".
solver_versionstringSim—String de versão da biblioteca do solver de PL. Omitido quando não disponível.
started_atstringNão—Marca de tempo ISO 8601 do início da simulação.
completed_atstringNão—Marca de tempo ISO 8601 da conclusão da simulação.
duration_secondsnumberNãosDuração total da simulação em tempo de relógio (wall-clock), em segundos.
statusstringNão—"complete" quando a simulação foi executada; "partial" quando uma parada por sinal a pulou (nenhum cenário foi executado).

Campos de scenarios:

NomeTipoAnulávelUnidadesDescrição
scenarios.totalintegerNão—Número de cenários cujas partições de saída foram gravadas; em uma simulação pulada (status "partial"), o número de cenários que a execução estava configurada para simular, com completed 0.
scenarios.completedintegerNão—Número de cenários cujas partições de saída foram gravadas.
scenarios.failedintegerNão—Número de cenários cujas partições de saída não puderam ser gravadas; uma falha na resolução de um PL, por sua vez, interrompe a execução com erro.

Campos de cost (null em uma simulação pulada):

NomeTipoAnulávelUnidadesDescrição
cost.mean_costnumberNãoR$Custo total médio sobre os cenários simulados.
cost.std_costnumberNãoR$Desvio-padrão do custo total sobre os cenários simulados.

Campos de solve_stats:

NomeTipoAnulávelUnidadesDescrição
solve_stats.total_lp_solvesintegerSim—Número total de resoluções de PL realizadas durante a simulação.
solve_stats.first_tryintegerSim—Número de resoluções de PL bem-sucedidas na primeira tentativa.
solve_stats.retriedintegerSim—Número de resoluções de PL bem-sucedidas após uma ou mais novas tentativas.
solve_stats.failedintegerSim—Número de resoluções de PL que falharam definitivamente.
solve_stats.solve_secondsnumberSimsSegundos acumulados (wall-clock) gastos nas resoluções de PL da simulação.
solve_stats.parallelismintegerSim—Número de workers usados durante a simulação: as threads de trabalho por processo (rank MPI) vezes o número de processos MPI.

Sob MPI, as contagens e solve_seconds são somas sobre todos os processos.

O objeto distribution tem a mesma estrutura de campos de training/metadata.json. Veja a tabela Campos de distribution acima.


Registra quais fontes de dados alimentaram os modelos de afluência e de produção hidrelétrica. Gravado em todo novomodelo run, antes do início do treinamento; tem finalidade de diagnóstico. Objeto de nível superior com dois subobjetos, inflow e hydro_production.

Metodologia: Determinismo e rastreabilidade · Modelo de afluências PAR(p)

Campos de inflow:

NomeTipoAnulávelUnidadesDescrição
inflow.estimation_pathstringNão—Rótulo estável do caminho de estimação adotado.
inflow.seasonal_stats_sourcestringNão—Origem dos dados sazonais de média/desvio-padrão: "estimated", "user_file" ou "n/a".
inflow.ar_coefficients_sourcestringNão—Origem dos coeficientes das defasagens do modelo AR (mesmo conjunto de valores).
inflow.correlation_sourcestringNão—Origem da correlação espacial: "user_file" quando o caso fornece scenarios/correlation.json, "estimated" quando ela é estimada a partir do histórico de afluências, "n/a" nos demais casos.
inflow.correlation_targetstringSim—Série a partir da qual a correlação estimada foi calculada, "inflows" ou "residuals" (estimation.correlation_target). null, a menos que correlation_source seja "estimated".
inflow.opening_tree_sourcestringNão—Origem da árvore de aberturas de ruídos (mesmo conjunto de valores).
inflow.opening_tree_moment_matchingstringSim—Correspondência de momentos (moment matching) de uma árvore de aberturas gerada, "per_coordinate" ou "none" (training.scenario_source.openings.moment_matching), registrado quer algum estágio tenha passado pela correspondência de momentos, quer não. null quando a árvore não foi gerada.
inflow.n_hydrosintegerNão—Número de usinas hidrelétricas do sistema.
inflow.ar_methodstringSim—Método de seleção de ordem usado quando os coeficientes AR foram estimados. null quando o AR não foi estimado.
inflow.ar_max_orderintegerSim—Ordem máxima do modelo AR entre todas as usinas hidrelétricas. null quando o AR não foi estimado.
inflow.white_noise_fallbacksarrayNão—Array de inteiros: IDs das usinas hidrelétricas que recorreram a ruído branco. Vazio quando nenhuma recorreu.
inflow.historical_library_seed_digestintegerSim—Impressão digital (fingerprint) da tendência hidrológica para a biblioteca histórica. Omitido quando nenhuma biblioteca foi construída.

Campos de hydro_production:

NomeTipoAnulávelUnidadesDescrição
hydro_production.n_fpha_computed_from_geometryintegerNão—Usinas hidrelétricas cujos hiperplanos da FPHA foram calculados a partir da geometria do reservatório; uma usina com FPHA calculada e sem capacidade de turbinamento não é contada.
hydro_production.n_fpha_precomputed_hyperplanesintegerNão—Usinas hidrelétricas cujos hiperplanos da FPHA foram fornecidos pré-calculados; uma usina com FPHA pré-calculada, sem capacidade de turbinamento e sem linhas de hiperplano não é contada.
hydro_production.n_evaporation_ref_user_suppliedintegerNão—Usinas hidrelétricas cujo nível de referência para evaporação foi fornecido pelo usuário.
hydro_production.n_evaporation_ref_default_midpointintegerNão—Usinas hidrelétricas cujo nível de referência para evaporação assumiu o padrão, o ponto médio da curva.