Pular para o conteúdo

Configuração

Todos os parâmetros de execução de novomodelo run são controlados pelo config.json no diretório do caso. Esta página documenta todas as seções e campos. Todo objeto em config.json rejeita chaves desconhecidas, de modo que uma chave com erro de digitação faz a carga falhar com um erro de análise que indica a chave.


{
"training": {
"selection": { "method": "sampled", "forward_passes": 50 },
"stopping_rules": [{ "type": "iteration_limit", "limit": 100 }]
}
}

Todas as demais seções são opcionais, com os valores padrão documentados abaixo.


Todas as chaves de config.json até o segundo nível, com seu tipo e valor padrão; cada linha aponta para sua seção.

NomeTipoObrigatórioPadrãoUnidadesDescrição
trainingobjectSim——Controla a fase de treinamento (training) da PDDE (SDDP). Veja training.
training.selectionobjectSim——Método de seleção de cenários da simulação forward do treinamento, sampled ou enumerated; a chave é obrigatória. Veja training.selection.
training.stopping_rulesarraySim——Critérios que encerram o treinamento; a chave é obrigatória. Veja training.stopping_rules.
training.enabledbooleanNãotrue—Executa a fase de treinamento; false passa direto à simulação. Veja training.
training.tree_seedinteger | nullNãonull—Semente da árvore de aberturas; null resolve para 42. Veja Resolução das sementes.
training.stopping_modestringNão"any"—Um de "any", "all". Como vários critérios de parada se combinam. Veja training.stopping_mode.
training.cut_selectionobjectNão{}—Processo de gestão de linhas; a seleção de linhas fica desligada salvo se selection for definido. Veja training.cut_selection.
training.solverobjectNão{}—Sobrescritas, por fase, do perfil do solver de PL; as duas chaves retry_* são aceitas e não têm efeito. Veja training.solver.
training.parallelismobjectNão{}—Parâmetros de escalonamento dos trabalhadores da simulação backward. Veja training.parallelism.
training.scenario_sourceobject | nullNãonull—Fonte de ruído da simulação forward por classe; null usa in_sample para todas as classes. Veja training.scenario_source.
simulationobjectNão{}—Controla a fase de simulação pós-treinamento. Veja simulation.
simulation.enabledbooleanNãofalse—Executa a fase de simulação após o treinamento. Veja simulation.
simulation.selectionobject | nullNãonull—Método de seleção de cenários da fase de simulação; null resolve para 2000 cenários amostrados. Veja simulation.selection.
simulation.io_channel_capacityintegerNão64—Capacidade da fila entre os trabalhadores da simulação e o gravador de saída. Veja simulation.
simulation.solverobject | nullNãonull—Perfil do solver da fase de simulação; null mantém o perfil embutido. Veja Campos do perfil do solver.
simulation.scenario_sourceobject | nullNãonull—Fonte de cenários da fase de simulação; null reutiliza training.scenario_source. Veja simulation.scenario_source.
simulation.cut_setstringNão"all"—Um de "all", "active". Quais linhas da política os PLs de estágio da simulação contêm. Veja simulation.
modelingobjectNão{}—Controla opções de modelagem física. Veja modeling.
modeling.inflow_non_negativityobjectNão{}—Tratamento de sorteios negativos de afluência do modelo PAR. Veja modeling.inflow_non_negativity.
modeling.cost_scale_factornumber | nullNão1000000.0—Divisor de todo coeficiente da função objetivo que não seja de θ; null ou ausente usa o padrão. Veja modeling.cost_scale_factor.
estimationobjectNão{}—Controla o processo de estimação do modelo PAR(p). Veja estimation.
estimation.max_orderintegerNão6—Ordem máxima de defasagem considerada no ajuste do modelo. Veja estimation.
estimation.order_selectionstringNão"pacf"—Um de "pacf", "pacf_annual". Critério de seleção de ordem. Veja estimation.
estimation.min_observations_per_seasonintegerNão30—Mínimo recomendado de ocorrências do período sazonal totalmente cobertas por período sazonal e usina. Veja estimation.
estimation.max_coefficient_magnitudenumber | nullNãonull—Reduz um ajuste à ordem 0 quando algum coeficiente excede essa magnitude. Veja estimation.
estimation.correlation_targetstringNão"inflows"—Um entre "inflows", "residuals". Série a partir da qual uma correlação de afluências estimada é calculada. Veja estimation.
estimation.history_yearsobject | nullNãonull—Intervalo inclusivo {"from", "to"} dos anos de inflow_history.parquet que a estimação lê; null lê todos os anos. Veja estimation.
policyobjectNão{}—Controla a persistência da política. Veja policy.
policy.pathstringNão"./policy"—Diretório da política, resolvido em relação ao diretório de saída da execução. Veja policy.
policy.modestringNão"fresh"—Um de "fresh", "warm_start", "resume". Modo de inicialização. Veja policy.
policy.boundaryobject | nullNãonull—Cortes de fronteira terminal carregados do checkpoint de outro estudo. Veja policy.boundary.
policy.checkpointingobjectNão{}—Checkpoints periódicos durante o treinamento. Veja policy.checkpointing.
upper_bound_evaluationobjectNão{}—Aceito; nenhuma parte da execução o lê. Veja upper_bound_evaluation.
upper_bound_evaluation.enabledboolean | nullNãonull—Aceito; não tem efeito. Veja upper_bound_evaluation.
upper_bound_evaluation.initial_iterationinteger | nullNãonull—Aceito; não tem efeito. Veja upper_bound_evaluation.
upper_bound_evaluation.interval_iterationsinteger | nullNãonull—Aceito; não tem efeito. Veja upper_bound_evaluation.
upper_bound_evaluation.lipschitzobjectNão{}—Aceito; não tem efeito. Veja upper_bound_evaluation.
exportsobjectNão{}—Controla quais saídas são gravadas no diretório de resultados. Veja exports.
exports.statesbooleanNãofalse—Armazena os estados visitados de cada conjunto de cortes e os grava no checkpoint da política. Veja exports.
exports.stochasticbooleanNãofalse—Grava os artefatos do pré-processamento estocástico. Veja exports.
exports.fpha_deviation_pointsbooleanNãofalse—Grava a tabela de desvios do ajuste da FPHA calculada. Veja exports.
$schemastring | nullNãonull—URI opcional do esquema; o carregador não a lê. Veja Exemplo completo.

Controla a fase de treinamento da PDDE.

CampoTipoDescrição
selectionobjectMétodo de seleção de cenários da simulação forward do treinamento — sampled{forward_passes} ou enumerated{} (veja training.selection abaixo). Sem padrão: a ausência de training.selection é um erro de carga fatal.
stopping_rulesarrayCritérios de parada (veja abaixo). A chave é obrigatória e a lista deve conter pelo menos um critério iteration_limit; uma lista sem nenhum, inclusive [], é recusada na carga da configuração. O treinamento nunca ultrapassa o maior iteration_limit da lista.

Define quantas trajetórias a simulação forward do treinamento percorre por iteração, ou se ela percorre todos os caminhos do grafo da política (policy graph) em vez de amostrar. O objeto é discriminado internamente por method; cada variante aceita apenas seus próprios campos — combinar forward_passes com "enumerated" é um erro de carga (deny_unknown_fields).

CampoTipoObrigatórioDescrição
methodstringSimUm de "sampled", "enumerated".
forward_passesintegerapenas sampledNúmero de trajetórias de cenários por iteração (>= 1). Valores maiores reduzem a variância do corte de cada iteração, mas aumentam o custo por iteração. Rejeitado com "enumerated".

Não há padrão para o número de simulações forward: a ausência de training.selection é um erro de carga fatal (SchemaViolation).

Exemplo — amostrado:

{ "method": "sampled", "forward_passes": 50 }

Exemplo — enumerado (a simulação forward percorre todos os caminhos do grafo da política em vez de sortear uma quantidade fixa):

{ "method": "enumerated" }

Com enumerated, uma classe de scenario_source lê a abertura declarada do nó somente quando é in_sample, ou external com uma coluna de cenário que o nó fixa. Uma classe em out_of_sample ou historical, ou em external sem coluna fixada, sorteia sua própria realização; assim, os limites informados são os do grafo da política declarado somente quando toda classe lê a abertura do nó.

Com dois ou mais processos MPI, o treinamento enumerado só admite um grafo da política cujas ramificações estejam todas no último estágio (um tronco determinístico terminando em um leque terminal); um grafo com nó de ramificação intermediário interrompe novomodelo run antes do treinamento, com código de saída 1. novomodelo validate não verifica isso; portanto, uma validação aprovada não exclui essa situação. A mensagem de erro está listada em Falhas de comunicação.

A seleção enumerada, no treinamento ou na simulação, também exige que todo nó do grafo da política tenha uma única abertura: ela percorre cada caminho do grafo da política e não enumera as aberturas de um nó. Um nó que fixa um scenario_id tem uma, e seu estágio não declara num_openings; qualquer outro nó tem as aberturas que seu estágio gera, de modo que esse estágio declara num_openings: 1 em stages.json. Um caso com um nó que tenha mais é recusado na preparação do estudo, por novomodelo validate e por novomodelo run antes do treinamento, com código de saída 1.

CampoTipoPadrãoDescrição
enabledbooleantrueDefina como false para pular o treinamento e seguir diretamente para a simulação (exige uma política já treinada).
tree_seedinteger | nullnullSemente da árvore de aberturas e dos sorteios de aberturas dentro da amostra (in-sample). Quando null, usa-se a semente padrão 42 (determinística, mas arbitrária), sem aviso; um valor negativo é usado em valor absoluto. Veja Resolução das sementes para a relação com scenario_source.seed.
stopping_modestring"any"Um de "any", "all". Como vários critérios de parada se combinam: "any" para quando o primeiro critério é satisfeito; "all" para quando todos os critérios, exceto iteration_limit, são satisfeitos na mesma iteração, e o maior iteration_limit limita a execução.
cut_selectionobject{}Processo de gestão de linhas (seleção de cortes), aninhado em training.cut_selection (não é chave de raiz). Veja cut_selection.
solverobject{}Sobrescritas opcionais, por fase, do perfil do solver de PL; as duas chaves retry_* não têm efeito. Veja training.solver.
parallelismobject{}Parâmetros de escalonamento dos trabalhadores da simulação backward. Veja parallelism.
scenario_sourceobject | nullnullFonte de ruído por classe para a simulação forward do treinamento. Veja scenario_source.

Para a configuração de scenario_source por classe, veja a subseção scenario_source abaixo e Geração de cenários §3.

Controla de onde vem o ruído da simulação forward para cada classe de entidade durante o treinamento. Quando ausente, todas as classes usam por padrão in_sample (reutilizando a árvore de aberturas pré-gerada).

CampoTipoPadrãoDescrição
seedinteger | nullnullSemente forward dos sorteios fora da amostra (out-of-sample) do treinamento e dos da simulação quando simulation.scenario_source está ausente; obrigatória quando alguma classe é out_of_sample ou external. A seleção de janelas históricas e de cenários externos não usa semente. Veja Resolução das sementes.
inflowobjectin_sampleEsquema de amostragem da afluência às usinas hidrelétricas. Objeto com a chave "scheme".
loadobjectin_sampleEsquema de amostragem da carga dos barramentos. Objeto com a chave "scheme".
ncsobjectin_sampleEsquema de amostragem da disponibilidade das NCS. Objeto com a chave "scheme".
historical_yearsarray | objectdescoberta automáticaRestringe o conjunto de janelas históricas. Quando ausente, todo ano do histórico é candidato. Lista ([1940, 1953]) ou intervalo ({"from": 1940, "to": 2010}). Cada ano listado designa a janela cujo primeiro estágio do estudo cai na ocorrência, naquele ano, de seu período sazonal; a elegibilidade segue o Conjunto de janelas históricas, e um ano que não a atenda é descartado sem mensagem. Um resultado vazio gera o erro “no valid historical windows found” (Códigos de erro). O mesmo conjunto fornece as aberturas historical_residuals.
openingsobject{"source": "generated"}Origem da árvore de aberturas da simulação backward. {"source": "generated"} constrói a árvore internamente, com o moment_matching opcional de training.scenario_source.openings; {"source": "file"} lê uma árvore fornecida pelo usuário em scenarios/noise_openings.parquet (apenas com seleção amostrada, e não com policy_graph.nodes[] declarado em stages.json; qualquer dessas combinações é rejeitada na validação do caso). Apenas no treinamento. Um arquivo declarado e ausente interrompe a execução em sua fase estocástica (Arquivo da árvore de aberturas ausente).

Valores válidos para "scheme": "in_sample", "out_of_sample", "external" para todas as classes; "historical" apenas para inflow.

Regras de admissão (verificadas na carga; as mensagens estão listadas em Regras de admissão da fonte de cenários):

  • historical só é válido para inflow — load ou ncs em historical é rejeitado.
  • seed é obrigatório quando alguma classe é out_of_sample ou external.
  • historical_years é rejeitado, a menos que alguma classe use historical.
  • Um intervalo historical_years deve ter from <= to.
  • openings só é aceito em training.scenario_source; em simulation.scenario_source é rejeitado.

Para uma classe no esquema "external" no treinamento, as seguintes entidades usam a média e o desvio-padrão do arquivo externo, por entidade e estágio:

  • os barramentos de carga de uma classe de carga externa;
  • as fontes NCS de uma classe de NCS externa;
  • as usinas hidrelétricas de uma classe de afluência externa cujo modelo de afluências tenha ordem AR 0 e nenhum componente anual.

Para uma classe externa, load_seasonal_stats.parquet e non_controllable_stats.parquet são, portanto, opcionais; um arquivo de estatísticas de carga presente mantém sua própria regra de uma linha para cada barramento em cada estágio do estudo. scenarios/inflow_seasonal_stats.parquet continua exigindo, quando presente, uma linha para cada usina em operação em cada estágio do estudo, e as linhas de uma usina com ordem AR 0 em inflow_seasonal_stats.parquet não são usadas na amostragem. Uma usina com ordem AR acima de 0 ou com componente anual mantém a média, o desvio-padrão e os coeficientes declarados em seus arquivos (ou os estimados a partir de inflow_history.parquet quando os arquivos os omitem). Uma coluna externa com σ = 0 é aceita para carga, NCS e um modelo de afluências de ordem AR 0 sem componente anual, e rejeitada para um modelo de afluências cujos arquivos declarem ordem AR acima de 0 ou componente anual (veja Códigos de erro).

Exemplo — afluência fora da amostra com carga e NCS dentro da amostra:

{
"training": {
"tree_seed": 42,
"selection": { "method": "sampled", "forward_passes": 50 },
"stopping_rules": [{ "type": "iteration_limit", "limit": 200 }],
"scenario_source": {
"seed": 99,
"inflow": { "scheme": "out_of_sample" },
"load": { "scheme": "in_sample" },
"ncs": { "scheme": "in_sample" }
}
}
}

Veja Geração de cenários §3 para a descrição completa de cada esquema e das janelas históricas.

De onde vem a árvore de aberturas da simulação backward e como uma árvore gerada é corrigida (Geração de cenários §2.3). Quando openings está ausente, a árvore é gerada com moment_matching no seu valor padrão.

CampoTipoPadrãoDescrição
sourcestring"generated"Um entre "generated", "file". "generated" constrói a árvore a partir do sampling_method dos estágios; "file" a lê de scenarios/noise_openings.parquet.
moment_matchingstring"per_coordinate"Um entre "per_coordinate", "none"; aceito apenas com "source": "generated". "per_coordinate" desloca e escala as aberturas de afluência de cada estágio gerado de modo que, para cada usina hidrelétrica, sua média seja 0 e sua variância seja a que a correlação do estágio atribui ao ruído dessa usina (passo 4 de §2.3); "none" mantém as aberturas como sorteadas. Um estágio historical_residuals, um estágio com uma única abertura e os ruídos de carga e de NCS nunca passam pela correspondência de momentos (moment matching).
{
"training": {
"scenario_source": {
"openings": { "source": "generated", "moment_matching": "none" }
}
}
}

moment_matching com "source": "file", ou um valor fora dos dois, é recusado quando o config.json é carregado. A simulação forward dentro da amostra (in-sample) e o stochastic/noise_openings.parquet exportado usam a árvore com correspondência de momentos; os sorteios da simulação forward fora da amostra (out-of-sample) não passam pela correspondência de momentos. O training/model_provenance.json registra o modo de uma árvore gerada como inflow.opening_tree_moment_matching (Arquivos de metadados).

Cada entrada de stopping_rules é um objeto JSON com um discriminador "type". A condição de parada de cada critério é definida em Critérios de parada.

Para após um número fixo de iterações de treinamento.

{ "type": "iteration_limit", "limit": 200 }
CampoTipoDescrição
limitintegerNúmero máximo de iterações da PDDE a executar.

Use uma única entrada iteration_limit: em uma execução retomada, seu limit também conta as iterações das execuções anteriores (Treinar em etapas).

Para quando se esgota um orçamento de tempo de relógio.

{ "type": "time_limit", "seconds": 3600.0 }
CampoTipoDescrição
secondsnumberTempo máximo de treinamento, em segundos.

O critério compara seconds com os segundos de relógio decorridos desde o início do treinamento desta execução, verificados após cada iteração.

Para quando a melhoria relativa do limite inferior fica abaixo de um limiar (estagnação do limite, bound stalling).

{ "type": "bound_stalling", "iterations": 20, "tolerance": 0.0001 }
CampoTipoDescrição
iterationsintegerTamanho da janela: número de limites inferiores registrados mais recentes que são comparados.
tolerancenumberLimiar de melhoria relativa. O treinamento para quando a melhoria na janela é inferior a esse valor.

O critério não pode ser acionado antes que iterations limites tenham sido registrados; uma execução retomada continua a série de limites inferiores de seu checkpoint, e uma partida a quente (warm-start) começa com a série vazia. Com tolerance positivo, uma janela de 1 compara o limite com ele mesmo e é acionada na primeira iteração.

Para quando o limite superior exato se aproxima do limite inferior dentro da tolerância. Exige uma simulação forward enumerada no treinamento, para que o limite superior comparado seja exato, e não uma estimativa estatística.

{ "type": "gap", "tolerance": 1000.0, "relative_tolerance": 0.01 }
CampoTipoDescrição
tolerancenumberOpcional. Tolerância absoluta do gap, nas unidades dos limites informados.
relative_tolerancenumberOpcional. Tolerância relativa do gap em percentual — 0.01 significa 0,01%, comparada com 100 · gap / max(1, |lower_bound|).

Pelo menos um de tolerance / relative_tolerance deve estar presente; um critério gap sem nenhum dos dois campos é rejeitado na validação da configuração: novomodelo validate o informa como ConfigValidationError, e novomodelo run imprime a mesma mensagem e termina com 1. Quando ambos estão presentes, os dois ramos se combinam por disjunção — o treinamento para assim que qualquer um dos ramos é satisfeito, não necessariamente ambos. O próprio gap é max(0, upper_bound − lower_bound).

Admissibilidade — o critério gap só é aceito quando ambas as condições valem:

  • training.selection.method é "enumerated" (a simulação forward percorre todos os caminhos do grafo da política, de modo que o limite superior é exato, e não uma estimativa amostral). A seleção enumerada também exige que todo nó do grafo da política tenha uma única abertura.
  • A medida de risco é uniforme em todos os estágios: ou risk_measure: "expectation" em todos os estágios, ou a mesma medida cvar (lambda e alpha idênticos) em todos os estágios de stages.json (um cvar com lambda: 0 equivale à esperança). Sob um cvar uniforme, o limite superior exato é calculado como uma recursão de risco aninhada e consistente no tempo sobre a árvore enumerada, de modo que continua delimitando o limite inferior avesso ao risco.

Com seleção sampled, com mais de uma abertura em algum nó ou com uma medida variável por estágio (a medida de risco difere entre estágios), o critério gap é rejeitado na preparação do estudo, por novomodelo validate e por novomodelo run antes do treinamento (saída 1). A comparação com o limite exato da qual o critério depende não está disponível nesses casos.

Quando vários critérios de parada são listados, stopping_mode controla como eles se combinam:

  • "any" (padrão): para quando qualquer um dos critérios é satisfeito.
  • "all": para quando todos os critérios, exceto iteration_limit, são satisfeitos na mesma iteração; o maior iteration_limit limita a execução, e um menor não tem efeito.
{
"training": {
"selection": { "method": "sampled", "forward_passes": 50 },
"stopping_mode": "all",
"stopping_rules": [
{ "type": "iteration_limit", "limit": 500 },
{ "type": "bound_stalling", "iterations": 20, "tolerance": 0.0001 }
]
}
}

Agrupa os parâmetros de escalonamento dos trabalhadores, que preservam o resultado e determinam como o trabalho da simulação backward é distribuído entre os trabalhadores, ao lado dos campos de semântica do algoritmo na raiz de training.

backward_scheduler define como as unidades de trabalho da simulação backward são assumidas pelos trabalhadores. É discriminado por method; fornecer um campo que não pertence ao método selecionado é um erro de carga (deny_unknown_fields), e não uma chave ignorada silenciosamente.

  • "by_scenario" (padrão) — cada unidade de trabalho paralela é um estado visitado inteiro.

    { "method": "by_scenario" }
  • "by_node" — cada unidade de trabalho paralela é um par (trial point, opening block), assumido dinamicamente a partir de um contador compartilhado.

    CampoTipoPadrãoDescrição
    block_sizeinteger | nullnullAberturas por bloco. Se ausente, resolve, por estágio, para ⌈|Ω_s|/2⌉ (metade das aberturas, arredondada para cima); um valor definido é limitado silenciosamente a min(|Ω_s|, block_size) — sem erro e sem aviso.

    Duas configurações são erros de carga, e não são aceitas silenciosamente:

    • block_size fornecido com "by_scenario" — rejeitado (deny_unknown_fields).
    • block_size: 0 — rejeitado (mínimo 1).

Dentro de um estágio, os blocos de aberturas são assumidos do mais difícil para o mais fácil: os blocos são classificados pelo custo médio, em pivôs do simplex, da iteração anterior por (stage, block), em ordem decrescente (empates resolvidos pelo índice de bloco crescente; a primeira iteração, e qualquer bloco sem dados anteriores, ficam por último). Essa ordem de atribuição altera apenas qual trabalhador processa qual bloco, e quando — ela é neutra quanto ao resultado: o conjunto de cortes produzido e o limite inferior do treinamento são idênticos aos da atribuição em ordem canônica.

Exemplo — padrão (by_scenario; nenhum bloco parallelism necessário):

{
"training": {
"selection": { "method": "sampled", "forward_passes": 50 },
"stopping_rules": [{ "type": "iteration_limit", "limit": 100 }]
}
}

Exemplo — by_node com block_size explícito:

{
"training": {
"selection": { "method": "sampled", "forward_passes": 50 },
"stopping_rules": [{ "type": "iteration_limit", "limit": 100 }],
"parallelism": {
"backward_scheduler": { "method": "by_node", "block_size": 4 }
}
}
}

Para a simulação backward dentro da qual esse escalonamento ocorre, veja Algoritmo da PDDE §3.4.


Controla o processo de gestão de linhas do conjunto de linhas de cada estágio. O processo tem até duas etapas: um método de seleção e um limite, por estágio, de linhas ativas. Desativar uma linha a remove dos PLs do estágio e a mantém no conjunto. Para uma explicação detalhada de cada etapa, veja Aceleradores de desempenho e, para os próprios métodos de seleção, Gerenciamento de cortes.

O bloco tem dois parâmetros sempre ativos no nível superior, mais um subobjeto selection que escolhe o método e contém apenas os parâmetros desse método. Omitir selection (ou defini-lo como null) desabilita a seleção de linhas — esse é o padrão.

CampoTipoPadrãoDescrição
row_activity_tolerancenumber1e-6Limiar de atividade na solução para o acompanhamento: uma linha conta como ativa na solução de um ponto quando seu multiplicador dual é estritamente maior que esse valor (comparação com sinal). Os multiplicadores das linhas do conjunto de um estágio somam no máximo o fator de desconto desse estágio, de modo que o limiar é adimensional. A atividade na solução registrada é lida apenas por max_active_per_stage e pelo seed_window do método dynamic, e só é registrada, e gravada no checkpoint da política, quando um deles está configurado. Deve ser >= 0; null é erro de análise. 0 conta como ativo na solução um multiplicador no nível de arredondamento do solver.
max_active_per_stageintegernullLimite de linhas ativas que a execução atual acrescentou ao conjunto de cada estágio estritamente entre o primeiro e o último; o conjunto de cada nó é limitado separadamente. Linhas carregadas de uma política não contam nem são removidas, e as linhas da iteração corrente contam mas nunca são removidas, de modo que um conjunto pode conter mais linhas ativas que o limite. Aplicado a cada iteração, após a etapa de seleção. O excesso é removido em ordem crescente da iteração em que a linha esteve ativa na solução pela última vez, depois do número de resoluções em que esteve ativa na solução e, por fim, de sua posição no conjunto. null = sem limite. Recusado com o método dynamic e com training.selection enumerado.
selectionobjectnullO método de seleção ativo e seus parâmetros (veja abaixo). null (o padrão) desabilita a seleção de linhas.

Um limite inferior a training.selection.forward_passes é aceito com um aviso: um conjunto que recebe essa quantidade de linhas por iteração passa então a remover, a cada iteração, todas as linhas que a execução acrescentou em uma iteração anterior.

selection.method é o discriminador; cada método expõe apenas seus próprios parâmetros. Fornecer um parâmetro que pertence a outro método é um erro de carga da configuração, um método com erro de digitação é rejeitado com a lista dos métodos válidos, e um selection fornecido como array é erro de análise. Um parâmetro de contagem definido como 0 é erro de análise que indica o caminho da chave, por exemplo training.cut_selection.selection.check_frequency must be >= 1 (got 0).

  • "level1" — seleção de cortes Nível 1 (Level-1) sobre o conjunto de cada estágio estritamente entre o primeiro e o último. Cada um desses conjuntos armazena o estado visitado de cada linha que a execução acrescenta. Em cada estado armazenado, a linha de maior valor é a detentora do estado, dentre as linhas pontuadas do conjunto, ativas ou não, e as demais linhas carregadas que estejam ativas; entre linhas com valores exatamente iguais, a que estiver na menor posição do conjunto é a detentora. A cada check_frequency iterações, uma linha pontuada é desativada quando não é detentora de nenhum estado armazenado e reativada quando está inativa e é detentora de algum. Os valores são comparados exatamente, e uma linha da iteração corrente é julgada como qualquer outra. Uma linha carregada é pontuada quando a política a registra assim (a execução que a gravou armazenou seu estado visitado, com level1 ou exports.states); uma linha carregada que não é pontuada mantém a atividade com que foi carregada.

    CampoTipoPadrãoDescrição
    check_frequencyinteger5Iterações entre etapas de seleção. Deve ser >= 1.
    lookback_iterationsintegernullIterações da execução atual cujas linhas mantêm seus estados visitados. null mantém todos os estados, e a memória cresce com o número de linhas. Um valor w descarta os estados das linhas mais antigas que as últimas w iterações, nunca uma linha: uma linha cujo estado foi descartado permanece no conjunto e concorre nos estados que restam. Um estado carregado com warm_start conta como anterior à primeira iteração da execução. A memória por conjunto fica então limitada a (lookback_iterations + check_frequency) vezes o máximo de linhas que a execução pode acrescentar a esse conjunto em uma iteração, vezes a dimensão do estado, vezes 8 bytes, mais os estados carregados. Deve ser >= 1 e >= check_frequency.
  • "dynamic" — um laço preguiçoso por resolução, a geração preguiçosa de linhas própria do Novo Modelo. A partir de start_iteration, cada resolução do treinamento começa com as linhas iniciais, acrescenta as linhas candidatas violadas por sua solução, no máximo max_added_per_round por rodada, e resolve novamente; retorna quando nenhuma candidata é violada. Após um número fixo de rodadas, o limite por rodada é removido. Uma resolução da simulação começa com todas as linhas ativas, de modo que seed_window e candidate_recency se aplicam apenas ao treinamento. O método nunca desativa uma linha. Ele é recusado com training.selection enumerado na preparação do estudo, por novomodelo validate e por novomodelo run (saída 1).

    CampoTipoPadrãoDescrição
    start_iterationinteger2Primeira iteração (contada a partir de 1) em que o laço preguiçoso se torna ativo. Deve ser >= 1.
    seed_windowinteger5Uma resolução começa com as linhas ativas cuja última atividade na solução ocorreu há no máximo seed_window iterações (uma linha que nunca esteve ativa na solução conta a partir da iteração que a acrescentou), mais as linhas da iteração corrente. 0 inicia com as linhas da iteração corrente e as que estiveram ativas na solução nela. Uma linha carregada com warm_start, ou de policy.boundary, conta a partir do início da execução.
    candidate_recencyintegernullnull: toda linha ativa é candidata e uma resolução retorna o ótimo sobre elas. Um valor n (deve ser >= 1) restringe as candidatas às linhas acrescentadas nas últimas n iterações e às linhas carregadas; o resultado é então o ótimo sobre essas linhas juntamente com as linhas iniciais. Com resume, uma linha recarregada só é linha carregada quando a execução que gravou o checkpoint a carregou.
    max_added_per_roundinteger10Máximo de linhas acrescentadas por rodada de resolução preguiçosa. Deve ser >= 1.
    violation_tolerancenumbernullUm fator relativo: uma linha candidata é acrescentada quando seu valor excede o valor de custo futuro em mais que o fator vezes a maior das duas magnitudes. null: cada fase usa a tolerância de viabilidade primal de seu perfil de solver. Um valor deve ser finito, > 0, < 1 e pelo menos igual à tolerância de viabilidade primal do perfil de solver de cada fase.

Os dois métodos são mutuamente exclusivos por construção: o bloco discriminado selection nomeia um só. Uma execução que define dynamic e simula com o padrão simulation.cut_set "all" é recusada na carga quando a política que carrega, ou as linhas de policy.boundary, contêm uma linha que "all" inclui e que não está ativa.

Exemplo com o método dinâmico:

{
"training": {
"cut_selection": {
"row_activity_tolerance": 1e-6,
"selection": {
"method": "dynamic",
"start_iteration": 2,
"seed_window": 5,
"max_added_per_round": 10
}
}
}
}

Exemplo com o método level1 e limite por estágio:

{
"training": {
"cut_selection": {
"row_activity_tolerance": 1e-6,
"max_active_per_stage": 500,
"selection": {
"method": "level1",
"check_frequency": 5,
"lookback_iterations": 20
}
}
}
}

Para o tratamento desses mesmos perfis do ponto de vista de ajuste de desempenho, veja Perfis de solver por fase.

As duas chaves retry_* não têm efeito (Chaves inertes); backward e forward são sobrescritas opcionais, por fase, do perfil do solver de PL.

CampoTipoPadrãoDescrição
retry_max_attemptsinteger5Número máximo de novas tentativas do solver antes de propagar um erro fatal. Sem efeito; veja Chaves inertes.
retry_time_budget_secondsnumber30.0Orçamento total de tempo, em segundos, para todas as novas tentativas de uma resolução. Sem efeito; veja Chaves inertes.
backwardobject | nullnullSobrescrita do perfil do solver de PL aplicada durante a simulação backward.
forwardobject | nullnullSobrescrita do perfil do solver de PL aplicada durante a simulação forward.

simulation.solver (veja simulation abaixo) é um terceiro irmão, independente, com o mesmo formato — training.solver.backward, training.solver.forward e simulation.solver resolvem-se todos a partir de um mesmo conjunto de campos de perfil do solver, documentado uma única vez abaixo.

Todo campo é opcional e tem padrão null. Um campo ausente mantém a opção correspondente no perfil ajustado embutido da fase — e não no perfil padrão do próprio solver subjacente; os dois diferem (por exemplo, os três perfis de fase definem price como "row_hyper_sparse", enquanto o padrão de pricing do próprio HiGHS é "row"). A resolução ocorre uma única vez na preparação — antes que qualquer modelo de PL seja montado — e todo processo resolve o mesmo perfil a partir da configuração difundida.

CampoTipo / valores
dual_edge_weight"devex" | "steepest_edge" | "dantzig"
scale"off" | "solver_scaling"
price"row" | "row_hyper_sparse"
presolve"on" | "off" | "choose"
primal_feasibility_tolerancenumber
dual_feasibility_tolerancenumber
simplex_update_limitinteger
cost_perturbationnumber
factor_pivot_thresholdnumber
use_warm_startboolean
steepest_edge_devex_fallback_thresholdnumber
  • presolve só afeta uma resolução realmente a frio — uma resolução com aproveitamento de base pula o presolve independentemente da configuração.
  • use_warm_start define se as resoluções do HiGHS de uma fase partem da base armazenada. Os perfis embutidos o definem como true para training.solver.forward e training.solver.backward, e como false para simulation.solver. Com false, o HiGHS ignora a base armazenada e resolve a frio, com presolve (ligado em todos os perfis embutidos). Defina "use_warm_start": true em simulation.solver para usar aproveitamento de base na simulação; em um PL grande, uma simulação com aproveitamento de base pode ser mais lenta que uma a frio, porque uma resolução com aproveitamento de base pula o presolve. Uma resolução a frio pode parar em um vértice diferente, igualmente ótimo, do de uma resolução com aproveitamento de base: o mesmo valor objetivo, possivelmente com duais diferentes. A escalada de novas tentativas do HiGHS mantém o use_warm_start da fase em todos os níveis de nova tentativa. O backend CLP não tem essa configuração: toda fase parte da base armazenada quando ela existe. A forma como o armazenamento de bases alimenta cada fase está nas notas de implementação do Aproveitamento de base do PL.
  • dual_edge_weight: "steepest_edge" é uma solicitação, não uma garantia — o HiGHS recai silenciosamente no pricing Devex quando o erro logarítmico do peso dual steepest-edge excede steepest_edge_devex_fallback_threshold.

Seis campos têm sua faixa verificada; um valor fora da faixa é rejeitado na preparação do estudo, por novomodelo validate e por novomodelo run (saída 1), com um erro que indica a fase e o campo problemático:

  • primal_feasibility_tolerance — deve ser finito.
  • dual_feasibility_tolerance — deve ser finito e >= 1e-10.
  • simplex_update_limit — deve ser <= 2147483647 (i32::MAX).
  • cost_perturbation — deve ser finito e >= 0.
  • factor_pivot_threshold — deve estar em [8e-4, 0.5].
  • steepest_edge_devex_fallback_threshold — deve ser finito e >= 1.0.

Os enums fechados (dual_edge_weight, scale, price, presolve) e use_warm_start são incondicionalmente válidos — todas as variantes são suportadas.

As sobrescritas de perfil de solver por fase são exclusivas do HiGHS. No backend CLP, qualquer campo definido em backward, forward ou simulation.solver é rejeitado na preparação — de forma determinística, em todo processo, antes que qualquer modelo de PL seja montado — com um erro nomeado que identifica a fase e o campo. Um bloco de sobrescrita vazio (por exemplo "solver": {} ou "backward": {}) e um bloco ausente são ambos válidos no CLP; apenas um campo efetivamente definido provoca a rejeição. O CLP inicia as resoluções de todas as fases a partir de uma base armazenada quando há uma disponível. Veja Instalação — Escolha do backend para a seleção do backend e as demais limitações do CLP.

Exemplo — training.solver.backward com duas sobrescritas:

{
"training": {
"solver": {
"retry_max_attempts": 5,
"retry_time_budget_seconds": 30.0,
"backward": {
"dual_edge_weight": "steepest_edge",
"factor_pivot_threshold": 0.05
}
}
}
}

Controla a fase opcional de simulação pós-treinamento.

CampoTipoPadrãoDescrição
enabledbooleanfalseHabilita a fase de simulação após o treinamento.
selectionobject | nullnullMétodo de seleção de cenários da fase de simulação — sampled{num_scenarios} ou enumerated{} (veja simulation.selection abaixo). Se ausente, resolve para uma contagem amostrada de 2000.
io_channel_capacityinteger64Capacidade da fila entre os trabalhadores da simulação e o gravador de saída; 0 se comporta como 1.
solverobject | nullnullPerfil do solver da fase de simulação, com os mesmos campos de um perfil de fase de training.solver (veja training.solver). Se ausente, mantém o perfil embutido da fase.
scenario_sourceobject | nullnullFonte de cenários da fase de simulação; se ausente, reutiliza training.scenario_source (veja simulation.scenario_source).
cut_setstring"all"Um de "all", "active". Quais linhas do conjunto de linhas de cada estágio a simulação carrega no PL do estágio (veja Conjunto de cortes da simulação abaixo).

"all" carrega todas as linhas que uma execução de treinamento acrescentou ao conjunto, inclusive as linhas que o método de seleção desativou e as que max_active_per_stage removeu, de modo que um PL da simulação pode ser maior que os PLs do treinamento. "active" carrega apenas as linhas ativas ao fim do treinamento.

Uma execução com o treinamento desabilitado carrega cada linha da política com o papel que ela tinha na execução que a gravou, de modo que "all" carrega o que o "all" daquela execução continha e "active", as linhas ativas quando ela terminou; um resume faz o mesmo. Com warm_start e para as linhas de policy.boundary, "all" carrega uma linha que a política registra como pontuada (a execução que a gravou armazenou o estado visitado da linha, com exports.states ou level1), qualquer que seja sua marcação de ativa, e qualquer outra linha carregada somente quando essa marcação está definida. A marcação exportada is_active registra a última seleção.

Uma execução com o método dynamic que simula com "all" é recusada na carga quando conteria uma linha que "all" inclui e que não está ativa, na política que carrega com warm_start ou resume ou com o treinamento desabilitado, ou nas linhas de policy.boundary; defina "active" ou use o método level1.

Define quantas trajetórias a simulação pós-treinamento executa, ou se ela percorre todos os caminhos do grafo da política em vez de amostrar. É discriminado internamente por method, espelhando training.selection acima. Ao contrário de training.selection, este campo é opcional: a ausência de simulation.selection resolve para uma contagem amostrada de 2000.

CampoTipoObrigatórioDescrição
methodstringSim (se presente)Um de "sampled", "enumerated".
num_scenariosintegerapenas sampledNúmero de cenários independentes de simulação Monte Carlo a avaliar. Rejeitado com "enumerated".

Quando simulation.enabled é false, ou a contagem amostrada num_scenarios resolve para 0, a fase de simulação é inteiramente pulada.

Com enumerated, as classes leem a abertura do nó como em training.selection: uma classe que não a lê sorteia sua própria realização. A exigência de abertura única de training.selection também se aplica aqui. Quando exatamente um entre treinamento e simulação é enumerated, novomodelo run registra um aviso na preparação indicando a estatística que falta à outra fase: com treinamento enumerado e simulação amostrada, o limite inferior exato está disponível, mas as estatísticas ponderadas da simulação censitária (census simulation) não. O aviso é apenas informativo e a execução prossegue; defina ambas as seleções como enumerated para uma simulação censitária.

Exemplo:

{
"simulation": {
"enabled": true,
"selection": { "method": "sampled", "num_scenarios": 1000 }
}
}

Controla de onde vem o ruído da simulação forward durante a fase de simulação. Quando ausente, a simulação recai no esquema configurado em training.scenario_source. Isso permite treinar com ruído dentro da amostra e simular com outro esquema (por exemplo, fora da amostra ou histórico) sem alterar os esquemas do treinamento. Para saber qual semente cada sorteio usa, e a regra de admissão da semente da simulação, veja Resolução das sementes.

Os campos são os de training.scenario_source, exceto openings, que é exclusivo do treinamento. Quando simulation.scenario_source está presente, ele substitui integralmente a fonte do treinamento — uma classe que ele omite recebe o padrão in_sample, e não o valor do treinamento:

CampoTipoPadrãoDescrição
seedinteger | nullnullSemente forward dos sorteios fora da amostra da simulação; obrigatória quando uma classe de simulation.scenario_source é out_of_sample ou external. Veja Resolução das sementes.
inflowobjectin_sampleEsquema de amostragem da afluência às usinas hidrelétricas. Objeto com a chave "scheme".
loadobjectin_sampleEsquema de amostragem da carga dos barramentos. Objeto com a chave "scheme".
ncsobjectin_sampleEsquema de amostragem da disponibilidade das NCS. Objeto com a chave "scheme".
historical_yearsarray | objectdescoberta automáticaRestringe o conjunto de janelas históricas. Lista ([1940, 1953]) ou intervalo ({"from": 1940, "to": 2010}); cada ano listado é interpretado como em training.scenario_source. Só tem efeito quando o esquema de afluência do treinamento não é historical: quando o treinamento também é historical, a simulação reproduz o conjunto do treinamento e esta chave não tem efeito.

Os valores de esquema e as regras de admissão são os de training.scenario_source; openings é rejeitado aqui.

Uma configuração completa de exemplo está em Simulação fora da amostra.


Três sementes em config.json conduzem os sorteios aleatórios: training.tree_seed, training.scenario_source.seed e simulation.scenario_source.seed. A seleção, na simulação forward, de janelas históricas e de cenários externos não usa semente.

  • training.tree_seed é a semente da árvore de aberturas e dos sorteios de aberturas dentro da amostra. Quando é um inteiro não nulo, o Novo Modelo usa |seed| (valor absoluto sem sinal) como semente-base para a geração determinística de ruído com SipHash-1-3, de modo que uma semente negativa -n atua como n. Quando ausente ou null, a semente é 42 e nenhum aviso é impresso. Defina-a explicitamente para tornar a escolha intencional e visível aos demais usuários do diretório do caso.
  • training.scenario_source.seed é a semente forward dos sorteios fora da amostra. O Novo Modelo aplica a mesma regra do valor absoluto: usa |seed|. A afluência sorteia diretamente a partir dela; carga e NCS derivam, cada uma, seu próprio fluxo a partir dela, de modo que as três classes sorteiam ruídos independentes. Ela é obrigatória sempre que alguma classe é out_of_sample ou external.
  • Os sorteios dentro da amostra da simulação usam training.tree_seed, e seus sorteios fora da amostra usam simulation.scenario_source.seed, ou training.scenario_source.seed quando simulation.scenario_source está ausente; simulation.scenario_source.seed é obrigatória quando uma classe de simulation.scenario_source é out_of_sample ou external.
  • A janela de uma trajetória historical e o cenário de uma trajetória external são escolhidos por um hash determinístico dos índices de iteração e de trajetória que não usa semente.
  • A janela que cada abertura historical_residuals lê faz parte da árvore de aberturas e segue training.tree_seed.

Com as mesmas sementes e entradas, os sorteios são idênticos entre execuções.


Controla opções de modelagem física.

CampoTipoPadrãoDescrição
inflow_non_negativityobject{}Estratégia de tratamento de sorteios negativos de afluência do modelo PAR.
cost_scale_factornumber | null1000000.0Divisor de todo coeficiente da função objetivo que não seja de θ (condicionamento da função objetivo; não altera o modelo, ao contrário dos demais campos desta seção). Veja abaixo.
CampoTipoPadrãoDescrição
methodstring"truncation_with_penalty"Um de "none", "penalty", "truncation" ou "truncation_with_penalty".

Em todos os métodos, a vazão incremental de uma usina mantém o valor dado pelo modelo de afluências, que pode ser negativo, e as defasagens de afluência dos estágios posteriores são construídas a partir desse valor (agregado sobre o período da defasagem quando o período abrange vários estágios). Os métodos diferem na água que uma coluna de folga pode acrescentar a ela no balanço hídrico da usina:

  • "none" — sem folga; uma afluência negativa pode tornar um estágio inviável.
  • "penalty" — qualquer quantidade não negativa, precificada pelo inflow_nonnegativity_cost da usina vezes as horas do estágio; o padrão do estudo para esse custo é penalties.json::hydro.inflow_nonnegativity_cost (padrão 1000.0).
  • "truncation" — exatamente max(-inflow, 0), sem custo, de modo que o balanço hídrico recebe max(inflow, 0). A quantidade é calculada em cada resolução a partir das defasagens de afluência daquela resolução.
  • "truncation_with_penalty" — qualquer quantidade de 0 a max(-inflow, 0), precificada como em "penalty".

Com "truncation" e "truncation_with_penalty", o limite inferior pode exceder o limite superior, e um critério de parada gap (admitido apenas com seleção forward enumerada) pode então indicar uma convergência que não ocorreu.

A saída da simulação informa a vazão incremental como incremental_inflow_m3s e a folga como inflow_nonnegativity_slack_m3s (simulation/hydros/). Os quatro métodos são definidos em Métodos de tratamento de afluências negativas.

Exemplo — a folga "penalty" sem limite superior no lugar do padrão:

{
"modeling": {
"inflow_non_negativity": {
"method": "penalty"
}
}
}

Divisor aplicado a todo coeficiente da função objetivo que não seja de θ na montagem do modelo de PL; toda saída no domínio de custos (valor objetivo, duais, coeficientes dos cortes) é multiplicada de volta pelo mesmo fator em toda fronteira de informação de resultados. Trata-se de condicionamento da função objetivo, e não de uma escolha de modelagem física — ao contrário de inflow_non_negativity acima, os resultados são idênticos em aritmética exata; alterá-lo nunca altera o modelo.

O padrão é 1000000.0 quando ausente ou null. Deve ser finito e > 0; um valor fora de [1.0, 1e12] é aceito, mas registra um aviso informativo — não é rejeitado.

Exemplo:

{
"modeling": {
"cost_scale_factor": 1000000.0
}
}

Para a metodologia, veja Estrutura e escalonamento do PL §2.1.


Controla o processo de estimação do modelo PAR(p) do Modelo de afluências PAR(p). Quando o caso fornece inflow_history.parquet, o Novo Modelo pode estimar automaticamente os coeficientes AR, em vez de exigir um inflow_ar_coefficients.parquet pré-calculado.

CampoTipoPadrãoDescrição
max_orderinteger6Ordem máxima de defasagem considerada no ajuste do modelo autorregressivo.
order_selectionstring"pacf"Um de "pacf", "pacf_annual". Critério de seleção de ordem: baseado na FACP (PACF) ou na FACP com componente anual.
min_observations_per_seasoninteger30Número mínimo recomendado de ocorrências totalmente cobertas de cada período sazonal, por usina: as amostras a partir das quais a estimação faz o ajuste. Uma ocorrência é um intervalo do período sazonal em season_definitions, dentro ou fora do horizonte do estudo; ela só conta quando as linhas de inflow_history.parquet a cobrem integralmente e, com history_years definido, apenas quando ela começa em um desses anos. Quando a estimação é executada, um grupo (usina, período sazonal) com pelo menos uma ocorrência desse tipo, mas menos do que esse valor, gera um aviso ModelQuality que indica a usina e o período sazonal, e a estimação prossegue.
max_coefficient_magnitudenumber | nullnullRede de segurança: reduz à ordem 0 se algum coeficiente exceder essa magnitude.
correlation_targetstring"inflows"Um entre "inflows", "residuals". Série a partir da qual a correlação espacial das afluências é estimada quando o modelo de afluências é ajustado, total ou parcialmente, a partir de inflow_history.parquet e o caso não fornece scenarios/correlation.json: as afluências padronizadas ("inflows") ou os resíduos da autorregressão ajustada ("residuals"); veja Modelo de afluências PAR(p) §6.1. O training/model_provenance.json a registra como inflow.correlation_target.
history_yearsobject | nullnullIntervalo inclusivo {"from": 1931, "to": 2024} dos anos de inflow_history.parquet que a estimação lê: uma amostra é lida quando a ocorrência do período sazonal a que ela pertence começa em um ano do intervalo. O intervalo limita as estatísticas sazonais, os coeficientes autorregressivos, a componente anual e a correlação estimada; ele não restringe nenhum outro leitor do arquivo: a tendência hidrológica derivada, as janelas do esquema historical (que historical_years restringe) e as aberturas historical_residuals. null lê todos os anos. from posterior a to é recusado quando config.json é carregado, e, quando a execução estima a partir de inflow_history.parquet, o mesmo ocorre com um intervalo que comece antes do primeiro ou termine depois do último ano do arquivo (Anos do histórico de estimação fora do histórico).

Exemplo:

{
"estimation": {
"max_order": 6,
"order_selection": "pacf",
"min_observations_per_season": 30
}
}

Definir "order_selection": "pacf_annual" ativa a extensão com componente anual. Quando habilitado, o processo de estimação executa quatro etapas adicionais além do caminho PAR clássico: (1) o sistema de Yule-Walker é estendido para incluir um termo de correlação cruzada entre a afluência do período sazonal corrente e a média móvel de 12 meses; (2) as estatísticas amostrais por período sazonal (média e desvio-padrão) dessa média móvel são calculadas para cada usina hidrelétrica; (3) o coeficiente, a média e o desvio-padrão são gravados em inflow_annual_component.parquet em output/stochastic/ quando exports.stochastic é true; e (4) o passo de defasagem usado na montagem das colunas de ruído do PL é ampliado para acomodar o termo anual adicional. Use esta opção quando sua série de afluências apresentar persistência que vá além da janela de defasagens sazonal padrão.


Controla a persistência da política (gravação de checkpoints e carga para partida a quente).

CampoTipoPadrãoDescrição
pathstring"./policy"Diretório da política, resolvido em relação ao diretório de saída da execução (<case>/output por padrão); o treinamento grava o checkpoint nele, e a partida a quente, a retomada e a execução somente de simulação o leem. Um caminho vazio, ., .. ou um caminho sem componente nomeado é recusado na carga da configuração; após a resolução, e seguindo o destino de um link simbólico, é recusado um caminho que seja o diretório de saída ou um de seus ancestrais, que designe ou contenha um diretório cujos arquivos uma execução substitui (como simulation/solver ou training/solver), ou que esteja dentro de um diretório que uma execução remove por inteiro (como simulation/costs). Este diretório contém apenas checkpoints completos: uma execução cujo treinamento termina com erro grava sua política no diretório irmão <path>.partial, substituindo o que já houver ali, e deixa este diretório como o último checkpoint completo o deixou. Uma execução só lê o diretório irmão quando policy.path o designa, e um resume dele é recusado. Os arquivos do checkpoint estão listados em Checkpoint da política.
modestring"fresh"Um de "fresh", "warm_start", "resume". Modo de inicialização. "fresh" começa do zero; "warm_start" carrega cortes de uma execução anterior; "resume" continua uma execução interrompida como ela teria continuado, restaurando a numeração das iterações, o papel de cada linha, seu histórico de atividade na solução e o estado visitado armazenado, e a base de PL de cada cenário. Um resume é recusado quando o checkpoint não permite continuar a execução de forma idêntica (Retomada); um warm_start não é recusado por esses motivos.
boundaryobject | nullnullConfiguração dos cortes de fronteira terminal para acoplamento com a FCF de um modelo externo. Veja abaixo.

enabled, initial_iteration e interval_iterations programam checkpoints periódicos (Gerenciamento da política — Configuração de checkpoints); store_basis e compress não têm efeito (Chaves inertes).

CampoTipoPadrãoDescrição
enabledboolean | nullnulltrue liga os checkpoints periódicos; null ou false os mantém desligados.
initial_iterationinteger | nullnullPrimeira iteração em que um checkpoint é gravado, em números absolutos de iteração; null significa interval_iterations.
interval_iterationsinteger | nullnullIterações entre checkpoints; obrigatório e pelo menos 1 quando enabled é true.
store_basisboolean | nullnullReservado e não lido: um checkpoint contém as bases de PL dos cenários da execução, qualquer que seja seu valor. Veja Chaves inertes.
compressboolean | nullnullReservado e não lido: os arquivos de checkpoint são gravados sem compressão, qualquer que seja seu valor. Veja Chaves inertes.

Configuração opcional para carregar cortes de fronteira do estágio terminal a partir de outro checkpoint de política do Novo Modelo. Quando presente, o solver carrega cortes do checkpoint de origem e os injeta como condições de contorno fixas no estágio terminal do estudo atual. Os cortes importados não são atualizados pelo treinamento — permanecem fixos durante toda a execução.

Isso permite o acoplamento de modelos Novo Modelo com Novo Modelo: um estudo de origem produz um checkpoint de política, e um estudo encadeado importa um conjunto de cortes desse checkpoint como sua função terminal fixa (Fronteira pós-estudo e estudos encadeados §5).

O conjunto de origem é selecionado automaticamente pela data da fronteira terminal do estudo atual (o end_date do último estágio não negativo) — não há parâmetro de índice de estágio. strict rege uma origem que precifica mais do que este estudo modela.

CampoTipoPadrãoDescrição
pathstring—Caminho do diretório do checkpoint de origem, resolvido em relação a este diretório do caso (um caminho absoluto é usado como está), de modo que o checkpoint de um estudo vizinho é ../<study>/output/policy.
strictbooleanfalseRejeita a carga quando a origem precifica uma entidade ou um compromisso que este estudo não modela. false descarta o excedente (registrado no relatório de reconciliação) e carrega.

Exemplo — carregar a política de um estudo de origem como fronteira terminal:

{
"policy": {
"mode": "fresh",
"boundary": {
"path": "../upstream_study/output/policy",
"strict": false
}
}
}

Executar novomodelo validate --json em um caso que configura uma fronteira e treina emite a data selecionada e o relatório de reconciliação por família como um único objeto — o formato de sucesso contém configured, boundary_date e report. A fronteira só é reconciliada quando a execução treina, de modo que um caso com o treinamento desabilitado informa configured: false:

{
"configured": true,
"boundary_date": "2027-12-01",
"report": {
"reconciled": true,
"storage": { "copy": 44, "fan_out": 0, "straddling": 0, "filled_from_storage": 0, "default_zero": 0, "dropped_source": 0 },
"inflow_lag": { "copy": 44, "fan_out": 0, "straddling": 0, "filled_from_storage": 0, "default_zero": 0, "dropped_source": 0 },
"transit_bucket": { "copy": 6, "fan_out": 0, "straddling": 0, "filled_from_storage": 0, "default_zero": 0, "dropped_source": 0 },
"anticipated": { "copy": 3, "fan_out": 0, "straddling": 0, "filled_from_storage": 0, "default_zero": 0, "dropped_source": 1 },
"anticipated_coverage": { "source_interval_count": 4 },
"other_identity": { "copy": 0, "fan_out": 0, "straddling": 0, "filled_from_storage": 0, "default_zero": 0, "dropped_source": 0 },
"dropped_source_slots": [
{ "family": "anticipated", "entity_id": 17, "subindex": 0, "interval": ["2028-01-01", "2028-02-01"], "reference_date": null }
],
"straddling_slots": [],
"filled_from_storage_slots": []
}
}

Aqui, uma posição de compromisso antecipado que a origem precificou (usina 17, com entrega em janeiro de 2028) não é modelada por este estudo; por isso, é descartada e contabilizada em anticipated.dropped_source; com strict: true, esse mesmo descarte faria a carga ser rejeitada.

Veja Gerenciamento da política — Cortes de fronteira para uma explicação completa do fluxo de acoplamento, e Requisitos de compatibilidade para as rejeições por seleção de data e por subconjunto.


O carregador aceita o bloco e verifica suas chaves e os tipos de valor; nenhuma parte da execução o lê, de modo que seus campos não têm efeito (Chaves inertes).

NomeTipoObrigatórioPadrãoUnidadesDescrição
upper_bound_evaluation.enabledboolean | nullNãonull—Aceito; não tem efeito. Marcação de habilitação.
upper_bound_evaluation.initial_iterationinteger | nullNãonull—Aceito; não tem efeito. Iteração inicial.
upper_bound_evaluation.interval_iterationsinteger | nullNãonull—Aceito; não tem efeito. Intervalo, em iterações.
upper_bound_evaluation.lipschitz.modestring | nullNãonull—Aceito; não tem efeito. Modo de Lipschitz; qualquer string é aceita.
upper_bound_evaluation.lipschitz.fallback_valuenumber | nullNãonull—Aceito; não tem efeito. Valor alternativo de Lipschitz.
upper_bound_evaluation.lipschitz.scale_factornumber | nullNãonull—Aceito; não tem efeito. Fator de escala de Lipschitz.

Nenhuma chave de config.json define a resolução temporal: a resolução de cada estágio vem de suas datas e do season_id em stages.json. Estudos com múltiplas resoluções explica como estágios de durações diferentes compartilham ruído, agregam o histórico e mudam a resolução das defasagens; Fronteira pós-estudo e estudos encadeados acopla dois estudos, e Variantes de formulação dos patamares fornece despacho semanal dentro de um estágio mensal por meio de patamares cronológicos.

  • Estágios compartilham um grupo de ruído quando têm o mesmo season_id e suas datas de início caem no mesmo ano civil. A árvore de aberturas copia as aberturas de um grupo apenas entre estágios adjacentes do grupo; uma classe forward out_of_sample atribui a todos os estágios do grupo o mesmo sorteio, adjacentes ou não. Um estágio posterior do grupo pode ter menos aberturas que o primeiro estágio do grupo e, nesse caso, copia as primeiras delas; um com mais aberturas é recusado (Número de aberturas do grupo de ruído).
  • Quando os estágios passam de mensais para trimestrais, a reconstrução das defasagens toma o mês de cada estágio mensal a partir do month_start de seu período sazonal e calcula a média dos valores mensais por trimestre civil (janeiro-março, abril-junho, julho-setembro, outubro-dezembro), quaisquer que sejam os meses declarados pelos períodos sazonais trimestrais. A reconstrução ocorre no primeiro estágio cujo período sazonal abrange um trimestre civil logo após um estágio cujo período sazonal abrange um mês civil, conforme as abrangências declaradas pelos períodos sazonais: esse estágio lê as defasagens mensais, e as defasagens trimestrais promediadas são lidas pela primeira vez pelo estágio seguinte.
  • Com um mapa de períodos sazonais personalizado cujos períodos sazonais se sobrepõem (períodos sazonais mensais e trimestrais cobrindo os mesmos meses), uma observação datada dentro de um estágio de stages.json (um estágio do estudo, ou um estágio pré-estudo com season_id) vai para o período sazonal desse estágio, e uma datada fora de todos esses estágios vai para o período sazonal de menor id que cubra sua data; um período sazonal que nunca tem o menor id recebe, portanto, observações apenas de dentro dos estágios de stages.json desse período sazonal.
  • Um corte nos componentes de defasagem de afluência lê as defasagens de afluência de saída do estágio (Estudos com múltiplas resoluções §2.1). Em um estágio que não fecha seu período de defasagem, como um estágio semanal dentro de um mês, essas são as defasagens de entrada. Em um estágio que fecha um período iniciado em um estágio anterior ou antes do estudo, a defasagem 1 é a média do período ponderada pela duração, incluída a afluência do próprio estágio, e cada defasagem posterior ℓ é a defasagem de entrada ℓ − 1. No estágio que executa a reconstrução mensal-para-trimestral, as defasagens de saída são as defasagens trimestrais promediadas, mas o corte associa a defasagem 1 à afluência do próprio estágio e cada defasagem posterior ℓ à defasagem de entrada ℓ − 1, como em um estágio de resolução única, e a preparação do estudo registra um aviso: stage <stage_id>: the inflow lags step from months to quarters here; cuts at this stage evaluate inflow lags as at a single-resolution stage.
  • Com esses estágios e uma ordem PAR de 1 ou mais, os cortes são exatos apenas onde a afluência parcial de todo período de defasagem aberto é a mesma em todos os caminhos, como quando o único período dividido entre estágios começa antes do estudo e se fecha no seu primeiro estágio. Nos demais casos, não há garantia de que o limite inferior permaneça abaixo do limite superior, mesmo com as defasagens de afluência na projeção do corte (stages[].state_variables), e nenhum aviso sinaliza esse estudo.
  • Cada trajetória da simulação forward amostrada acumula seus próprios períodos de defasagem, de modo que os resultados do treinamento não dependem de --threads nem do número de processos MPI.

Controla quais saídas são gravadas no diretório de resultados.

CampoTipoPadrãoDescrição
statesbooleanfalseArmazena o estado visitado de cada linha que a execução acrescenta, em qualquer método de seleção, e grava os estados armazenados no checkpoint da política (policy/states/<pool>.bin). Cada conjunto que recebe linhas armazena os estados de suas próprias linhas: o conjunto do primeiro estágio mantém todos os estados, e o conjunto de cada estágio estritamente entre o primeiro e o último mantém, com level1 e lookback_iterations, apenas os estados dentro da janela. Uma execução level1 armazena e grava os estados dos conjuntos que seleciona, esteja esta opção definida ou não. Armazenar os estados não altera nenhum resultado; a política passa então a marcar suas linhas como pontuadas, e uma execução level1 posterior que a carregue as seleciona como suas próprias linhas.
stochasticbooleanfalseExporta os artefatos do pré-processamento estocástico para output/stochastic/.
fpha_deviation_pointsbooleanfalseExporta a tabela de desvios do ajuste da FPHA calculada, por ponto da grade, para output/hydro_models/fpha_deviation_points.parquet. É opcional porque emite uma linha por ponto amostral (usina, estágio, V, Q) com vertimento = 0.

Estas chaves são aceitas na carga de config.json — seus nomes e tipos de valor são verificados — e nenhuma parte de uma execução as lê; portanto, defini-las não altera nada.

NomePadrãoO que a execução faz em vez disso
policy.checkpointing.store_basisnullUm checkpoint contém as bases de PL dos cenários da execução.
policy.checkpointing.compressnullOs arquivos de checkpoint são gravados sem compressão.
training.solver.retry_max_attempts5Uma resolução que não atinge a otimalidade escala pela sequência de novas tentativas embutida no solver, e não por esta configuração (Salvaguardas do solver).
training.solver.retry_time_budget_seconds30.0Uma resolução que não atinge a otimalidade escala pela sequência de novas tentativas embutida no solver, e não por esta configuração (Salvaguardas do solver).
upper_bound_evaluation{}Nada lê o bloco: todas as suas chaves, inclusive as chaves lipschitz, não têm efeito.

Cada receita é um trecho de config.json que se mescla a um caso: uma chave do trecho substitui a mesma chave no caso, inclusive um array. As regras por trás de suas chaves estão nas seções indicadas.

Treine com simulação forward enumerada e pare quando o gap exato se fechar. relative_tolerance é um percentual: 0.01 para com gap de 0,01%. A entrada iteration_limit encerra a execução se o gap não se fechar antes; uma simulação amostrada após o treinamento registra um aviso informativo na preparação (simulation.selection). O critério gap só é admitido com seleção enumerated e a mesma medida de risco em todos os estágios (o padrão expectation atende), e todo estágio declara uma única abertura (num_openings: 1 em stages.json), porque a seleção enumerada o exige (training.selection).

{
"training": {
"selection": { "method": "enumerated" },
"stopping_rules": [
{ "type": "gap", "relative_tolerance": 0.01 },
{ "type": "iteration_limit", "limit": 50 }
]
}
}

Limite uma execução pelo tempo de relógio. Com o stopping_mode padrão ("any"), o treinamento para no primeiro critério satisfeito; portanto, combine time_limit com um iteration_limit acima do que o tempo permite: o treinamento nunca ultrapassa o maior iteration_limit do conjunto.

{
"training": {
"stopping_rules": [
{ "type": "time_limit", "seconds": 600.0 },
{ "type": "iteration_limit", "limit": 1000 }
]
}
}

Treine com ruído dentro da amostra e simule com afluência fora da amostra. A simulation.scenario_source.seed (77) conduz os sorteios fora da amostra da simulação (Resolução das sementes). Os campos de simulation.scenario_source estão listados em simulation.scenario_source.

{
"training": {
"selection": { "method": "sampled", "forward_passes": 50 },
"stopping_rules": [{ "type": "iteration_limit", "limit": 200 }],
"scenario_source": { "seed": 77 }
},
"simulation": {
"enabled": true,
"selection": { "method": "sampled", "num_scenarios": 2000 },
"scenario_source": {
"seed": 77,
"inflow": { "scheme": "out_of_sample" },
"load": { "scheme": "in_sample" },
"ncs": { "scheme": "in_sample" }
}
}
}

{
"$schema": "https://docs.modelossetoreletrico.org.br/schemas/config.schema.json",
"training": {
"tree_seed": 42,
"selection": { "method": "sampled", "forward_passes": 50 },
"stopping_rules": [
{ "type": "iteration_limit", "limit": 200 },
{ "type": "bound_stalling", "iterations": 20, "tolerance": 0.0001 }
],
"stopping_mode": "any",
"scenario_source": {
"seed": 99,
"inflow": { "scheme": "out_of_sample" },
"load": { "scheme": "in_sample" },
"ncs": { "scheme": "in_sample" }
},
"cut_selection": {
"row_activity_tolerance": 1e-6,
"max_active_per_stage": null,
"selection": {
"method": "level1",
"check_frequency": 5
}
}
},
"modeling": {
"inflow_non_negativity": {
"method": "truncation_with_penalty"
}
},
"simulation": {
"enabled": true,
"selection": { "method": "sampled", "num_scenarios": 2000 }
},
"policy": {
"path": "./policy",
"mode": "fresh"
},
"exports": {
"states": false,
"stochastic": false
}
}