Pular para o conteúdo

Códigos de erro

A carga do caso reporta erros em dois grupos: tipos de relatório de validação (categorias de diagnóstico coletadas durante a validação do caso) e tipos de falha de carga (retornados quando a carga do caso falha). A página também lista os erros de carga da política gerados pela recusa de um checkpoint e os erros de execução de um novomodelo run em andamento.

O Novo Modelo expõe erros por quatro canais voltados ao usuário:

  • Relatório legível de novomodelo validate — os erros são impressos como linhas com o prefixo error:; os avisos (após uma validação bem-sucedida) são impressos como linhas com o prefixo warning:.

  • novomodelo validate --json — em caso de sucesso, um objeto JSON no stdout: { configured, boundary_date, report }, mais policy_load: { mode, unused_stored_bases } quando a execução carregaria uma política (mode warm_start, resume ou simulation_only), sem chave error; configured é true quando policy.boundary está configurado e a execução o aplica, o que só ocorre em uma execução que treina, e false caso contrário. Em caso de falha, essas três chaves são null e uma chave error contém { phase, message }. O campo phase é o nome da variante de LoadError que falhou, um dos seis tipos da fase de preparação ou um tipo de carga da política (WarmStartIncompatible, ResumeIncompatible, SimulationPolicyIncompatible ou IoError para um checkpoint cuja leitura o sistema operacional recusa); ele nomeia uma variante de LoadError, um tipo de preparação ou um tipo de carga da política, nunca o ErrorKind de um diagnóstico coletado. Uma falha na carga do caso reporta ConstraintError em quase todos os casos, porque toda falha de leitura, análise sintática e esquema de cada arquivo e toda regra de validação são coletadas em um único relatório; seu message contém uma linha [<ErrorKind>] <file>[ (<entity>)]: <message> por erro coletado, unidas por quebras de linha (a parte [ (<entity>)] aparece apenas quando o erro nomeia uma entidade). Os avisos não constam do JSON. Somente a ausência do diretório do caso não imprime objeto JSON; ela é reportada no stderr e encerra com código 2.

    Um caso sem policy.boundary é validado com sucesso com:

    {
    "configured": false,
    "boundary_date": null,
    "report": null
    }

    Um grupo de unidades geradoras que referencia um barramento inexistente falha com:

    {
    "configured": null,
    "boundary_date": null,
    "report": null,
    "error": {
    "phase": "ConstraintError",
    "message": "[InvalidReference] system/hydros.json (Hydro 0 unit group 0): Hydro 0 unit group 0 references non-existent Bus 99 via field 'bus_id'"
    }
    }
  • novomodelo.io.validate(...) (Python) — retorna { valid, errors: [{ kind, message }], warnings: [{ kind, message, file, entity }] }. errors contém no máximo uma entrada: nenhuma quando valid é verdadeiro, uma em caso de falha. Seu kind é a mesma string do phase da CLI, e seu message é o texto completo do erro, que, em uma falha na carga do caso, começa com constraint violation: . Para um diretório do caso ausente, em que a CLI não imprime objeto JSON, o Python ainda retorna uma entrada IoError. O kind de cada aviso é o nome do ErrorKind.

  • Classes de exceção Python de novomodelo.errors — a carga do caso gera ValidationError ou CaseIoError; uma recusa na carga da política gera a classe do seu erro: PolicyIncompatibleError para um checkpoint recusado, ausente ou que não pode ser decodificado, CaseIoError para uma leitura de checkpoint recusada pelo sistema operacional, e ValidationError para um diretório da política ausente ou uma reconciliação de fronteira recusada (veja Erros de carga da política). Veja novomodelo.errors para a hierarquia completa e Guia rápido em Python — Tratamento de erros para a captura dessas classes.

As falhas de carga da política usam códigos de saída e classes de exceção diferentes; veja Como uma falha de carga da política chega até você. Para a causa e a correção das falhas mais comuns em um estudo, veja Solução de problemas.


Localize na primeira coluna o tipo indicado na sua linha de erro (a palavra entre colchetes, ou o valor de phase de novomodelo validate --json); a linha correspondente informa como o tipo é reportado, sua severidade e o código de saída que o novomodelo retorna.

TipoReportado comoSeveridadeCódigo de saída
FileNotFoundlinha de relatório [FileNotFound]Erro1
ParseErrorlinha de relatório [ParseError]; valor de phaseErro1 como linha de relatório; como valor de phase, 4 (novomodelo validate) ou 1 (novomodelo run)
SchemaViolationlinha de relatório [SchemaViolation]Erro1
InvalidReferencelinha de relatório [InvalidReference]Erro1
DuplicateIdlinha de relatório [DuplicateId]Erro1
InvalidValuelinha de relatório [InvalidValue]Erro1
CycleDetectedlinha de relatório [CycleDetected]Erro1
DimensionMismatchlinha de relatório [DimensionMismatch]Erro1
BusinessRuleViolationlinha de relatório [BusinessRuleViolation]Erro1
WarmStartIncompatiblevalor de phase (carga da política recusada); linha warning:Erro; Aviso1 (2 sob a fase IoError); 0 para um aviso
ResumeIncompatiblevalor de phase (carga da política recusada); linha warning:Erro; Aviso1 (2 sob a fase IoError); 0 para um aviso
SimulationPolicyIncompatiblevalor de phase (carga da política recusada); linha warning:Erro; Aviso1 (2 sob a fase IoError); 0 para um aviso
NotImplementedlinha de relatório [NotImplemented]Erro1
UnusedEntitylinha warning:Aviso0
ModelQualitylinha warning:Aviso0
SemanticAmbiguitylinha warning:Aviso0
IoErrorvalor de phaseErro2, inclusive para uma leitura da política recusada pelo sistema operacional
SchemaErrorvalor de phaseErro1, inclusive para uma recusa de policy.path; 4 sob novomodelo validate apenas para a divergência na contagem de coeficientes AR posterior ao relatório (novomodelo run: 1)
ConstraintErrorvalor de phaseErro1
ConfigValidationErrorvalor de phaseErro1
StochasticPreparationErrorvalor de phaseErro1, ou 2 para uma leitura de entrada estocástica, como uma árvore de aberturas declarada e ausente (ambos os subcomandos)
StudySetupErrorvalor de phaseErro1
HydroModelsPreparationErrorvalor de phaseErro1
GenericConstraintValidationErrorvalor de phaseErro1
BoundaryReconciliationErrorvalor de phaseErro1
PolicySoftwareMismatchrecusa na carga da políticaErro1
Bases armazenadas não utilizadaslinha warning:Aviso0

As falhas de execução não têm tipo; Erros de execução informa o código de saída de cada mensagem. Uma rejeição de perfil do solver tem a fase StudySetupError, ou BoundaryReconciliationError com policy.boundary configurado; Validação do perfil do solver informa seu código de saída.


Cada erro coletado na carga de um caso é impresso como uma linha de relatório, [<Kind>] <file> (<entity>): <message>. A parte (<entity>) aparece apenas quando o erro nomeia uma entidade, e <Kind> é um dos valores abaixo.

novomodelo validate imprime cada erro como error: seguido da sua linha de relatório e encerra com código 1 quando há algum erro. novomodelo run imprime error: constraint violation: seguido das mesmas linhas. Após uma validação bem-sucedida, novomodelo validate imprime cada aviso como uma linha warning: no formato <file> (<entity>): <message> após a linha Valid case: ..., sem o tipo entre colchetes, e novomodelo.io.validate (Python) retorna os avisos, cada um com seu tipo, no array warnings. Um aviso da carga da política que a execução aplicaria é impresso depois deles como warning: <output dir>/<policy.path>: <message>, não nomeia entidade e é contabilizado na linha Validation:.

Os três tipos de aviso (UnusedEntity, ModelQuality, SemanticAmbiguity) nunca interrompem uma execução, assim como um BusinessRuleViolation que novomodelo validate imprime como linha warning:; todas as demais linhas de relatório são erros que precisam ser resolvidos para que o caso seja carregado.

WarmStartIncompatible, ResumeIncompatible e SimulationPolicyIncompatible não são tipos de linha de relatório: cada um nomeia uma carga da política recusada, como valor de phase, e os avisos dessa carga: WarmStartIncompatible para uma carga com policy.mode = "warm_start" em uma execução que treina, ResumeIncompatible para uma carga com policy.mode = "resume" em uma execução que treina, e SimulationPolicyIncompatible para a carga de uma execução somente de simulação, qualquer que seja seu policy.mode; veja as respectivas entradas abaixo.

Severidade: Erro

Quando ocorre: Um arquivo exigido pela estrutura do caso está ausente do diretório do caso. Emitido durante a verificação dos arquivos obrigatórios, uma vez para cada um que não é encontrado em disco.

Exemplo: Um diretório do caso sem system/hydros.json:

[FileNotFound] system/hydros.json: required file 'system/hydros.json' not found in case directory

Um diretório do caso sem system/buses.json gera duas linhas [FileNotFound]: a primeira reporta o arquivo obrigatório ausente, a segunda, a falha na sua leitura:

[FileNotFound] system/buses.json: required file 'system/buses.json' not found in case directory
[FileNotFound] system/buses.json: No such file or directory (os error 2)

Solução: Crie o arquivo ausente no subdiretório correto. Os arquivos obrigatórios são: config.json, penalties.json, stages.json, initial_conditions.json, system/buses.json e system/hydros.json.


Severidade: Erro

Quando ocorre: Um arquivo existe e foi lido, mas não pôde ser analisado — sintaxe JSON inválida, cabeçalho Parquet ilegível, campo obrigatório ausente ou variante de enum desconhecida em uma união JSON com tag. Emitido quando a análise sintática de um arquivo falha. config.json e system/hydros.json reportam um campo ausente ou uma variante desconhecida como SchemaViolation, e system/hydro_production_models.json faz o mesmo para uma variante desconhecida. Uma entrada de training.stopping_rules que contenha um campo pertencente a outro type de regra — por exemplo, seconds (um campo de time_limit) em uma regra bound_stalling — também é rejeitada como ParseError, com uma mensagem unknown field.

Formato de exibição:

parse error in {path}: {message}

Este formato só aparece para um erro de análise gerado após a conclusão do relatório de validação (veja Tipos de falha de carga); uma falha de análise no relatório é impressa como a linha [ParseError] mostrada nos exemplos abaixo.

Campos:

CampoDescrição
pathCaminho do arquivo cuja análise falhou
messageDescrição legível da falha de análise

Exemplo:

[ParseError] stages.json: parse error: EOF while parsing a list at line 2 column 0

Um campo obrigatório ausente, aqui uma entrada de restrição sem slack:

[ParseError] constraints/generic_constraints.json: parse error: missing field `slack` at line 1 column 69

Uma regra bound_stalling que contém seconds, um campo de time_limit:

[ParseError] config.json: parse error: unknown field `seconds`, expected `iterations` or `tolerance` at line 19 column 5

Solução: Corrija o erro de sintaxe no arquivo indicado. Use um validador de JSON ou um visualizador de Parquet para localizar a posição exata. Em arquivos JSON, as causas comuns são vírgulas finais, aspas ausentes ou chaves desbalanceadas. Para uma mensagem missing field, adicione o campo indicado. Para uma mensagem unknown field dentro de uma entrada de stopping_rules, remova o campo que não pertence ao type dessa entrada ou mova-o para uma entrada cujo type o declare.

Veja também: um objeto anticipated_config em system/thermals.json que não corresponda a nenhuma das formas de antecedência aceitas é coletado sob este tipo — veja Antecedência inválida de térmica antecipada.

Campo desconhecido em uma entrada de restrição genérica

Seção intitulada “Campo desconhecido em uma entrada de restrição genérica”

Quando ocorre: Cada objeto de restrição genérica aceita exatamente cinco campos (id, name, description, expression, slack); qualquer outra chave é rejeitada como ParseError, com uma mensagem unknown field.

Campos:

CampoDescrição
pathSempre constraints/generic_constraints.json
messageUma mensagem “unknown field”, que nomeia a chave indevida e os cinco nomes de campo aceitos

Exemplo: Um objeto de restrição com uma chave type adicional:

[ParseError] constraints/generic_constraints.json: parse error: unknown field `type`, expected one of `id`, `name`, `description`, `expression`, `slack` at line 10 column 12

Solução: Remova o campo desconhecido, mantendo apenas as cinco chaves aceitas. Veja Restrições genéricas para a gramática.


Severidade: Erro

Quando ocorre: Um arquivo é analisado com sucesso, mas um campo viola uma restrição do esquema: um campo obrigatório está ausente de config.json ou de system/hydros.json, ou uma coluna Parquet obrigatória está ausente (um campo ausente em qualquer outro arquivo JSON é um ParseError), um arquivo Parquet traz uma coluna que a respectiva tabela não lista, um valor está fora do intervalo válido (por exemplo, capacidade negativa, custo de penalidade não positivo, reservatório cujo min_storage_hm3 excede max_storage_hm3 ou estágio cujo num_openings é 0), um campo contém um tipo inesperado, ou um id de entidade aparece duas vezes em um arquivo de cadastro como system/buses.json. Emitido durante a verificação dos campos de um arquivo já analisado.

Exemplo:

Um custo de penalidade negativo:

[SchemaViolation] system/buses.json: field buses[0].deficit_segments[0].cost: penalty value must be > 0.0, got -100

Um reservatório cujo armazenamento mínimo excede o máximo:

[SchemaViolation] system/hydros.json: field hydros[0].reservoir: min_storage_hm3 (800) must be <= max_storage_hm3 (500)

Um estágio sem aberturas:

[SchemaViolation] stages.json: field stages[0].num_openings: num_openings must be > 0

Um config.json sem training.selection:

[SchemaViolation] config.json: field training.selection: a forward-pass count is required via training.selection

Dois barramentos com o mesmo id em system/buses.json:

[SchemaViolation] system/buses.json: field buses[1].id: duplicate id 0 in buses array

Solução: Corrija o valor no campo indicado. Os caminhos de campo usam notação de ponto e índices de array começando em zero. Consulte a página Formato do caso para os intervalos válidos e os campos obrigatórios. Para limites de armazenamento, garanta min <= max. Para quantidades de aberturas, garanta num_openings >= 1. Em config.json, training.selection (por exemplo, { "method": "sampled", "forward_passes": 192 }) e training.stopping_rules são chaves obrigatórias, sem valor padrão quando ausentes. A ausência de training.selection é reportada com a mensagem a forward-pass count is required via training.selection; adicione a chave em config.json.

Veja também: uma inversão da faixa de vertimento ou uma rejeição de não negatividade em constraints/hydro_bounds.parquet é coletada sob este tipo durante uma carga completa do caso — veja Inversão da faixa de vertimento. Duas das quatro falhas de Antecedência inválida de térmica antecipada imprimem linhas [SchemaViolation]; as outras duas imprimem linhas [ParseError] e [BusinessRuleViolation]. A carga de um caso imprime toda falha de esquema como uma linha [SchemaViolation]; a forma schema error in <path>, field <field>: <message> é o formato de exibição de SchemaError, que só aparece para um erro de carga gerado após a conclusão do relatório.

O objeto slack de uma restrição genérica também é verificado sob este tipo, no campo constraints[<i>].slack.penalty ou constraints[<i>].slack.penalty_basis: uma folga habilitada exige um penalty positivo e um penalty_basis, e uma folga desabilitada não traz nenhum dos dois. A mensagem de base ausente indica a escolha:

slack.enabled is true but slack.penalty_basis is absent: use "per_hour" for a row in MW or m³/s, "per_unit" for a row in MWh or hm³

As demais mensagens de folga:

slack.enabled is true but slack.penalty is absent
slack.penalty must be > 0.0 when enabled, got {value}
slack.penalty is set but slack.enabled is false
slack.penalty_basis is set but slack.enabled is false

Um penalty_basis diferente de per_hour ou per_unit é um ParseError (unknown variant). Veja Restrições genéricas — Base de penalização.

A faixa de ajuste de uma FPHA calculada em system/hydro_production_models.json também é verificada sob este tipo: um fpha_config.spillage_fit_max_m3s ou fpha_config.turbined_fit_max_m3s que não seja um número finito maior que 0 é recusado no campo production_models[<i>].stage_ranges[<j>].fpha_config.<name> (ou production_models[<i>].seasons[<j>].fpha_config.<name>):

<name> must be finite and > 0.0, got <value> for hydro_id <id>

A carga de config.json recusa os valores abaixo; cada um imprime uma linha [SchemaViolation] config.json: field <field>: <message>, e ambos os comandos encerram com código 1.

RegraCampoMensagem
Nenhuma regra iteration_limittraining.stopping_rulesmust contain an iteration_limit rule
interval_iterations ausente ou menor que 1, com checkpointing habilitadopolicy.checkpointing.interval_iterationsmust be at least 1 when policy.checkpointing.enabled is true; got {found}
policy.path que não nomeia um subdiretório ("", ., ..)policy.path"{value}" names the output directory or one of its ancestors, which a checkpoint write would replace; choose another directory, such as "./policy"

{found} é no value quando a chave está ausente e 0 caso contrário. {value} é o policy.path configurado.

Quando ocorre: policy.path é resolvido em relação a --output, e um link é verificado tanto onde está quanto para onde aponta. O caminho é recusado quando nomeia o diretório de saída ou um de seus ancestrais, ou quando nomeia, contém ou está dentro de um diretório que uma execução reescreve ou remove. Configuração — policy enuncia a regra. Em um caso que treina, o caminho também é recusado quando ele (para um link, seu destino) ou seu irmão .staging ou .previous não é um diretório ou contém uma entrada que nenhum gravador de checkpoint deixa ali; a mensagem é refusing to write a checkpoint: …, citada em Gerenciamento da política — Conteúdo do diretório de checkpoint.

"{value}" names the output directory or one of its ancestors, which a checkpoint write would replace; choose another directory, such as "./policy"
"{value}" {relation} {dir}, which a run removes whole before writing its outputs; choose a directory that neither contains nor lies inside it, such as "./policy"
"{value}" {relation} {dir}, which holds files a run writes and a checkpoint write would replace; choose a directory that neither names nor contains it, such as "./policy"

{relation} é names, contains ou lies inside, e {dir} é o diretório relativo à saída, como simulation/hydros. Para um link, {value} assume a forma {path} -> {target}. novomodelo validate reporta a fase SchemaError (código de saída 1), ou IoError (código de saída 2) quando o caminho não pode ser inspecionado; novomodelo run imprime error: schema error in {path}, field policy.path: {message} e encerra com código 1.

Estações sobrepostas em um mesmo nível de resolução

Seção intitulada “Estações sobrepostas em um mesmo nível de resolução”

Quando ocorre: Períodos sazonais cujas durações diferem em no máximo 7 dias formam um nível de resolução, e dois períodos sazonais de um mesmo nível não podem compartilhar um dia do calendário. A carga recusa um par sobreposto de season_definitions com [SchemaViolation] stages.json: field season_definitions.seasons: <message>, em que <message> é:

seasons {a} and {b} overlap within one resolution level; seasons whose spans differ by at most 7 days form one level and must not share a calendar day

{a} e {b} são os ids dos dois períodos sazonais. Arquivos de estágios — stages.json descreve season_definitions.

Colisão de namespace entre um parâmetro escalar e uma expressão nomeada

Seção intitulada “Colisão de namespace entre um parâmetro escalar e uma expressão nomeada”

Quando ocorre: O array expressions de constraints/generic_constraints.json declara expressões lineares nomeadas que compartilham o namespace de referências @name com os parâmetros escalares de constraints/generic_parameters.json. Uma entrada de expressão nomeada cujo name coincida com o name de um parâmetro escalar já carregado é rejeitada — um token @name deve se resolver sem ambiguidade para exatamente um tipo de objeto.

Campos:

CampoDescrição
pathSempre constraints/generic_constraints.json
fieldexpressions[i].name — o índice da entrada em colisão
messagename "<name>" is declared as both a scalar parameter and a named expression; the "@name" namespace is shared

Exemplo:

[SchemaViolation] constraints/generic_constraints.json: field expressions[0].name: name "demanda" is declared as both a scalar parameter and a named expression; the "@name" namespace is shared

Solução: Renomeie a expressão nomeada (ou o parâmetro escalar) para que as duas tabelas @name não se sobreponham. Veja Restrições genéricas para a gramática @name compartilhada entre os dois arquivos.

Quando ocorre: As entradas de expressions[] referenciam-se umas às outras por @name; um ciclo nesse grafo de referências (incluindo uma autorreferência de comprimento 1) é rejeitado antes que qualquer expressão seja expandida, mesmo que nenhuma restrição a utilize.

Campos:

CampoDescrição
pathSempre constraints/generic_constraints.json
fieldSempre expressions
messagenamed-expression reference cycle detected: <a> -> <b> -> ... -> <a>

Exemplo:

[SchemaViolation] constraints/generic_constraints.json: field expressions: named-expression reference cycle detected: fnese -> fnese_margin -> fnese

Solução: Quebre o ciclo — reescreva uma das expressões nomeadas da cadeia reportada para que ela deixe de referenciar um ancestral. Veja Restrições genéricas para as regras de composição de @name.

Limite de termos na expansão de expressões nomeadas excedido

Seção intitulada “Limite de termos na expansão de expressões nomeadas excedido”

Quando ocorre: A expansão substitui cada referência @name pela expressão referenciada e agrega o resultado em um único coeficiente por variável. Uma declaração acíclica, mas de expansão exponencial, é detectada assim que a expansão ultrapassaria 100.000 operações sobre coeficientes, muito acima de qualquer expressão escrita legitimamente, abortando a explosão antes que ela se materialize. Uma cadeia de duplicação cujos elos são multiplicados por um parâmetro escalar, @e_k = @a * @e_{k-1} + @e_{k-1}, atinge o limite; uma cadeia de simples autoadições, @e_k = @e_{k-1} + @e_{k-1}, reduz-se a um termo por variável e fica abaixo dele. O limite só se aplica quando uma restrição (ou outra expressão) de fato referencia a declaração descontrolada — declará-la sem referenciá-la é apenas uma verificação de existência, de baixo custo, e não uma expansão.

Campos:

CampoDescrição
pathSempre constraints/generic_constraints.json
fieldconstraints[i].expression (ou o próprio campo da expressão que referencia)
message `@<name>`: named-expression reference "@<name>" expands to more than 100000 coefficient operations; this indicates an exponential reference pattern (e.g. a doubling chain "@e = @prev + @prev") quando a expansão ocorre dentro de uma expressão nomeada referenciada, ou `<fragment>`: expression expands to more than 100000 coefficient operations quando ocorre no próprio texto da expressão que referencia, por exemplo @e15 + @e15

Exemplo:

[SchemaViolation] constraints/generic_constraints.json: field constraints[0].expression: `@e60`: named-expression reference "@e60" expands to more than 100000 coefficient operations; this indicates an exponential reference pattern (e.g. a doubling chain "@e = @prev + @prev")

Solução: Reescreva a cadeia de expressões nomeadas para que cresça linearmente, e não por autoadições repetidas — por exemplo, acumulando em uma única expressão corrente em vez de duplicar uma referência a cada passo. Veja Restrições genéricas para as regras de composição de @name.

Quando ocorre: Uma expressão em constraints/generic_constraints.json (constraints[i].expression, ou expressions[i].expression para a definição de uma expressão nomeada) recusada pela gramática ou pela sua regra de linearidade. Toda mensagem começa com o fragmento problemático entre crases, como em `@zz`: unknown name …; um problema no final do texto termina, em vez disso, com (at the end of the expression).

ErroMensagem após o fragmento citado
Um @name declarado nem como parâmetro escalar nem como expressão nomeadaunknown name "@<name>": no scalar parameter or named expression with this name was declared
Um produto de dois termos que contêm variáveis do PLproduct of LP variables is not linear; quando um fator é uma expressão nomeada, seguido de ("@<name>" is the named expression at expressions[<i>], which contains LP variables)
Uma divisão por um termo que contém variável do PLdivision by an expression containing LP variables
Uma constante formada por números que divide por zerodivision by zero
Um literal numérico grande demais para ser representadonumeric literal <text> is not finite
Uma parte constante em uma expressão sem operador relacionalan expression without a relational operator cannot have a constant part; put the bound in generic_constraint_bounds.parquet or use <=, >= or ==
Dois operadores relacionaisa generic constraint expression carries at most one relational operator (<=, >=, ==); an inline double-relational range is not supported — split into two constraints
Um operador relacional dentro de parêntesesa relational operator is only allowed at the top level
Um < ou > isoladobare '<' at position <n> is not a valid operator; use '<=' for a relational bound
Parênteses e sinais unários aninhados em mais de 256 níveisexpression nests deeper than 256 levels
Um corpo de expressão nomeada com operador relacionala named expression cannot contain a relational operator
Um corpo de expressão nomeada que não lê nenhuma variável do PL"<name>" contains no LP variable; declare it in generic_parameters.json as a kind "expression" parameter

Campos:

CampoDescrição
pathSempre constraints/generic_constraints.json
fieldconstraints[i].expression ou expressions[i].expression
messageO fragmento citado, seguido de uma das mensagens da tabela acima

Exemplo: Um produto de duas variáveis do PL:

[SchemaViolation] constraints/generic_constraints.json: field constraints[0].expression: `hydro_generation(0) * thermal_generation(0)`: product of LP variables is not linear

Solução: Mantenha todos os termos lineares: multiplique uma variável do PL apenas por um número, um parâmetro escalar ou uma expressão formada por eles, e divida apenas por uma constante desse tipo. Verifique se cada @name corresponde a um parâmetro declarado em constraints/generic_parameters.json ou a uma entrada do próprio array expressions deste arquivo; mova um corpo que não lê nenhuma variável do PL para constraints/generic_parameters.json como um parâmetro expression. Veja Restrições genéricas — Gramática das expressões para a gramática completa.

Quando ocorre: Uma entrada de constraints/generic_parameters.json cujos campos não correspondem ao seu kind, ou um parâmetro expression cuja fórmula é recusada. As mensagens sobre a fórmula começam com o fragmento problemático entre crases, como em uma expressão de restrição genérica.

ErroCampoMensagem
Um campo de conteúdo de outro tipo, como values em um constantscalar_parameters[i].<field>"values" is only valid for kind "per_stage" or "seasonal", not "constant"
Um parâmetro expression sem sua fórmulascalar_parameters[i].expression"expression" kind requires an "expression" field
Uma variável do PL na fórmulascalar_parameters[i].expressionan LP variable cannot appear in a scalar-parameter expression
Um @name que não é parâmetro escalarscalar_parameters[i].expressionunknown scalar parameter "@<name>"; a named expression cannot appear in a scalar-parameter expression
Um operador relacional na fórmulascalar_parameters[i].expressiona scalar-parameter expression cannot contain a relational operator
Uma constante que divide por zeroscalar_parameters[i].expressiondivision by zero
Um ciclo de referências entre parâmetros expressionscalar_parametersexpression-parameter reference cycle detected: <a> -> <b> -> ... -> <a>

Campos:

CampoDescrição
pathSempre constraints/generic_parameters.json
fieldO campo indicado na tabela acima
messageUma das mensagens da tabela acima

Exemplo: Um parâmetro expression que lê uma variável do PL:

[SchemaViolation] constraints/generic_parameters.json: field scalar_parameters[0].expression: `hydro_storage(0)`: an LP variable cannot appear in a scalar-parameter expression

Solução: Atribua a cada entrada apenas o campo de conteúdo do seu tipo. Monte um parâmetro expression somente a partir de números e de outros parâmetros escalares, sem operador relacional, e quebre qualquer ciclo entre eles. Uma fórmula sobre variáveis do PL deve ficar em constraints/generic_constraints.json, como uma expressão nomeada. Veja Restrições genéricas — parâmetros expression. Uma fórmula cujo valor não é finito apenas em algum estágio e patamar é reportada por GenericConstraintValidationError.

Quando ocorre: Uma variável aceita no máximo um argumento posicional de patamar. Um segundo argumento, igual ou não, é rejeitado na análise da expressão, por exemplo hydro_turbined(5, 0, 1).

Campos:

CampoDescrição
pathSempre constraints/generic_constraints.json
fieldconstraints[<i>].expression ou expressions[<i>].expression
messagerepeated block argument in variable "{name}", em que {name} é a variável, como hydro_turbined

Solução: Informe um único argumento de patamar para a variável. Veja Restrições genéricas — Gramática das expressões para a gramática completa.

Quando ocorre: Uma entrada Parquet traz uma coluna que a respectiva tabela em Formato do caso não lista. Os nomes das colunas são verificados na abertura do arquivo, antes da leitura de qualquer linha e da verificação de qualquer tipo de coluna, e a primeira coluna não listada, na ordem das colunas do arquivo, é recusada.

Campos:

CampoDescrição
pathO arquivo Parquet
fieldO nome da coluna não listada
messageUma das três formas abaixo

A mensagem toma a primeira forma que se aplica:

  • column "<name>" is no longer read; <instruction> para uma coluna com instrução própria: residual_std_ratio em scenarios/inflow_ar_coefficients.parquet, reference_volume_hm3 em system/hydro_energy_productivity.parquet e date em scenarios/inflow_history.parquet;
  • unknown column "<name>"; did you mean "<column>"? quando uma coluna que o arquivo pode trazer está a uma distância de edição de no máximo um terço do nome mais longo (no mínimo 1), sem distinguir maiúsculas de minúsculas; a mensagem nomeia a mais próxima;
  • unknown column "<name>"; the columns this file may carry are <columns> nos demais casos, listando todas as colunas que o arquivo pode trazer.

Exemplos:

Uma coluna com o nome grafado errado, mean_m3 em vez de mean_m3s, em scenarios/inflow_seasonal_stats.parquet:

[SchemaViolation] scenarios/inflow_seasonal_stats.parquet: field mean_m3: unknown column "mean_m3"; did you mean "mean_m3s"?

O mesmo arquivo com a coluna hydro_id chamada hydro, que não fica perto de nenhuma coluna que o arquivo pode trazer:

[SchemaViolation] scenarios/inflow_seasonal_stats.parquet: field hydro: unknown column "hydro"; the columns this file may carry are hydro_id, stage_id, mean_m3s, std_m3s

Uma coluna residual_std_ratio em scenarios/inflow_ar_coefficients.parquet:

[SchemaViolation] scenarios/inflow_ar_coefficients.parquet: field residual_std_ratio: column "residual_std_ratio" is no longer read; it is derived from the AR coefficients at load; remove the column

Um DataFrame que o DataFrame.to_parquet do pandas gravou depois de ter as linhas reordenadas, o que mantém o índice como coluna:

[SchemaViolation] scenarios/inflow_seasonal_stats.parquet: field __index_level_0__: unknown column "__index_level_0__"; the columns this file may carry are hydro_id, stage_id, mean_m3s, std_m3s

Solução: Renomeie a coluna como a sugestão indica ou remova-a; para uma coluna com instrução própria, siga a instrução. O DataFrame.to_parquet do pandas grava um índice que não seja o índice de intervalo padrão (o índice que um DataFrame filtrado ou reordenado mantém) como uma coluna chamada __index_level_0__: passe index=False ou monte a tabela com pa.Table.from_pandas(df, schema=schema).

Quando ocorre: Uma entrada Parquet sem uma coluna obrigatória é uma falha de esquema que nomeia a coluna obrigatória. Um arquivo que traz a coluna com outro nome é recusado antes, por esse nome (Coluna Parquet desconhecida).

Campos:

CampoDescrição
pathO arquivo Parquet
fieldO nome da coluna obrigatória
messagemissing required column "<name>"

Exemplo: Um scenarios/inflow_seasonal_stats.parquet sem a coluna hydro_id:

[SchemaViolation] scenarios/inflow_seasonal_stats.parquet: field hydro_id: missing required column "hydro_id"

Solução: Acrescente a coluna com o nome exigido pelo arquivo. As tabelas de colunas de Formato do caso listam as colunas obrigatórias de cada arquivo.

Quando ocorre: Um bloco training.scenario_source ou simulation.scenario_source de config.json viola uma regra de admissão. As regras são verificadas na carga de config.json, de modo que novomodelo validate e novomodelo run encerram com código 1. Na tabela, {section} representa training ou simulation, conforme o bloco que violou a regra, e {from} e {to} representam o primeiro e o último ano do intervalo como declarados no caso. A mensagem impressa mostra esses valores no lugar dos marcadores.

RegraCampoMensagem
openings sob simulationsimulation.scenario_source.openingsopenings is only valid under training.scenario_source, not simulation.scenario_source
historical_years sem classe historical{section}.scenario_source.historical_yearshistorical_years is specified but no class uses the 'historical' scheme
historical em load ou ncs{section}.scenario_source.load.scheme ou {section}.scenario_source.ncs.schemehistorical scheme is only valid for the inflow class
seed ausente{section}.scenario_source.seedseed is required when any class uses out_of_sample or external scheme
Intervalo historical_years invertido{section}.scenario_source.historical_yearsrange 'from' ({from}) must be <= 'to' ({to})

Exemplo: novomodelo validate em um caso cujo training.scenario_source define a classe de afluências como out_of_sample sem seed:

[SchemaViolation] config.json: field training.scenario_source.seed: seed is required when any class uses out_of_sample or external scheme

novomodelo validate imprime esta linha após o prefixo error: . novomodelo run a imprime após error: constraint violation: .

Solução: Configuração lista as chaves de scenario_source. Localize a mensagem na tabela acima e corrija a regra correspondente:

  • openings: declare-o apenas sob training.scenario_source.
  • historical_years: remova-o ou defina a classe de afluências com o esquema historical.
  • load ou ncs: use outro esquema; apenas a classe de afluências aceita historical.
  • seed: adicione-a ao bloco.
  • Intervalo historical_years invertido: defina from não posterior a to.

Um arquivo de árvore de aberturas declarado e ausente é reportado na fase estocástica: Arquivo da árvore de aberturas ausente.

Quando ocorre: O intervalo estimation.history_years de config.json tem um ano from posterior ao seu ano to. O intervalo é verificado quando config.json é carregado, de modo que novomodelo validate e novomodelo run encerram com código 1, quer a execução estime ou não a partir do histórico de afluências.

[SchemaViolation] config.json: field estimation.history_years: range 'from' ({from}) must be <= 'to' ({to})

Solução: Defina from não posterior a to; veja Configuração — estimation.

Quando ocorre: O anticipated_config de uma térmica em system/thermals.json aceita exatamente uma de duas chaves: lead_stages (um inteiro maior ou igual a 1) ou lead_time_hours (um número finito maior que 0). Uma antecedência maior que todo o horizonte de estudo também precisa alcançar um estágio pós-estudo declarado. Quatro falhas acrescentam, cada uma, uma linha ao relatório de validação:

  • lead_stages é 0.
  • lead_time_hours é zero ou negativo.
  • O objeto não corresponde a nenhuma das formas aceitas, por exemplo por ter as duas chaves, nenhuma delas ou um lead_stages negativo.
  • A antecedência é maior que todo o horizonte de estudo e não alcança nenhum estágio pós-estudo declarado.

Mensagens: novomodelo validate imprime uma linha error: para cada falha. As três primeiras falhas interrompem a leitura de system/thermals.json na primeira entrada problemática, de modo que um arquivo com várias antecedências inválidas reporta apenas a primeira; a regra do horizonte reporta todas as térmicas problemáticas. As capturas seguem a ordem da lista acima.

error: [SchemaViolation] system/thermals.json: field thermals[0].anticipated_config.lead_stages: lead_stages must be >= 1, got 0
error: [SchemaViolation] system/thermals.json: field thermals[0].anticipated_config.lead_time_hours: lead_time_hours must be finite and > 0.0, got -1
error: [ParseError] system/thermals.json: parse error: data did not match any variant of untagged enum RawAnticipatedConfig at line 18 column 5
error: [BusinessRuleViolation] system/thermals.json (thermals[id=0].anticipated_config.lead_stages): Thermal 0: lead_stages exceeds study horizon (lead_stages=9, n_stages=4); the plant can never deliver within the study horizon

Uma antecedência lead_time_hours que viola a regra do horizonte produz esta mensagem no lugar da mensagem de lead_stages acima:

Thermal {thermal_id}: lead_time exceeds study horizon (lead_time={delta_hours}, total_horizon_hours={total_horizon_hours}); the plant can never deliver within the study horizon

{thermal_id} é o id da térmica, {delta_hours} é sua antecedência em horas e {total_horizon_hours} é a duração de todo o horizonte de estudo em horas. Nas linhas SchemaViolation, o índice em thermals[0] é a posição da entrada no array thermals, contando a partir de 0; a mensagem do horizonte nomeia, em vez disso, o id da térmica, como em thermals[id=0].

Solução: Mantenha apenas uma das duas chaves: atribua a lead_stages um inteiro maior ou igual a 1, ou a lead_time_hours um número maior que 0. Para uma antecedência maior que o horizonte de estudo, reduza a antecedência ou declare, em post_study_stages.json, um estágio pós-estudo que a antecedência alcance. Veja Visão geral da modelagem dos elementos do sistema §4 para o modelo de térmica antecipada e system/thermals.json para os campos do arquivo.

Quando ocorre: Uma faixa de vertimento invertida (min_spillage_m3s > max_spillage_m3s) ou um min_diversion_m3s, min_spillage_m3s ou max_spillage_m3s negativo em constraints/hydro_bounds.parquet é reportado aqui (com a tag [SchemaViolation]) na carga completa de um caso, e aparece como um SchemaError isolado quando esse arquivo é verificado separadamente.

Campos:

CampoDescrição
descriptionContém uma linha [SchemaViolation] constraints/hydro_bounds.parquet: field hydro_bounds[<i>].<column>: <message> — veja abaixo

Exemplo:

[SchemaViolation] constraints/hydro_bounds.parquet: field hydro_bounds[0].max_spillage_m3s: max_spillage_m3s (5) must be >= min_spillage_m3s (10)
[SchemaViolation] constraints/hydro_bounds.parquet: field hydro_bounds[0].min_diversion_m3s: value must be >= 0.0, got -5

Solução: Corrija a linha problemática para que min_spillage_m3s <= max_spillage_m3s e para que min_diversion_m3s, min_spillage_m3s e max_spillage_m3s sejam todos não negativos. Veja Formato do caso para a referência das colunas de hydro_bounds.parquet.

Quando ocorre: O diversion.max_flow_m3s de uma hidrelétrica em system/hydros.json é negativo. A capacidade do canal limita superiormente a vazão desviada, e a vazão tem limite inferior 0, de modo que uma capacidade negativa é rejeitada na carga. Um canal sem limite de capacidade omite max_flow_m3s ou o define como null.

Campos:

CampoDescrição
descriptionContém uma linha [SchemaViolation] system/hydros.json: field hydros[<i>].diversion.max_flow_m3s: max_flow_m3s must be >= 0, got <value>, em que <i> é a posição da hidrelétrica no arquivo, a partir de zero

Exemplo:

[SchemaViolation] system/hydros.json: field hydros[0].diversion.max_flow_m3s: max_flow_m3s must be >= 0, got -5

Solução: Defina max_flow_m3s como a capacidade do canal, 0 ou mais, ou omita-o para um canal sem limite de capacidade. Um max_diversion_m3s por estágio ou por patamar em constraints/hydro_bounds.parquet continua limitando a vazão.


Severidade: Erro

Quando ocorre: Uma referência de chave estrangeira entre entidades aponta para uma entidade que não existe no cadastro esperado. Por exemplo, o bus_id de um dos grupos de unidades geradoras de uma usina hidrelétrica referencia um barramento que não está em system/buses.json. Emitido durante a resolução das referências entre entidades.

Exemplo:

[InvalidReference] system/hydros.json (Hydro 0 unit group 0): Hydro 0 unit group 0 references non-existent Bus 99 via field 'bus_id'

Solução: Adicione a entidade referenciada ao seu arquivo de cadastro ou corrija o ID no arquivo que a referencia. Verifique todas as referências de ID: unit_groups[].bus_id, thermals.bus_id, lines.source_bus_id, lines.target_bus_id, hydros.downstream_id.

Veja também: uma linha de constraints/ncs_bounds.parquet com um stage_id não declarado é reportada sob este tipo — veja stage_id não declarado em parquet de sobrescrita de limites.

Referência de limite de restrição genérica sem linhas de ativação

Seção intitulada “Referência de limite de restrição genérica sem linhas de ativação”

Quando ocorre: constraints/generic_constraint_bounds.parquet é a grade de ativação das restrições genéricas — uma restrição se aplica em (stage, block) se e somente se existir uma linha para ela ali, independentemente de a linha fornecer um extremo numérico ou de o extremo vir inteiramente do próprio resto afim embutido na restrição (por exemplo, um <= @demanda embutido). Uma restrição cujos únicos extremos vêm desse resto afim, mas que não tem nenhuma linha no parquet de limites, é coletada como InvalidReference — caso contrário, a referência não se aplicaria a nada e ficaria silenciosamente inerte.

Campos:

CampoDescrição
descriptionContém uma linha [InvalidReference] constraints/generic_constraints.json (GenericConstraint <id>): GenericConstraint <id> declares a bound reference but has no activation rows in generic_constraint_bounds.parquet: the reference would apply to nothing

Exemplo:

constraint violation: [InvalidReference] constraints/generic_constraints.json (GenericConstraint 3): GenericConstraint 3 declares a bound reference but has no activation rows in generic_constraint_bounds.parquet: the reference would apply to nothing

Solução: Adicione ao menos uma linha para o id da restrição em generic_constraint_bounds.parquet em cada (stage, block) em que ela deva se aplicar — a linha pode deixar bound_lower/bound_upper ambos nulos, desde que o próprio resto afim da restrição forneça o valor; a função da linha passa a ser apenas ativar a célula. Veja Restrições genéricas — a grade de ativação para o modelo completo.


Severidade: Erro

Quando ocorre: Um id ou chave é declarado duas vezes onde deve ser único. Três situações emitem este tipo: um id de grupo de unidades geradoras declarado duas vezes na mesma usina hidrelétrica (os ids de grupos de unidades são únicos dentro da usina, não globalmente); um id de nó do grafo da política (policy graph) declarado duas vezes em policy_graph.nodes[] de stages.json; e duas linhas de um arquivo de sobrescrita constraints/*_bounds.parquet que definem a mesma coluna para a mesma entidade, estágio e patamar. Um id de entidade declarado duas vezes em um arquivo de cadastro, como dois barramentos com o mesmo id em system/buses.json, é um SchemaViolation, e não um DuplicateId; veja o exemplo dos dois barramentos naquela seção.

Exemplo:

[DuplicateId] system/hydros.json (Hydro 0): Hydro 0: unit group id 0 is declared more than once; unit group ids must be unique within a plant

Solução: Renomeie o id repetido do grupo de unidades ou do nó, ou remova ou mescle as linhas de sobrescrita de limites que definem a mesma coluna duas vezes.


Severidade: Erro

Quando ocorre: Um valor viola uma regra de domínio que novomodelo validate verifica após a carga dos arquivos. Exemplos: as probabilidades das transições que saem de um estágio em stages.json não somam 1,0, ou um estágio do estudo tem um array blocks vazio. Um reservatório cujo min_storage_hm3 excede max_storage_hm3 e um estágio cujo num_openings é 0 são reportados, em vez disso, como linhas SchemaViolation.

Exemplo:

[InvalidValue] stages.json: outgoing transition probabilities from stage 0 sum to 0.50000000 (expected 1.0 ±0.000001); probability must sum to 1.0
[InvalidValue] stages.json: stage 1 declares no blocks; every study stage must declare at least one block

Solução: Corrija o valor indicado na mensagem. Consulte a página Formato do caso para as restrições documentadas. Para transições, faça as probabilidades que saem de cada estágio somarem 1,0. Para estágios, declare ao menos um patamar no array blocks de cada estágio do estudo.

Veja também: um min_diversion_m3s ou max_diversion_m3s positivo em uma hidrelétrica sem canal de desvio declarado é reportado sob este tipo — veja Limite de desvio sem canal declarado. Um limite de armazenamento de constraints/hydro_bounds.parquet fora da faixa do reservatório, ou um estágio do estudo cujo armazenamento mínimo excede o máximo, também é reportado sob este tipo — veja Limites de armazenamento por estágio recusados na carga. Um armazenamento inicial fora da faixa de armazenamento da hidrelétrica, ou listado no array errado de initial_conditions.json, também é reportado sob este tipo — veja Armazenamento inicial recusado na carga.

Linha de limites de restrição genérica sem nenhum extremo e sem resto afim

Seção intitulada “Linha de limites de restrição genérica sem nenhum extremo e sem resto afim”

Quando ocorre: Uma linha de generic_constraint_bounds.parquet com bound_lower = null e bound_upper = null só é válida quando o próprio bound_lower_affine/bound_upper_affine da restrição fornece ao menos um extremo (a linha então apenas ativa a célula, conforme acima). Uma linha com ambos nulos em uma restrição sem resto afim em nenhum dos lados não tem extremo algum e é coletada como InvalidValue.

Campos:

CampoDescrição
descriptionContém uma linha [InvalidValue] constraints/generic_constraint_bounds.parquet (GenericConstraintBoundsRow[<i>]): GenericConstraintBoundsRow[<i>] on constraint <id> has neither bound_lower nor bound_upper: at least one endpoint is required

Exemplo:

constraint violation: [InvalidValue] constraints/generic_constraint_bounds.parquet (GenericConstraintBoundsRow[4]): GenericConstraintBoundsRow[4] on constraint 3 has neither bound_lower nor bound_upper: at least one endpoint is required

Solução: Forneça bound_lower e/ou bound_upper na linha, ou adicione um operador relacional embutido (<=, >=, ==) à expression da restrição, para que um resto afim preencha o extremo ausente. Veja Restrições genéricas — a grade de ativação.

Quando ocorre: constraints/hydro_bounds.parquet pode sobrescrever o min_diversion_m3s e o max_diversion_m3s de uma hidrelétrica por (hydro, stage) ou por patamar. Quando a hidrelétrica não declara canal diversion, sua vazão desviada é fixada em [0, 0]. Um piso positivo resultaria no intervalo inviável [min > 0, 0], e um teto positivo desviaria água que nenhuma usina recebe. A verificação de regras de negócio rejeita ambas as sobrescritas antes que cheguem ao PL, com um apontamento por campo.

Campos:

CampoDescrição
descriptionContém uma linha [InvalidValue] constraints/hydro_bounds.parquet (Hydro <id>): Hydro <id>: hydro_bounds row at stage_id=<stage>[ block_id=<block>] sets <field>=<value>, but the hydro declares no diversion channel; without a channel the diversion column is [0, 0], em que <field> é min_diversion_m3s ou max_diversion_m3s

Exemplo:

[InvalidValue] constraints/hydro_bounds.parquet (Hydro 0): Hydro 0: hydro_bounds row at stage_id=1 sets max_diversion_m3s=25, but the hydro declares no diversion channel; without a channel the diversion column is [0, 0]

Solução: Declare um canal diversion na hidrelétrica em system/hydros.json (veja Visão geral da modelagem dos elementos do sistema) ou remova a sobrescrita positiva de min_diversion_m3s ou max_diversion_m3s para aquele (hydro, stage) em constraints/hydro_bounds.parquet.

Limites de armazenamento por estágio recusados na carga

Seção intitulada “Limites de armazenamento por estágio recusados na carga”

Quando ocorre: constraints/hydro_bounds.parquet define um limite de armazenamento fora da faixa do reservatório, ou deixa um estágio do estudo cujo armazenamento mínimo excede o máximo:

  • O max_storage_hm3 de uma linha fica acima do max_storage_hm3 do reservatório em system/hydros.json, ou seu min_storage_hm3 fica abaixo do min_storage_hm3 do reservatório (o volume morto), além de uma tolerância relativa de 1e-9 (absoluta abaixo de 1 hm³). Cada coluna fora da faixa gera um apontamento, de modo que uma linha fora da faixa nos dois lados gera dois. Uma linha com um hydro_id que o caso não declara é reportada, em vez disso, como InvalidReference.
  • Em um estágio do estudo, o armazenamento mínimo em vigor excede o máximo em vigor. Cada limite em vigor é o valor da linha do estágio, senão o do próprio reservatório, de modo que duas linhas podem definir o mínimo e o máximo separadamente, e uma substituição pode cruzar o limite oposto do reservatório. Limites iguais são aceitos. Um único apontamento lista todos os pares (hidrelétrica, estágio). Um reservatório cujo próprio min_storage_hm3 excede seu max_storage_hm3 é recusado antes, como SchemaViolation de system/hydros.json.

Os modelos de geometria, de produção e de evaporação de uma hidrelétrica cobrem apenas a faixa do seu reservatório, de modo que os limites de armazenamento de um estágio devem ficar dentro dela.

Campos:

CampoDescrição
descriptionContém uma linha [InvalidValue] constraints/hydro_bounds.parquet (hydro_id=<id>, stage_id=<stage>): Hydro <id>: hydro_bounds row at stage_id=<stage>[, block_id=<block>] sets <column>=<value>, above the reservoir's <column> (<declared>) in system/hydros.json; a stage's storage bounds must lie within the reservoir's range, com below no lugar de above para min_storage_hm3, ou uma linha [InvalidValue] constraints/hydro_bounds.parquet: min_storage_hm3 exceeds max_storage_hm3 at <n> (hydro, stage) pair(s), so no storage satisfies those stages: <pairs>

Cada par é escrito Hydro <id> at stage <stage> (<min> > <max>), com os pares ordenados pelo id da hidrelétrica e depois pelo id do estágio, e unidos por , .

Exemplos:

[InvalidValue] constraints/hydro_bounds.parquet (hydro_id=0, stage_id=1): Hydro 0: hydro_bounds row at stage_id=1 sets max_storage_hm3=1200, above the reservoir's max_storage_hm3 (1000) in system/hydros.json; a stage's storage bounds must lie within the reservoir's range
[InvalidValue] constraints/hydro_bounds.parquet (hydro_id=0, stage_id=1): Hydro 0: hydro_bounds row at stage_id=1 sets min_storage_hm3=50, below the reservoir's min_storage_hm3 (100) in system/hydros.json; a stage's storage bounds must lie within the reservoir's range

No caso seguinte, o estágio 1 recebe o mínimo e o máximo de duas linhas, e o máximo do estágio 2 fica abaixo do mínimo do reservatório, de 100 hm³, que é o mínimo em vigor nesse estágio:

[InvalidValue] constraints/hydro_bounds.parquet: min_storage_hm3 exceeds max_storage_hm3 at 2 (hydro, stage) pair(s), so no storage satisfies those stages: Hydro 0 at stage 1 (600 > 400), Hydro 0 at stage 2 (100 > 50)

Solução: Mantenha o min_storage_hm3 e o max_storage_hm3 de cada estágio dentro da faixa de min_storage_hm3 a max_storage_hm3 do reservatório em system/hydros.json, ou corrija a faixa do reservatório quando for ela o valor errado. Em cada estágio listado, reduza o mínimo ou aumente o máximo em vigor. Veja constraints/hydro_bounds.parquet.

Quando ocorre: initial_conditions.json define o armazenamento de uma hidrelétrica fora de sua faixa ou no array que não corresponde à sua configuração de filling:

  • Um storage[].value_hm3 de uma hidrelétrica sem configuração de filling está fora da faixa [min_storage_hm3, max_storage_hm3] da própria hidrelétrica em system/hydros.json, além de uma tolerância relativa de 1e-9 (absoluta abaixo de 1 hm³). Uma hidrelétrica que entra em operação após o primeiro estágio também é verificada. O valor é recusado, nunca truncado. Uma hidrelétrica cujo min_storage_hm3 excede seu max_storage_hm3 reporta, em vez disso, aquele SchemaViolation.
  • Uma hidrelétrica com configuração de filling está listada em storage, ou uma hidrelétrica sem essa configuração está listada em filling_storage.

Os min_storage_hm3 e max_storage_hm3 por estágio de constraints/hydro_bounds.parquet limitam o final do seu estágio, e não o armazenamento inicial; um valor inicial fora dos limites do primeiro estágio de operação da hidrelétrica gera o aviso ModelQuality, e não um erro.

Campos:

CampoDescrição
descriptionContém uma linha [InvalidValue] initial_conditions.json (Hydro <id>): Hydro <id>: initial storage (<value>) must lie in [min_storage_hm3, max_storage_hm3] = [<min>, <max>] para um valor fora da faixa, ou Hydro <id>: has a filling configuration, so its initial storage belongs in filling_storage, not storage ou Hydro <id>: has no filling configuration, so its initial storage belongs in storage, not filling_storage para o array errado

Exemplo:

[InvalidValue] initial_conditions.json (Hydro 0): Hydro 0: initial storage (1200) must lie in [min_storage_hm3, max_storage_hm3] = [0, 1000]

Solução: Defina o valor dentro da faixa [min_storage_hm3, max_storage_hm3] da hidrelétrica, ou mova a entrada para filling_storage, no caso de uma hidrelétrica com configuração de filling, e para storage, no caso de uma sem ela. Veja Arquivos de condições iniciais.


Severidade: Erro

Quando ocorre: Um grafo direcionado que deve ser acíclico contém um ciclo. Dois grafos são verificados. A cascata hidráulica: as ligações downstream_id entre usinas hidrelétricas devem formar uma floresta direcionada (sem ciclos), pois um ciclo significaria que a usina A deságua na usina B, que por sua vez deságua de volta na usina A. O grafo da política: os policy_graph.nodes[] de stages.json, ligados por transitions[], devem ser acíclicos; esta verificação só se aplica quando nodes[] é declarado.

Mensagens:

[CycleDetected] system/hydros.json: hydro cascade contains a cycle involving hydro IDs: [0, 1]

A mensagem dos nós do grafo da política:

policy-graph nodes contain a cycle; the node graph must be acyclic

novomodelo validate a imprime como [CycleDetected] stages.json: <message>, em que <message> é o texto acima.

Solução: Revise a cadeia de downstream_id das usinas listadas e remova o ciclo. Toda cascata hidráulica deve ser uma árvore direcionada cujas raízes são usinas sem usina a jusante (descarga no canal de fuga). No grafo da política, remova a entrada de transitions[] que fecha o ciclo.


Severidade: Erro

Quando ocorre: Uma verificação de cobertura entre arquivos falha. Por exemplo, quando scenarios/inflow_seasonal_stats.parquet está presente, cada hidrelétrica precisa de uma linha para cada estágio do estudo em que está ativa, e cada par (hidrelétrica, estágio) ausente é um erro que nomeia a hidrelétrica e o estágio. Uma divergência significa que um arquivo opcional por entidade fornece dados para algumas entidades, mas não para todas as que os exigem. Quando system/fpha_hyperplanes.parquet contém alguma linha, toda usina configurada com o modelo fpha que tenha capacidade de turbinamento precisa de linhas próprias, qualquer que seja seu source, e uma usina sem elas é reportada como Hydro <id> is configured with FPHA model but has no FPHA hyperplanes.

Exemplo:

[DimensionMismatch] scenarios/inflow_seasonal_stats.parquet (Hydro 1): Hydro 1 missing inflow seasonal stats for stage 0

Solução: Adicione as linhas ausentes ao arquivo Parquet; a mensagem nomeia a hidrelétrica e o estágio sem linha. Quando esse arquivo está presente, cada hidrelétrica precisa de uma linha para cada estágio do estudo em que está ativa.


Severidade: Erro

Quando ocorre: É violada uma regra de negócio específica do domínio que não pode ser expressa como uma simples restrição de intervalo. Exemplos: um turbined_cost negativo em uma hidrelétrica cujo modelo de geração é fpha, um cronograma de enchimento de volume morto que não consegue atingir o volume morto antes da entrada em operação da hidrelétrica, as regras de térmica antecipada e de fronteira pós-estudo, uma linha de sobrescrita de limites que nomeia um stage_id não declarado, uma usina elevatória em serviço em um estágio em que sua hidrelétrica de origem ou de destino não está em operação (Operating), uma hidrelétrica com FPHA calculada cujos volumes em system/hydro_geometry.parquet não cobrem sua faixa de armazenamento, uma referência por patamar de restrição genérica que os patamares do estágio não conseguem satisfazer, ou um estágio que compartilha um season_id com estágios de outra duração e não é nem a janela inteira do período sazonal nem uma parte dela (stages.json). Uma verificação reporta um BusinessRuleViolation como aviso: quando o modelo de afluências é estimado a partir de scenarios/inflow_history.parquet e uma hidrelétrica tem mais de uma observação em um mesmo período sazonal de um ano, novomodelo validate imprime uma linha warning: (código de saída 0) informando que as observações são agregadas na resolução do período sazonal.

Exemplo:

error: [BusinessRuleViolation] penalties.json (Hydro 0): Hydro 0: turbined_cost (-0.05) must be non-negative (>= 0) for FPHA hydros; negative values distort LP dispatch

Solução: Leia a mensagem com atenção — ela descreve a regra específica violada e as entidades envolvidas. Para as duas regras de penalidade, veja Verificações de penalidades na carga.

Veja também: as entradas abaixo trazem as regras de térmica antecipada e de fronteira pós-estudo (Compromisso de despacho em térmica não antecipada, Janela de compromisso ausente em térmica antecipada, Fronteira pós-estudo desancorada ou malformada e Janela past_anticipated_commitments descoberta ou com cobertura excessiva), a regra de sobrescrita de limites com stage_id não declarado (stage_id não declarado em parquet de sobrescrita de limites) e as referências por patamar de restrição genérica (Referências por patamar de restrição genérica). A regra da usina elevatória está em Usina elevatória fora das janelas de operação de suas extremidades. A regra da geometria da FPHA calculada está em Geometria da FPHA calculada que não cobre a faixa de armazenamento. A regra da janela de estimação está em Anos do histórico de estimação fora do histórico. A regra do horizonte de Antecedência inválida de térmica antecipada também imprime uma linha [BusinessRuleViolation]; essa entrada fica sob SchemaViolation, onde são impressas duas de suas quatro linhas. As regras de volume do estágio das restrições genéricas estão em Restrições genéricas com volume do estágio.

Coluna determinística de afluência externa sob modelo autorregressivo

Seção intitulada “Coluna determinística de afluência externa sob modelo autorregressivo”

Quando ocorre: No esquema de amostragem de afluências external, a média e o desvio-padrão sazonais de uma afluência são substituídos pelos momentos amostrais de seu arquivo de cenários externos apenas para uma hidrelétrica de ordem autorregressiva 0 sem componente anual; uma hidrelétrica cujos arquivos declaram um coeficiente de defasagem ou um componente anual mantém as estatísticas declaradas em seus próprios arquivos. A substituição é feita por classe: uma classe de carga ou de fonte não despachável obtém seus momentos de seu arquivo externo apenas quando essa própria classe é external.

Uma coluna constante (σ = 0) é aceita para carga, NCS e uma hidrelétrica de ordem 0 sem componente anual, mas é rejeitada para uma hidrelétrica cujos arquivos declaram uma ordem autorregressiva acima de 0 ou um componente anual: um único valor determinístico não pode substituir tal modelo, pois teria de ser igual à própria saída PAR determinística do modelo, estágio a estágio, que o carregador não reconstrói a partir de uma coluna constante.

Campos:

CampoDescrição
descriptionContém uma linha [BusinessRuleViolation] <external inflow file> (inflow entity <e> stage <stage_id>): <message>

Exemplo:

constraint violation: [BusinessRuleViolation] scenarios/external_inflow_scenarios.parquet (inflow entity 7 stage 3): inflow external library at stage 3, entity 7: every scenario value is constant (σ = 0), but this hydro's inflow follows an autoregressive model of order > 0; a deterministic value here would have to equal that model's own deterministic PAR output at every stage, which this loader does not compute upstream

Solução: Dê à coluna externa uma variação real de estágio para estágio ou reduza o modelo autorregressivo de afluências da usina para ordem 0 (sem coeficiente de defasagem, sem componente anual), se sua afluência for de fato determinística. Veja Geração de cenários §4.4 para a regra de aceitação/rejeição e scenario_source para a configuração do esquema.

Parâmetros escalares fora do diretório de restrições

Seção intitulada “Parâmetros escalares fora do diretório de restrições”

Quando ocorre: Os parâmetros escalares são lidos apenas de constraints/generic_parameters.json, junto às restrições genéricas que referenciam seus parâmetros @name. Um arquivo em system/scalar_parameters.json é rejeitado qualquer que seja seu conteúdo; o carregador nunca o lê, de modo que mesmo um arquivo bem formado nesse caminho é recusado.

Campos:

CampoDescrição
descriptionContém uma linha [BusinessRuleViolation] system/scalar_parameters.json: system/scalar_parameters.json is no longer read; scalar parameters are now read from constraints/generic_parameters.json, beside the constraints that reference them by @name. Move the file (its contents are unchanged).

Exemplo:

[BusinessRuleViolation] system/scalar_parameters.json: system/scalar_parameters.json is no longer read; scalar parameters are now read from constraints/generic_parameters.json, beside the constraints that reference them by @name. Move the file (its contents are unchanged).

Solução: mkdir -p <case>/constraints && git mv <case>/system/scalar_parameters.json <case>/constraints/generic_parameters.json — o conteúdo não muda. Veja Restrições genéricas — os tipos de parâmetro para o esquema atual do arquivo.

Compromisso de despacho em térmica não antecipada

Seção intitulada “Compromisso de despacho em térmica não antecipada”

Quando ocorre: As entradas past_anticipated_commitments de initial_conditions.json declaram um compromisso de despacho decidido externamente para uma térmica antecipada, identificado por thermal_id. A validação do caso rejeita qualquer entrada cujo thermal_id não corresponda a uma térmica com anticipated_config — seja porque a térmica não existe, seja porque existe mas não está configurada como antecipada.

Campos:

CampoDescrição
descriptionContém uma linha [BusinessRuleViolation] initial_conditions.json (initial_conditions.past_anticipated_commitments[thermal_id=<id>]): Thermal <id>: referenced in past_anticipated_commitments but is not an anticipated thermal (anticipated_config is None or thermal does not exist)

Exemplo:

constraint violation: [BusinessRuleViolation] initial_conditions.json (initial_conditions.past_anticipated_commitments[thermal_id=12]): Thermal 12: referenced in past_anticipated_commitments but is not an anticipated thermal (anticipated_config is None or thermal does not exist)

Solução: Defina anticipated_config na térmica <id> em system/thermals.json ou remova/corrija o thermal_id na entrada past_anticipated_commitments problemática. Veja Visão geral da modelagem dos elementos do sistema §4 para a configuração de térmicas antecipadas e Formato do caso para o esquema de initial_conditions.json.

Janela de compromisso ausente em térmica antecipada

Seção intitulada “Janela de compromisso ausente em térmica antecipada”

Quando ocorre: Toda térmica com anticipated_config precisa de ao menos uma janela em past_anticipated_commitments de initial_conditions.json, identificada por thermal_id. A validação do caso rejeita uma térmica que não tenha nenhuma, tanto para antecedência dada em estágios quanto para antecedência dada em horas.

Campos:

CampoDescrição
descriptionContém uma linha [BusinessRuleViolation] initial_conditions.json (initial_conditions.past_anticipated_commitments): Thermal <id>: missing entry in initial_conditions.past_anticipated_commitments; every anticipated thermal must have at least one commitment window

Exemplo:

[BusinessRuleViolation] initial_conditions.json (initial_conditions.past_anticipated_commitments): Thermal 0: missing entry in initial_conditions.past_anticipated_commitments; every anticipated thermal must have at least one commitment window

Solução: Adicione uma janela para a térmica em past_anticipated_commitments (um compromisso de 0 MW é uma janela explícita) ou remova o anticipated_config da térmica. Veja Janela past_anticipated_commitments descoberta ou com cobertura excessiva para a cobertura que as janelas devem atingir e Formato do caso para o esquema de initial_conditions.json.

Quando ocorre: A verificação de regras de negócio valida post_study_stages.json — o calendário da fronteira pós-horizonte — e as entregas de térmicas antecipadas que recaem sobre ele. Várias falhas distintas são coletadas nessa única verificação. (Uma usina cuja antecedência é maior que todo o horizonte de estudo e não alcança nenhum estágio pós-estudo declarado é detectada antes, na validação de térmicas antecipadas, com uma mensagem system/thermals.json … the plant can never deliver within the study horizon (veja Antecedência inválida de térmica antecipada); para eliminá-la, reduza a antecedência ou declare um estágio pós-estudo que a antecedência alcance — veja Visão geral da modelagem dos elementos do sistema §4.) As falhas pós-estudo, associadas a post_study_stages.json:

  • O primeiro estágio do calendário pós-estudo não começa exatamente no final do horizonte de estudo.
  • Os estágios pós-estudo não são contíguos em datas (lacuna ou sobreposição entre estágios consecutivos).
  • O duration_hours de um estágio pós-estudo, arredondado para dias inteiros, resulta em duração não positiva.
  • Regra 1 — a antecedência de uma usina alcança um estágio pós-estudo sem célula thermal_bounds para seu (thermal_id, post_study_stage_index).
  • V2 — os compromissos de uma usina decididos antes do estudo e entregues após o horizonte não ladrilham os estágios pós-estudo que cobrem com cobertura 1.0.
  • V3 — uma janela de compromisso cobre um estágio pós-estudo que o próprio estudo decide (carried), ou um estágio além do alcance de decisão da usina.
  • V5 — um compromisso fixo não nulo cobre um estágio pós-estudo fora da janela de entrada em operação da usina.

Campos:

CampoDescrição
descriptionContém uma linha [BusinessRuleViolation] post_study_stages.json (...): <message> por falha — veja as mensagens abaixo

Exemplo:

constraint violation: [BusinessRuleViolation] post_study_stages.json (stages[0].start_date): first post-study stage starts 2026-09-08 but the study horizon ends 2026-09-05; the post-study calendar must begin exactly at the study horizon end.
constraint violation: [BusinessRuleViolation] post_study_stages.json (stages start_date=2026-10-01): post-study stages are not date-contiguous: the stage starting 2026-09-05 ends 2026-09-28 but the next stage starts 2026-10-01; each stage must end exactly where the next begins.
constraint violation: [BusinessRuleViolation] post_study_stages.json (thermals[id=12].anticipated_config): Thermal 12: anticipated lead reaches post-study stage index 0, but post_study_stages.json has no thermal_bounds entry for (thermal_id 12, post_study_stage_index 0).
constraint violation: [BusinessRuleViolation] post_study_stages.json (thermals[id=12].anticipated_config): Thermal 12: past_anticipated_commitments do not tile post-study stage index(es) [0] at coverage 1.0; declare the fixed commitment for each (a committed 0 MW is explicit).
constraint violation: [BusinessRuleViolation] post_study_stages.json (thermals[id=12].anticipated_config): Thermal 12: past_anticipated_commitments cover post-study stage index(es) [1], which the study itself decides; a declared fixed value there contradicts the study's own decision. Remove the window, or lengthen anticipated_config's lead so the delivery becomes pre-study-decided.
constraint violation: [BusinessRuleViolation] post_study_stages.json (thermals[id=12].anticipated_config): Thermal 12: past_anticipated_commitments cover post-study stage index(es) [2], which are past the plant's decision reach and cannot be represented. Remove the window, or shorten anticipated_config's lead so the delivery falls inside the reach.
constraint violation: [BusinessRuleViolation] post_study_stages.json (thermals[id=12].anticipated_config): Thermal 12: past_anticipated_commitments window [2026-10-01, 2026-11-01) value_mw = 120 covers post-study stage index 0, which is outside the plant's commissioning window [entry=Some(0), exit=Some(6)); the plant is not in service for this stage and the fixed commitment cannot be delivered. Declare a zero commitment at this stage, or widen the commissioning window.

Solução: Declare post_study_stages.json com o primeiro estágio começando exatamente no final do horizonte de estudo e cada estágio contíguo em datas com o seguinte. Adicione uma célula thermal_bounds para cada (thermal_id, post_study_stage_index) alcançado pela antecedência decidida dentro do estudo de uma usina. Ladrilhe, com cobertura 1.0, todo estágio pós-estudo coberto por uma janela past_anticipated_commitments de um compromisso decidido antes do estudo, sem nunca cobrir um estágio decidido pelo estudo ou além do alcance da usina, e mantenha todo compromisso fixo não nulo dentro da janela de entrada em operação da usina. Veja Fronteira pós-estudo e estudos encadeados para o modelo de fronteira e Formato do caso para o esquema de post_study_stages.json.

Janela past_anticipated_commitments descoberta ou com cobertura excessiva

Seção intitulada “Janela past_anticipated_commitments descoberta ou com cobertura excessiva”

Quando ocorre: As janelas past_anticipated_commitments de uma térmica antecipada devem ladrilhar exatamente os estágios de entrega dentro do estudo que a usina decidiu antes do estudo — cada um desses estágios coberto com fração 1.0 — e nunca um estágio que o próprio estudo decide. A verificação de regras de negócio reporta uma lacuna (um estágio inicial descoberto), um excesso de alcance (uma janela que cobre um estágio decidido pelo estudo) e um cruzamento do horizonte (uma única janela que atravessa o final do horizonte) como diagnósticos separados; cada um pode ocorrer de forma independente. Uma janela pode legitimamente se estender além do horizonte (um compromisso decidido antes do estudo e entregue após o horizonte; para o termo equivalente em outras ferramentas de planejamento, veja o Glossário) — essa cobertura pós-estudo é validada separadamente, em Fronteira pós-estudo, acima.

Campos:

CampoDescrição
descriptionContém uma linha [BusinessRuleViolation] initial_conditions.json (thermals[id=<id>].anticipated_config): <message> — veja as mensagens abaixo

Exemplo:

constraint violation: [BusinessRuleViolation] initial_conditions.json (thermals[id=7].anticipated_config): Thermal 7: past_anticipated_commitments do not tile the leading 2 delivery stage(s) at coverage 1.0; study stage id(s) [0] are not covered exactly once. Write a commitment window (a committed 0 MW is explicit) for every leading delivery stage.
constraint violation: [BusinessRuleViolation] initial_conditions.json (thermals[id=7].anticipated_config): Thermal 7: past_anticipated_commitments cover study stage id(s) [3] beyond the leading 2 calendar-derived delivery stage(s); a commitment window may not cover a study stage the study itself decides. Shorten the plant's anticipated_config lead so its window stays within the leading 2 delivery stage(s).
constraint violation: [BusinessRuleViolation] initial_conditions.json (thermals[id=7].anticipated_config): Thermal 7: past_anticipated_commitments window [2026-08-15, 2026-09-15) straddles the study horizon end (2026-09-01); a single window may not cover both in-study and post-study delivery. Declare two windows split at the horizon instead: one ending at 2026-09-01 for the in-study coverage, one starting at 2026-09-01 for the post-study coverage.

Solução: Escreva uma janela de compromisso para cada estágio de entrega dentro do estudo que a usina decidiu antes do estudo (um compromisso de 0 MW é uma janela legítima e explícita — não uma omissão), sem nunca cobrir um estágio que o próprio estudo decide (encerre a janela antes ou aumente a antecedência do anticipated_config da usina, se esse estágio for de fato decidido antes do estudo), e divida no final do horizonte qualquer janela que o atravesse. Esses são os estágios de entrega dentro do estudo cuja decisão ocorre antes do primeiro estágio do estudo: os primeiros lead_stages estágios ou, para lead_time_hours, todo estágio cujo instante de decisão — uma antecedência antes do final do estágio — seja anterior ou igual ao início do estudo. Veja Visão geral da modelagem dos elementos do sistema §4.

stage_id não declarado em parquet de sobrescrita de limites

Seção intitulada “stage_id não declarado em parquet de sobrescrita de limites”

Quando ocorre: Uma linha em constraints/{thermal,hydro,line,pumping,contract,hydro_unit_group}_bounds.parquet cujo stage_id não é um estágio do estudo declarado (pertinência aos ids declarados em stages.json, que podem ter lacunas ou começar em 1) é rejeitada em novomodelo validate como BusinessRuleViolation; uma linha de constraints/ncs_bounds.parquet é rejeitada como InvalidReference com NcsBoundsRow[i] has invalid stage_id N (not a valid study stage). Linhas em constraints/generic_constraint_bounds.parquet e constraints/penalty_overrides_*.parquet com stage_id não declarado não são rejeitadas e não têm efeito.

Campos:

CampoDescrição
descriptionUma linha [BusinessRuleViolation] constraints/{family}_bounds.parquet (...): ... por linha rejeitada, para as seis famílias, ou uma linha [InvalidReference] constraints/ncs_bounds.parquet: NcsBoundsRow[i] has invalid stage_id N ... para NCS

Exemplo:

error: [BusinessRuleViolation] constraints/hydro_bounds.parquet (hydro_id=0, stage_id=15): Hydro 0: hydro_bounds override names stage_id=15, which is not a declared study stage

Solução: Corrija o valor de stage_id para que corresponda a um dos IDs de estágio declarados em stages.json. Em caso de erro de digitação (por exemplo, 15 em vez de 5), corrija a linha; em caso de sobrescrita obsoleta que referencia um estágio removido, exclua a linha ou atualize a declaração dos estágios.

Quando ocorre: Um termo de restrição genérica nomeia um patamar que seu estágio não pode expor. A verificação só é executada para um par (restrição, estágio) que tenha uma linha em constraints/generic_constraint_bounds.parquet. Uma referência de evaporação é um termo hydro_evaporation; uma referência de armazenamento é um termo hydro_storage_initial, hydro_storage_final, hydro_useful_volume_initial ou hydro_useful_volume_final. Sendo K o número de patamares que o estágio declara, a verificação rejeita quatro condições:

  • Um índice de patamar igual ou maior que K em uma referência de evaporação ou de armazenamento, em qualquer estágio.
  • Uma referência de evaporação a um patamar de 1 a K - 1 em um estágio paralelo com K > 1.
  • Uma referência de evaporação sem patamar em um estágio cronológico com K > 1.
  • Uma referência de armazenamento a uma fronteira interna entre patamares, isto é, uma fronteira entre dois patamares, em um estágio paralelo com K > 1.

As regras estão enunciadas em Referências a patamares de hydro_evaporation.

Tipo, arquivo, entidade: BusinessRuleViolation, constraints/generic_constraints.json e a entidade constraint[id=N], em que N é o id da restrição.

Mensagens: novomodelo validate imprime uma linha error: por rejeição. As cinco linhas abaixo mostram uma mensagem por modelo, nesta ordem:

  1. Um patamar de evaporação igual ou maior que K.
  2. Um patamar de evaporação de 1 a K - 1 em um estágio paralelo.
  3. Uma fronteira interna de armazenamento em um estágio paralelo.
  4. Um patamar de armazenamento igual ou maior que K.
  5. Uma referência de evaporação sem patamar em um estágio cronológico.
error: [BusinessRuleViolation] constraints/generic_constraints.json (constraint[id=0]): Constraint "evap_out_of_range": per-block evaporation reference `hydro_evaporation(0, 5)` at stage 0 references block 5 which does not exist at stage 0 (K = 2)
error: [BusinessRuleViolation] constraints/generic_constraints.json (constraint[id=1]): Constraint "evap_parallel_block": per-block evaporation reference `hydro_evaporation(0, 1)` at stage 0 names block 1, past the stage-level evaporation, which requires chronological block mode (stage 0 is parallel with 2 blocks); use block 0 or no block
error: [BusinessRuleViolation] constraints/generic_constraints.json (constraint[id=2]): Constraint "storage_interior": per-block storage reference `hydro_storage_final(0, 0)` at stage 0 resolves to an interior boundary, which requires chronological block mode (stage 0 is parallel with 2 blocks)
error: [BusinessRuleViolation] constraints/generic_constraints.json (constraint[id=3]): Constraint "storage_out_of_range": per-block storage reference `hydro_storage_initial(0, 5)` at stage 0 references block 5 which does not exist at stage 0 (K = 2)
error: [BusinessRuleViolation] constraints/generic_constraints.json (constraint[id=4]): Constraint "evap_chronological_bare": stage-level `hydro_evaporation(0)` at chronological stage 1 is ambiguous — evaporation is per-block there (K = 2); name a block, e.g. `hydro_evaporation(0, 0)`

Cada mensagem por patamar cita o termo completo accessor(hydro, block); a mensagem de ambiguidade no nível do estágio cita accessor(hydro) e sugere um termo com patamar.

Solução: Nomeie um patamar que exista no estágio: os índices de patamar vão de 0 a K - 1. Em um estágio paralelo, referencie a evaporação com o patamar 0 ou sem patamar, e referencie o armazenamento apenas no início ou no final do estágio: patamar 0 ou nenhum patamar para uma referência inicial, o último patamar ou nenhum patamar para uma referência final. Para referenciar grandezas por patamar, defina block_mode como "chronological" no estágio em stages.json; um estágio cronológico exige um patamar nomeado para a evaporação, como em hydro_evaporation(<hydro>, 0).

Quando ocorre: Uma restrição genérica com um termo hydro_outflow_volume, hydro_diversion_volume ou pumping_volume é uma única linha no nível do estágio; por isso, a verificação recusa três coisas nela:

  • um termo que não é um volume do estágio, hydro_storage, nem um termo hydro_storage_initial, hydro_storage_final, hydro_useful_volume_initial ou hydro_useful_volume_final sem argumento de patamar, esteja ele escrito na expressão ou trazido por uma expressão nomeada;
  • um parâmetro per_stage_block lido por um coeficiente ou limite, diretamente ou por meio de parâmetros expression;
  • uma linha da restrição em constraints/generic_constraint_bounds.parquet com block_id.

As regras estão enunciadas em Volumes do estágio.

Tipo, arquivo, entidade: BusinessRuleViolation. A recusa de um termo ou de um parâmetro informa constraints/generic_constraints.json e a entidade constraint[id=N], em que N é o id da restrição, tenha a restrição linhas de limites ou não. A recusa de uma linha de limites informa constraints/generic_constraint_bounds.parquet e a entidade constraint_id=N, stage_id=S da linha.

Mensagens: novomodelo validate imprime uma linha error: por termo, parâmetro e linha de limites recusados. Um termo trazido por uma expressão nomeada é citado com (from @name) depois dele, nomeando cada expressão nomeada cujo próprio corpo escreve o termo. As três linhas abaixo mostram uma recusa de cada tipo, na ordem acima.

error: [BusinessRuleViolation] constraints/generic_constraints.json (constraint[id=1]): Constraint "release_vs_flow": `hydro_turbined(1)` cannot appear beside a stage-volume term; such a constraint takes only stage volumes, hydro_storage, and hydro_storage_* or hydro_useful_volume_* without a block argument
error: [BusinessRuleViolation] constraints/generic_constraints.json (constraint[id=2]): Constraint "release_cap": parameter `@cap` is per_stage_block; a constraint with a stage-volume term takes no coefficient or bound that varies by block
error: [BusinessRuleViolation] constraints/generic_constraint_bounds.parquet (constraint_id=3, stage_id=0): Constraint "diverted_cap": the bounds row at stage_id=0 has block_id=0; a constraint with a stage-volume term takes one row per stage with a null block_id

Solução: Restrinja uma restrição com volume do estágio a volumes do estágio e ao armazenamento no nível do estágio: escreva uma vazão, uma geração ou outra grandeza por patamar como uma restrição própria, ou como o seu volume do estágio, quando houver um; substitua um parâmetro per_stage_block por um per_stage; e defina como nulo o block_id de cada linha de limites.

Usina elevatória fora das janelas de operação de suas extremidades

Seção intitulada “Usina elevatória fora das janelas de operação de suas extremidades”

Quando ocorre: Uma usina elevatória em system/pumping_stations.json está em serviço em um estágio em que sua hidrelétrica de origem ou de destino não está em operação: antes do entry_stage_id dessa hidrelétrica, a partir de seu exit_stage_id, ou enquanto ela está em fase de enchimento (Filling). É impressa uma linha para cada extremidade problemática, nomeando o primeiro estágio nessa situação.

PumpingStation {id}: active at stage {stage_id} while its {side} hydro {hid} is not Operating there (before entry_stage_id, at or after exit_stage_id, or Filling); a pumping station may operate only inside both endpoints' Operating windows

{side} é source ou destination. A linha é impressa como [BusinessRuleViolation] system/pumping_stations.json (PumpingStation {id}): <message>.

Solução: Mantenha a usina elevatória em serviço apenas nos estágios em que ambas as hidrelétricas estejam em operação: ajuste o entry_stage_id e o exit_stage_id da usina elevatória ou os das hidrelétricas.

Geometria da FPHA calculada que não cobre a faixa de armazenamento

Seção intitulada “Geometria da FPHA calculada que não cobre a faixa de armazenamento”

Quando ocorre: Uma hidrelétrica cuja configuração de modelo de produção tem uma entrada source: "computed" tem linhas em system/hydro_geometry.parquet, e a faixa de volumes dessas linhas não cobre a faixa de armazenamento da hidrelétrica, de min_storage_hm3 a max_storage_hm3. Os planos da FPHA calculada são ajustados sobre essa faixa de armazenamento. Uma hidrelétrica sem nenhuma linha no arquivo fica a cargo da regra de cobertura de geometria da tabela de validação.

{entity}: the hydro_geometry.parquet volume range [{geometry_min}, {geometry_max}] hm³ does not cover its storage range [{min}, {max}] hm³, over which its computed FPHA planes are fitted; extend the geometry to cover it

{entity} é Hydro {name} (id={id}). A linha é impressa como [BusinessRuleViolation] system/hydro_geometry.parquet ({entity}): <message>.

Solução: Estenda a geometria em system/hydro_geometry.parquet para cobrir de min_storage_hm3 a max_storage_hm3 ou corrija a faixa de armazenamento da hidrelétrica.

Anos do histórico de estimação fora do histórico

Seção intitulada “Anos do histórico de estimação fora do histórico”

Quando ocorre: A execução estima o modelo de afluências a partir de scenarios/inflow_history.parquet (o caso não fornece ao mesmo tempo scenarios/inflow_seasonal_stats.parquet e scenarios/inflow_ar_coefficients.parquet), e estimation.history_years começa antes do primeiro ano ou termina depois do último ano do arquivo. Os anos do arquivo são os anos de início de suas linhas, considerando todas as hidrelétricas. Um caso que não estima nada a partir do histórico não é verificado.

estimation.history_years ({from} to {to}) reaches outside the years of scenarios/inflow_history.parquet ({first} to {last}); narrow the range to those years

A linha é impressa como [BusinessRuleViolation] config.json: <message>.

Solução: Restrinja estimation.history_years aos anos que o arquivo contém, ou estenda o arquivo; veja Configuração — estimation.


novomodelo validate reporta como phase uma carga recusada com policy.mode = "warm_start" em uma execução que treina, com a mensagem rotulada <output dir>/<policy.path>: , e encerra com código 1; um checkpoint cuja leitura o sistema operacional recusa reporta IoError e encerra com código 2. O mesmo tipo traz os avisos da carga, que encerram com código 0: Bases armazenadas não utilizadas, entity manifest absent (source slots: {n}, current slots: {m}); slot identity could not be verified, relying on state_dimension alone e slot {i} (entity_type={entity_type}, entity_id={entity_id}, subindex={subindex}) was dormant in the source policy but is active in the current study; loading its cut. Erros de carga da política apresenta as mensagens de recusa.


novomodelo validate reporta como phase uma carga recusada com policy.mode = "resume" em uma execução que treina, com a mensagem rotulada <output dir>/<policy.path>: , e encerra com código 1; um checkpoint cuja leitura o sistema operacional recusa reporta IoError e encerra com código 2. O mesmo tipo traz os avisos da carga, que encerram com código 0: Bases armazenadas não utilizadas, entity manifest absent (source slots: {n}, current slots: {m}); slot identity could not be verified, relying on state_dimension alone e slot {i} (entity_type={entity_type}, entity_id={entity_id}, subindex={subindex}) was dormant in the source policy but is active in the current study; loading its cut. Erros de carga da política apresenta as mensagens de recusa.

Uma carga da FCF completa só usa uma base de PL armazenada quando ela se ajusta ao PL do seu estágio (Gerenciamento da política — Filtro de bases armazenadas enuncia a regra); as demais são descartadas com um único aviso, e a carga prossegue:

warning: stored bases not used: {n} of {m} do not fit the current LP (first: node {node}, {reason}); a stored basis is used only when its column count equals the LP's, its row count equals the LP's template rows plus its recorded cut rows, its basic count equals its row count, and every recorded cut-row slot holds a loaded cut; the policy was trained on a different LP

{n} e {m} contam bases armazenadas, uma por nó e cenário da simulação forward, e {node} é o nó da primeira que não se ajusta, por posição do nó e depois por cenário. {reason} é um de {found} columns, the LP has {expected}, {found} rows, the LP expects {expected}, {found} basic entries for {expected} rows ou a cut row at slot {slot}, which holds no loaded cut.

novomodelo run o imprime como warning: {message} no stderr (--quiet o oculta); novomodelo validate imprime warning: <output dir>/<policy.path>: {message}, e --json fornece a contagem em policy_load.unused_stored_bases. O Python imprime novomodelo-python: policy validation warning: {message}. O código de saída não é afetado.

novomodelo validate reporta como phase uma carga recusada de uma execução somente de simulação (training.enabled = false com cenários de simulação), qualquer que seja policy.mode, com a mensagem rotulada <output dir>/<policy.path>: , e encerra com código 1; um checkpoint cuja leitura o sistema operacional recusa reporta IoError e encerra com código 2. O mesmo tipo traz os avisos da carga, que encerram com código 0: Bases armazenadas não utilizadas e os dois avisos de manifesto de entidades citados em WarmStartIncompatible. Erros de carga da política apresenta as mensagens de recusa. Por exemplo, uma execução somente de simulação sem checkpoint em policy.path reporta:

<output dir>/<policy.path>: Policy directory not found: <output dir>/<policy.path>. Cannot run simulation-only mode without a trained policy.

Severidade: Erro

Quando ocorre: Duas ou mais hidrelétricas que declaram um travel_time_hours positivo alimentam a mesma usina a jusante com valores que diferem em mais de 1e-9, e ao menos um estágio do estudo em stages.json usa block_mode "chronological". A verificação rejeita o caso sempre que algum estágio do estudo é cronológico, e não apenas nos estágios em que a temporização dos arcos seria diferente. Emitido pela verificação de regras de negócio, com uma linha para cada usina a jusante afetada, em system/hydros.json.

Exemplo:

Hydro {downstream_id}: chronological confluence with heterogeneous travel times is unsupported in v1 — {n} declared arcs feed this downstream plant with differing travel_time_hours ({arcs}); align the arcs' travel_time_hours or keep every study stage in Parallel mode

{downstream_id} é o id da usina a jusante, {n} é o número de arcos que a alimentam e {arcs} lista esses arcos como itens hydro {id} (travel_time_hours={t}) separados por vírgula.

Solução: Atribua o mesmo travel_time_hours a todos os arcos que chegam a essa usina a jusante em system/hydros.json ou defina block_mode como "parallel" em todos os estágios do estudo em stages.json.


Severidade: Aviso (não bloqueia a execução)

Quando ocorre: Um termo contract_import ou contract_export de uma restrição genérica nomeia um id de contrato que system/energy_contracts.json não declara. O termo não tem efeito e o caso ainda é carregado. O aviso alerta o usuário para um possível erro de entrada.

Exemplo:

{label} references Contract {id} which is a stub entity with no LP effect

{label} é GenericConstraint N term[M], que nomeia o id da restrição e a posição do termo em sua expressão, a partir de zero; {id} é o id do contrato não declarado.

Solução: Corrija o id do contrato no termo ou declare esse contrato em system/energy_contracts.json. Se o termo for intencional, este aviso pode ser ignorado.


Severidade: Aviso (não bloqueia a execução)

Quando ocorre: É detectado um problema no modelo de entrada que mantém o caso válido. Exemplos: uma ordenação de penalidades invertida, um preço da FPHA menor ou igual ao maior custo de déficit mais o preço de geração mínima, o estado de tendência hidrológica desabilitado em todos os estágios do estudo apesar de terem sido fornecidos coeficientes autorregressivos, um valor negativo em scenarios/inflow_history.parquet, um período sazonal sem nenhuma das amostras desse arquivo a partir das quais a estimação faz o ajuste, um par hidrelétrica-período sazonal com pelo menos uma, mas menos de estimation.min_observations_per_season, ocorrências do período sazonal totalmente cobertas nesse arquivo, um alerta sobre o travel_time_hours declarado de uma hidrelétrica, um piso rígido de armazenamento que sobe acima do piso deixado pelo estágio anterior, um plano da FPHA pré-calculado que fica abaixo de 0 MW com vazão turbinada nula, ou um armazenamento inicial fora dos limites de armazenamento ao final do primeiro estágio de operação da hidrelétrica. Cada um é reportado como aviso.

Exemplo:

warning: penalties.json: Penalty ordering violation: max(deficit_segment_costs) (7500) should be > generation_violation_below_cost (10000) (both $/MWh) -- 1 hydro(s) affected, worst case: Hydro 0

Os avisos de ordenação de custos começam com Penalty ordering violation:, e o aviso do preço da FPHA começa com FPHA price ordering violation:. As quatro mensagens são citadas em Verificações de penalidades na carga.

A mensagem de tendência hidrológica:

inflow lags are disabled on all study stages (state_variables.inflow_lags = false) despite a PAR(p>0) inflow model (AR order {max_order}), so the inflow-lag dimensions are omitted from the per-stage state. This is a valid configuration for external-solver interoperability; otherwise it is likely a misconfiguration

{max_order} é substituído pela ordem do modelo AR quando o aviso é emitido. Quando ele ocorre e o que altera: stages[].state_variables — Projeção de Cortes.

A mensagem de contagem de observações:

hydro {hid} season {sid} has {n} observations (minimum recommended: {min_obs}); estimation accuracy may be insufficient with so few observations

{min_obs} é estimation.min_observations_per_season. novomodelo validate reporta o aviso apenas quando o modelo de afluências é estimado a partir de scenarios/inflow_history.parquet (isto é, quando o caso não fornece ao mesmo tempo scenarios/inflow_seasonal_stats.parquet e scenarios/inflow_ar_coefficients.parquet) e stages.json declara season_definitions. {n} conta as ocorrências do período sazonal totalmente cobertas a partir das quais a estimação faz o ajuste, dentro ou fora do horizonte do estudo; com estimation.history_years definido, apenas as que começam em seus anos.

As mensagens de armazenamento inicial, reportadas em initial_conditions.json para a hidrelétrica:

Hydro {id}: initial storage ({value}) lies below the minimum storage ({min}) at the end of stage {stage_id}, its first operating stage; that stage must reach it from its own inflow
Hydro {id}: initial storage ({value}) lies above the maximum storage ({max}) at the end of stage {stage_id}, its first operating stage; that stage must release the excess

O primeiro estágio de operação é o primeiro estágio do estudo dentro da janela de entrada em operação da hidrelétrica. Seus limites são a linha no nível do estágio (block_id nulo) de constraints/hydro_bounds.parquet para essa hidrelétrica e esse estágio ou, na ausência dela, os min_storage_hm3 e max_storage_hm3 da própria hidrelétrica. Uma hidrelétrica com configuração de filling não é verificada. O armazenamento inicial é mantido como declarado.

A mensagem de piso crescente, reportada em constraints/hydro_bounds.parquet:

Minimum storage rises above the previous stage's floor at {} (hydro, stage) pair(s), so a stage whose inflow cannot cover the rise is infeasible: {pairs}

Cada par é escrito como Hydro {hydro_id} at stage {stage_id} ({floor} > {incoming}). Os pares são ordenados pelo id da hidrelétrica e, depois, pelo id do estágio, e unidos por , . A verificação é executada sob os métodos de afluência truncation, truncation_with_penalty e none e é silenciosa sob penalty. O piso rígido é 0 para uma hidrelétrica em fase de enchimento e em um estágio em pré-enchimento e, nos demais casos, o min_storage_hm3 resolvido do estágio. O estágio que recebe o armazenamento inicial fica a cargo da mensagem de armazenamento inicial.

A mensagem do plano pré-calculado, reportada em system/fpha_hyperplanes.parquet para a hidrelétrica:

FPHA plane below zero at zero turbining: {entity} -- {n_pairs} (stage, plane) pair(s) at stages {stages} fall below 0 MW with no turbined flow; the earliest crosses 0 MW at {s_star} m³/s of spillage (stage {stage_id}, plane {plane_id}, storage {v_min} hm³, spillage up to {s_ref} m³/s), so while it spills the hydro turbines water at 0 MW, or reports fpha_violation_mw where turbining cannot lift the plane to 0 MW

A verificação ignora uma hidrelétrica sem entrada de FPHA, uma hidrelétrica cuja FPHA é calculada (source: "computed") e uma hidrelétrica sem capacidade de turbinamento. Ela cobre cada estágio do estudo cuja entrada resolve para fpha, e um estágio usa as linhas com o seu próprio stage_id ou, na falta delas, as linhas válidas para todos os estágios (stage_id nulo). Ela avalia cada linha com vazão turbinada nula, no armazenamento mínimo da janela de ajuste e no extremo superior da faixa de ajuste do vertimento (spillage_fit_max_m3s, ou o seu padrão), com kappa multiplicando apenas gamma_0. {s_star} é o vertimento no qual o plano atinge 0 MW, (kappa·gamma_0 + gamma_v·v_min)/|gamma_s| quando essa soma é positiva e 0 caso contrário. O primeiro cruzamento é o menor {s_star}, com empates desfeitos pelo id do estágio e, depois, pelo id do plano. {stages} lista os ids dos estágios sinalizados como sequências crescentes escritas a-b (ou um id isolado) e unidas por , . É reportado um aviso por hidrelétrica.

Solução: Revise a entrada sinalizada. Para um aviso de ordenação de penalidades, veja Verificações de penalidades na carga; para o aviso de tendência hidrológica, veja stages[].state_variables — Projeção de Cortes; para o aviso de armazenamento inicial, verifique se o primeiro estágio de operação consegue atingir seus limites de armazenamento ou mova o armazenamento inicial para dentro deles; para o aviso de piso crescente, reduza o piso que sobe, eleve o piso do estágio anterior ou use o método de afluência penalty (veja a precondição de recurso completo); para o aviso do plano pré-calculado, eleve o gamma_s do plano sinalizado para pelo menos −(kappa·gamma_0 + gamma_v·v_min)/S_ref, com o armazenamento v_min e o vertimento S_ref que a mensagem imprime, ou ajuste os planos a partir da geometria com source: "computed", cujos planos recebem esse limite (Secante de vazão lateral); um plano cujo cruzamento está em 0 m³/s precisa de um gamma_0 ou gamma_v maior. Avisos deste tipo não impedem a execução do solver.


Severidade: Aviso (não bloqueia a execução)

Quando ocorre: Uma construção válida cuja semântica é ambígua ou dependente do estágio de um modo que provavelmente surpreenderá o usuário. Duas construções o disparam, ambas emitidas pela verificação de regras de negócio em constraints/generic_constraints.json:

  1. thermal_generation(N) em uma térmica antecipada. Uso de thermal_generation(N) em uma restrição genérica quando a térmica N é uma térmica antecipada. thermal_generation refere-se à geração por patamar medida no estágio de entrega (quando o compromisso se concretiza), e não à decisão de compromisso tomada no estágio corrente. Quem pretende restringir o próprio compromisso deve usar anticipated_decision(N).

    Exemplo: Uma restrição genérica thermal_generation(0) em uma térmica antecipada:

    warning: constraints/generic_constraints.json (constraint[id=0]): Constraint "peak_cap": thermal_generation(0) references an anticipated thermal. thermal_generation refers to the per-block generation at the delivery stage, not the forward commitment. If you intend to constrain the commitment itself, use anticipated_decision(0) instead.

    Solução: Revise a expressão da restrição. Se o objetivo é limitar a geração despachada no estágio de entrega, thermal_generation(N) está correto e o aviso pode ser ignorado. Se o objetivo é limitar a própria decisão de compromisso antecipado, substitua thermal_generation(N) por anticipated_decision(N).

  2. Tags de energia armazenada que não se cancelariam. Uma restrição referencia tags calculadas — nos coeficientes da expressão, nos seus limites (um @emax no lado direito conta) ou por meio de um parâmetro expression que as lê — em uma de duas formas:

    • um teto max_stored_energy(h) junto a uma tag de produtibilidade da mesma hidrelétrica diferente de integrated_accumulated_productivity(h) (ou um teto max_stored_energy_mwh(h) junto a uma tag de produtibilidade em MWh diferente de integrated_accumulated_productivity_mwh_per_hm3(h)). As tags diferem em abrangência (uma usina ou sua cascata a jusante) ou em critério de avaliação (o ponto de referência da usina ou a média da faixa útil), de modo que uma comparação de energia armazenada construída com elas não se cancela. É emitido um aviso para cada par desse tipo.
    • tags em MWh (a família _mwh e _mwh_per_hm3) misturadas com tags brutas. As duas famílias diferem por um fator de 106/360010^6/3600; o aviso diz Constraint "<name>": mixes MWh tags (<tags>) with raw productivity tags (<tags>); the two units differ by a factor of 10^6/3600. Use one family throughout.

    O caso continua válido.

    Exemplo: Uma restrição que combina as duas tags para a hidrelétrica 0:

    warning: constraints/generic_constraints.json (sec_mismatch): Constraint "sec_mismatch": pairs max_stored_energy(0) with accumulated_productivity(0) for hydro 0; the two differ in scope or evaluator and would not cancel. The coefficient matching max_stored_energy is integrated_accumulated_productivity.

    Solução: Use integrated_accumulated_productivity como o coeficiente correspondente a max_stored_energy, ou integrated_accumulated_productivity_mwh_per_hm3 com max_stored_energy_mwh, e mantenha cada restrição em uma única família; veja o exemplo da curva de segurança.

O aviso é impresso por novomodelo validate em sua saída legível; a saída de sucesso de --json não traz avisos.


O valor de phase de novomodelo validate --json e o kind de uma entrada do array errors de novomodelo.io.validate (Python) nomeiam a falha que interrompeu a carga. Quase toda falha na carga do caso reporta ConstraintError, porque a carga reúne seus problemas em um único relatório. Os tipos estão listados abaixo na ordem das etapas da carga em que normalmente ocorrem: leitura de um arquivo, análise sintática, verificação de seus campos e, por fim, validação do caso inteiro.

Durante a carga de um caso, uma falha de leitura, análise ou esquema em um arquivo é coletada no relatório de validação, em vez de ser retornada isoladamente. Ela aparece como uma linha de um ConstraintError: [FileNotFound] para uma falha de leitura, [ParseError] <file>: parse error: <message> para uma falha de análise e [SchemaViolation] <file>: field <field>: <message> para uma falha de esquema. Os formatos de exibição abaixo só aparecem para um erro de carga gerado após a conclusão desse relatório, como uma recusa de policy.path gerada depois que o caso foi carregado; veja Códigos de saída.

Severidade: Erro

Quando ocorre: Um arquivo obrigatório consta do manifesto de arquivos, mas não pode ser lido do disco — arquivo não encontrado, permissão negada ou outra falha de E/S do sistema operacional. Ocorre quando um arquivo JSON ou Parquet é lido para análise e a leitura retorna um erro. Também é retornado quando um policy.path não pode ser inspecionado (código de saída 2).

Formato de exibição:

I/O error reading {path}: {source}

Campos:

CampoDescrição
pathCaminho do arquivo que não pôde ser lido
sourceErro de E/S subjacente do sistema operacional

Solução: Verifique se o arquivo existe no diretório do caso. Verifique se o processo tem permissão de leitura no diretório e no arquivo. Para uma carga completa do caso, a raiz do caso deve conter todos os arquivos obrigatórios (veja Formato do caso). Um problema coletado durante a carga de um caso é impresso como linha de relatório; veja Tipos de relatório de validação.


ParseError — veja ParseError; uma falha de análise coletada no relatório é impressa como uma linha [ParseError].


Severidade: Erro

Quando ocorre: Um arquivo é analisado com sucesso, mas um campo viola uma restrição do esquema: um campo obrigatório está ausente, um valor está fora do intervalo válido ou um discriminador de enum nomeia uma variante desconhecida. Ocorre durante a verificação dos campos de um arquivo já analisado. Também é retornado quando training.selection (que traz a quantidade de simulações forward) ou training.stopping_rules está ausente e a configuração é analisada ou mesclada fora de uma carga de caso (por exemplo, em sobrescritas de configuração via Python); uma carga de caso reporta a mesma ausência como uma linha SchemaViolation. Também é retornado para um policy.path que a execução recusa após a carga do caso (código de saída 1; veja Configuração — policy).

Formato de exibição:

schema error in {path}, field {field}: {message}

Campos:

CampoDescrição
pathCaminho do arquivo que contém a entrada inválida
fieldCaminho, separado por pontos, do campo problemático (por exemplo, "hydros[3].bus_id")
messageDescrição legível da violação

Solução: O valor de field identifica a posição exata do problema. Verifique se os campos obrigatórios estão presentes e se os valores estão dentro dos intervalos documentados. Um problema coletado durante a carga de um caso é impresso como linha de relatório; veja Tipos de relatório de validação.


Severidade: Erro

Quando ocorre: Categoria genérica para todos os diagnósticos de validação coletados em qualquer etapa de validação, para rejeições na montagem do sistema e para verificações feitas diretamente pelos carregadores após a montagem (por exemplo, uma escala de ruído derivada do fechamento e não finita é rejeitada aqui, com indicação da hidrelétrica e do período sazonal). O campo description contém todas as mensagens de erro coletadas, unidas por quebras de linha, cada uma prefixada com seu [<Kind>], o arquivo de origem, um identificador opcional de entidade e o texto da mensagem.

Formato de exibição:

constraint violation: {description}

Campos:

CampoDescrição
descriptionTodas as mensagens de erro, unidas por quebras de linha

Exemplo: A captura de falha em --json em Como esses erros chegam até você reporta ConstraintError como sua phase, com a linha de relatório coletada em message.

Solução: Leia todas as linhas de description — cada linha é um problema distinto. Corrija todos e execute novamente. O prefixo [<Kind>] identifica a categoria de cada problema, e a seção de cada tipo traz sua solução. Um problema coletado durante a carga de um caso é impresso como linha de relatório; veja Tipos de relatório de validação.


Os seis valores de phase abaixo aparecem apenas nas verificações de validação de novomodelo validate anteriores ao solver e não são tipos de LoadError. Eles aparecem no campo phase do erro de novomodelo validate --json quando uma verificação da fase de preparação falha antes da inicialização do solver.

Severidade: Erro

Quando ocorre: Uma falha de validação de config.json na fase de preparação da montagem do estudo, depois que a configuração foi analisada e antes do início da montagem do modelo estocástico. Rótulo de arquivo: config.json.

Exemplo: Uma regra de parada gap sem tolerance nem relative_tolerance:

config.json: configuration validation error: gap stopping rule requires at least one of tolerance / relative_tolerance to be present

training.cut_selection é verificado em três pontos. Um valor recusado pelo esquema imprime uma linha [ParseError] na carga do caso; uma regra entre dois de seus campos reporta ConfigValidationError; uma combinação com outra configuração reporta StudySetupError (ou BoundaryReconciliationError com policy.boundary configurado). Todos encerram com código 1. Configuração — training.cut_selection enuncia as regras.

ConfiguraçãoReportado comoMensagem
selection informado como array[ParseError]config.json: parse error: invalid type: sequence, expected internally tagged enum SelectionMethod
Um parâmetro de contagem definido como 0[ParseError]config.json: parse error: training.cut_selection.selection.check_frequency must be >= 1 (got 0), nomeando a chave definida como 0
method "lml1" ou "domination"[ParseError]config.json: parse error: the row-selection method `lml1` was removed: use `level1` (key `training.cut_selection.selection.method`)
tie_tolerance sob level1[ParseError]config.json: parse error: the key `tie_tolerance` was removed: `level1` compares row values exactly; delete the key (`training.cut_selection.selection`)
row_activity_tolerance null[ParseError]config.json: parse error: invalid type: null, expected f64
Um method com erro de grafia[SchemaViolation]config.json: field dynmic: unknown variant `dynmic`, expected `level1` or `dynamic`
lookback_iterations menor que check_frequencyConfigValidationErrorconfig.json: configuration validation error: cut_selection config error: cut_selection.lookback_iterations (2) must be >= cut_selection.check_frequency (5)
row_activity_tolerance negativoConfigValidationErrorconfig.json: configuration validation error: cut_selection config error: cut_selection.row_activity_tolerance must be finite and >= 0 (got -1)
violation_tolerance igual ou maior que 1ConfigValidationErrorconfig.json: configuration validation error: cut_selection config error: cut_selection.violation_tolerance must be < 1 (got 1)
violation_tolerance abaixo da tolerância de viabilidade primal de uma faseStudySetupErrorconfig.json: configuration validation error: training.cut_selection.selection.violation_tolerance (0.000000000001) is a relative factor and must be at least the primal feasibility tolerance of the backward solver profile (0.000000001); raise it, or omit it to use each phase's solver tolerance
max_active_per_stage com dynamicStudySetupErrorconfig.json: configuration validation error: training.cut_selection.max_active_per_stage is inadmissible with the dynamic cut selection method; a lazy solve takes its candidates from the active rows and dynamic runs no selection pass, so an evicted row never returns — remove the cap, or use the `level1` method

O método domination imprime seu próprio nome na mensagem de método removido. Duas combinações com um training.selection enumerado também reportam StudySetupError:

dynamic cut selection is inadmissible under enumerated forward traversal; the enumerated backward never solves lazily and records no binding activity, so the seed window of the enumerated forward's lazy solve would never advance past a cut's generating iteration — pair enumerated forwards with the `level1` method, or with no selection method
training.cut_selection.max_active_per_stage is inadmissible under enumerated forward traversal; enumerated traversal records no binding activity, so the cap would evict by generation order alone — remove the cap, or use sampled forward selection

Um limite abaixo de training.selection.forward_passes é aceito com um aviso, que novomodelo validate e novomodelo run registram no stderr como uma linha WARN, separada do relatório no stdout:

WARN max_active_per_stage (1) is less than forward_passes (4): in a stage whose row pool receives 4 rows per iteration, the cap evicts at every iteration every row this run added in an earlier iteration; rows loaded from a policy are not affected

Severidade: Erro

Quando ocorre: Uma falha durante a preparação do modelo estocástico — geração de cenários, montagem do modelo de afluências ou validação de cenários externos. Rótulo de arquivo: scenarios/inflow_history.parquet para um erro do modelo estocástico (após o rótulo, sua mensagem começa com stochastic error:) e scenarios/ para qualquer outra falha desta fase, como um erro de carga (após o rótulo, sua mensagem começa com I/O error:). O rótulo depende de como o erro é classificado, e não do arquivo a que ele se refere.

Exemplo: Uma biblioteca histórica sem nenhuma janela completa, um modelo de afluências não estacionário (escala de ruído não finita), um estágio autorregressivo com desvio-padrão nulo, um estágio com mais aberturas que o primeiro estágio do seu grupo de ruído, ou um arquivo de árvore de aberturas declarado e ausente. Recusas da biblioteca histórica, Recusas do modelo de afluências, Número de aberturas do grupo de ruído e Arquivo da árvore de aberturas ausente citam as mensagens.

Quando ocorre: Três recusas do conjunto de janelas históricas podem ocorrer a partir de um caso. O conjunto atende ao esquema forward historical e aos estágios que usam o método de amostragem historical_residuals (veja Conjunto de janelas históricas e Aberturas por resíduos históricos). Cada mensagem é insufficient data: seguido do texto abaixo:

  • Nenhum ano é admissível, de modo que o conjunto fica vazio:
    no valid historical windows found: ensure that inflow history covers the required seasons for at least one starting year
  • Um estágio do estudo não tem período sazonal:
    V2.1: stage {stage_id} (index {index}) has season_id: None; all study stages must have a season_id assigned
  • Um resíduo do conjunto não é finito:
    V2.3: historical library contains non-finite eta (NEG_INFINITY or NaN) at window year {year}, stage id {stage_id}, hydro id {hydro_id} — sigma=0 with non-matching historical observation or numerical failure

V2.1 nomeia o id do estágio e, em seguida, seu índice a partir de 0. Um estágio não tem período sazonal quando não declara nenhum e o caso não tem definições de períodos sazonais ou tem um mapa de períodos sazonais custom que deixa a data de início do estágio descoberta. Por exemplo, com um modelo de afluências de ordem 1 e um mapa de períodos sazonais custom que cobre o primeiro estágio e seu período sazonal de defasagem, mas deixa descoberta a data de início de um estágio posterior, novomodelo validate reporta V2.1.

V2.3 nomeia o ano da janela, o id do estágio e o id da hidrelétrica.

Exibição em novomodelo validate: a fase é StochasticPreparationError e o código de saída é 1. A linha error: traz o rótulo do arquivo e o prefixo stochastic error:. Este trecho omite a linha de resumo Validation:, que traz o caminho do caso.

error: scenarios/inflow_history.parquet: stochastic error: insufficient data: no valid historical windows found: ensure that inflow history covers the required seasons for at least one starting year

novomodelo run no mesmo caso encerra com código 1. A linha não tem rótulo de arquivo e é seguida da dica de validação. Este trecho omite o banner, o bloco Execution e a linha Loading case:.

error: stochastic error: insufficient data: no valid historical windows found: ensure that inflow history covers the required seasons for at least one starting year
-> run `novomodelo validate <CASE_DIR>` for a full diagnostic report

novomodelo validate monta o estudo da mesma forma que novomodelo run, de modo que também reporta uma recusa da biblioteca do esquema forward historical: como StudySetupError (scenarios/: stochastic error: …) sem policy.boundary, e como BoundaryReconciliationError (policy.boundary: …) com ele; ambos os comandos encerram com código 1. Quando um estágio também usa historical_residuals, a recusa é reportada como mostrado acima, com ou sem policy.boundary.

Quando ocorre: O modelo de afluências, declarado pelos arquivos autorregressivos e de estatísticas do caso ou ajustado a partir de inflow_history.parquet, não consegue sustentar o estudo. Duas recusas têm mensagem fixa:

  • Um estágio autorregressivo tem desvio-padrão nulo. A mensagem nomeia o id da hidrelétrica e o id do estágio, e ar_order é a ordem autorregressiva do estágio:
    invalid PAR parameters for hydro {hydro_id} at stage {stage_id}: zero standard deviation with ar_order={ar_order}: AR model requires nonzero variance to normalize coefficients
    Este é um erro do modelo estocástico. novomodelo validate o imprime após o prefixo scenarios/inflow_history.parquet: stochastic error: e encerra com código 1. novomodelo run o imprime como error: stochastic error: invalid PAR parameters … com a dica de validação e encerra com código 1.
  • Os coeficientes do modelo implicam um processo não estacionário, de modo que uma razão derivada de desvio-padrão dos resíduos não é finita. Um modelo ajustado a partir do histórico não chega a essa recusa: o ajuste reduz a ordem de um período sazonal cujo modelo implica uma variância residual negativa, e o fitting_report.json o registra como negative_residual_variance. A mensagem nomeia o id da hidrelétrica e o id do período sazonal:
    I/O error: constraint violation: derived residual_std_ratio is non-finite for hydro_id={hydro_id} season={season}: the coefficients imply a non-stationary process (implied residual variance 1 - sum(psi*rho) is negative)
    Este é um ConstraintError gerado durante a montagem do modelo, de modo que chega ao comando como erro de carga. novomodelo validate o imprime com o rótulo de arquivo scenarios/ e encerra com código 1. novomodelo run o imprime sem o prefixo I/O error: , seguido de uma dica para executar novomodelo validate, e também encerra com código 1.

Quando ocorre: Um estágio do estudo tem mais aberturas que o primeiro estágio do seu grupo de ruído, a sequência de estágios adjacentes do estudo com o mesmo season_id cujas datas de início caem em um mesmo ano civil (Geração de cenários §2.3). As contagens comparadas são as que a árvore de aberturas usa: num_openings depois dos limites impostos por um conjunto de janelas históricas e por uma biblioteca externa de cenários (os avisos de limitação da aba Notas de implementação de Geração de cenários), de modo que um limite aplicado apenas ao primeiro estágio pode provocá-la. A verificação ocorre antes do sorteio de qualquer ruído. A mensagem nomeia os dois estágios:

insufficient data: stage {dst_id} has {k_dst} openings but shares a noise group with stage {src_id}, which has {k_src}; a stage cannot have more openings than the first stage of its noise group: lower num_openings of stage {dst_id} in stages.json to {k_src}

Este é um erro do modelo estocástico. novomodelo validate o imprime depois do prefixo scenarios/inflow_history.parquet: stochastic error: e encerra com código 1. novomodelo run o imprime como error: stochastic error: insufficient data: stage …, com a dica do validate, e encerra com código 1.

Resolução: Reduza o num_openings do estágio indicado em stages.json para a contagem que a mensagem informa. Quando um limite reduziu a contagem do primeiro estágio, mais janelas históricas ou mais cenários externos para esse estágio também eliminam a recusa. Um estágio posterior com menos aberturas que o primeiro é aceito e copia as primeiras delas.

Quando ocorre: training.scenario_source.openings é {"source": "file"} e scenarios/noise_openings.parquet está ausente. A fase de preparação estocástica de novomodelo validate é interrompida com código de saída 2, assim como novomodelo run, e, com --json, a phase do erro é StochasticPreparationError. A mensagem é:

openings source is 'file' but the conventional scenarios/noise_openings.parquet is absent

Exemplo: novomodelo validate imprime a mensagem dentro de uma linha de erro de E/S. O rótulo scenarios/ e a expressão I/O error: são a forma como esta fase reporta um arquivo ausente, e <case> representa o caminho do diretório do seu caso:

error: scenarios/: I/O error: I/O error reading <case>/scenarios/noise_openings.parquet: openings source is 'file' but the conventional scenarios/noise_openings.parquet is absent
error: I/O error in <case>/scenarios/noise_openings.parquet: openings source is 'file' but the conventional scenarios/noise_openings.parquet is absent
-> check that the path exists and you have read/write permissions

Solução: Forneça scenarios/noise_openings.parquet ou declare openings como {"source": "generated"}. Configuração descreve a chave openings.


Severidade: Erro

Quando ocorre: A montagem do estudo falha em um caso sem policy.boundary: uma biblioteca de cenários (inclusive a do esquema forward historical), uma verificação de biblioteca externa, uma verificação de perfil do solver ou o filtro de admissão da regra gap e do método de seleção dynamic e de max_active_per_stage. Rótulo de arquivo: scenarios/ para um erro do modelo estocástico, config.json nos demais casos. Em um caso com policy.boundary, as mesmas falhas reportam BoundaryReconciliationError. novomodelo validate encerra com código 1.

Exemplo:

scenarios/: stochastic error: insufficient data: no valid historical windows found: ensure that inflow history covers the required seasons for at least one starting year

Severidade: Erro

Quando ocorre: Uma falha durante o ajuste da FPHA calculada ou a preparação do modelo de produção hidrelétrica. Rótulo de arquivo: system/hydro_production_models.json.

Exemplo: Uma usina cujo generation.model é fpha e que não tem entrada em system/hydro_production_models.json:

system/hydro_production_models.json: configuration validation error: hydro UHE1 (id=0) has generation_model: "fpha" in hydros.json but no entry in hydro_production_models.json. Add an entry with source: "precomputed" to specify the hyperplane source.

Em uma usina com entrada source: "computed", todo estágio do estudo que resolve para o modelo fpha precisa de uma entrada com fpha_config. Um estágio não coberto por nenhuma entrada, em uma usina cujo generation.model é fpha, ou um período sazonal que recai em um default_model igual a "fpha", é recusado com:

system/hydro_production_models.json: configuration validation error: hydro <name> (id=<id>) has source: "computed" but no FphaColumnLayout covers stage <stage_id> in hydro_production_models.json

Severidade: Erro

Quando ocorre: Uma falha durante a preparação das restrições genéricas, incluindo a expansão de expressões, a resolução de parâmetros e a montagem das folgas. Rótulo de arquivo: constraints/.

Um escalar @parameter não resolvido — um parâmetro de restrição genérica declarado em constraints/generic_parameters.json que não tem valor para um período sazonal, estágio ou patamar de que o estudo precisa — falha aqui, durante novomodelo validate. Um @name que nenhum arquivo declara é reportado na carga; veja Expressão de restrição genérica rejeitada. O parâmetro é recusado com uma das mensagens:

parameter '<name>': no seasonal value for season_id=<season> (needed by stage <t>)
parameter '<name>': PerStageBlock cell (stage=<s>, block=<b>) is not covered by any triple
parameter '<name>': PerStageBlock cell (stage=<s>, block=<b>) lies outside the study's (stage, block) grid
parameter '<name>': no specific productivity (`ρ_esp`) available for hydro_id=EntityId(<id>)

<t> e <s> são posições de estágios do estudo a partir de 0, e <b> é um índice de patamar a partir de 0. Um parâmetro seasonal precisa de um valor para o período sazonal de cada estágio do estudo, e um parâmetro per_stage_block, de um valor para cada patamar de cada estágio do estudo. Um parâmetro computed com a tag specific_productivity precisa de um specific_productivity_mw_per_m3s_per_m para sua hidrelétrica em cada estágio do estudo, proveniente de system/hydro_energy_productivity.parquet ou de system/hydros.json.

Um valor resolvido não finito também falha aqui. Um coeficiente, um limite ou um parâmetro expression que depende de parâmetros escalares é avaliado em cada estágio e patamar em que está ativo, e um cujo valor não seja finito ali (uma divisão por um parâmetro nulo naquele estágio, por exemplo) é recusado com uma das mensagens:

generic constraint <id> '<name>': the coefficient of <variable> resolves to the non-finite value <value> at stage <s>, block <b>
generic constraint <id> '<name>': the upper bound resolves to the non-finite value <value> at stage <s>, block <b>
parameter '<name>': expression resolves to the non-finite value <value> at stage <s>, block <b>

A mensagem de limite nomeia o limite inferior ou o superior; um parâmetro expression é verificado mesmo que nenhuma restrição o leia. Uma constante formada apenas por números que divide por zero é, em vez disso, recusada na carga; veja Expressão de restrição genérica rejeitada.

Exemplo: Um parâmetro seasonal cujo único valor é para o período sazonal 5, em um caso sem definições de períodos sazonais:

constraints/: configuration validation error: parameter 'sea': no seasonal value for season_id=0 (needed by stage 0)

Esta fase também reporta falhas de conversão de energia de uma usina hidrelétrica calculadas na mesma etapa — uma tabela de montante (VHA) em system/hydro_geometry.parquet que não pode ser construída, ou uma queda equivalente média da faixa útil não positiva — para qualquer usina com geometria VHA e produtibilidade específica, independentemente de seu modelo de geração e de o caso declarar ou não restrições genéricas (veja Modelos de função de produção hidrelétrica §4.3). Um valor de equivalent_productivity_mw_per_m3s em system/hydro_energy_productivity.parquet define apenas a produtibilidade no ponto de referência e não evita a verificação da queda média; um valor de integrated_equivalent_productivity_mw_per_m3s para o estágio a evita, e a mensagem nomeia essa coluna.

Uma usina cuja geometria e perdas resultam em queda negativa:

constraints/: configuration validation error: hydro EntityId(0) has non-positive useful-range mean equivalent head h_mean=-50; fix its geometry/tailrace or supply integrated_equivalent_productivity_mw_per_m3s in system/hydro_energy_productivity.parquet

Severidade: Erro

Quando ocorre: Uma falha ao reconciliar uma política de fronteira injetada com o estudo atual. Rótulo de arquivo: policy.boundary.

Exemplo: Um checkpoint de fronteira gravado por outro software ou outra versão reporta a mensagem de PolicySoftwareMismatch prefixada com o rótulo de arquivo:

policy.boundary: policy was written by {writer}, but this is novomodelo {running}; a policy loads only in the software and version that wrote it: re-run the program that produced it with novomodelo {running}; for a converted boundary policy, convert it again

A fase reporta uma recusa de qualquer uma das verificações de fronteira listadas em Requisitos de compatibilidade após a leitura do checkpoint. Um checkpoint que não pode ser lido também é reportado nesta fase, como policy.boundary: configuration validation error: failed to read boundary policy checkpoint at {path}: {e} (código de saída 1; --json imprime o objeto). Em um caso com policy.boundary, toda falha na montagem do estudo reporta esta fase e este rótulo.


Uma carga da política recusa um checkpoint que não se ajusta ao estudo que o carrega. Duas cargas geram esses erros: uma carga da FCF completa do checkpoint em policy.path (execuções com partida a quente (warm-start), retomada e somente simulação) e uma carga de fronteira do checkpoint em policy.boundary.path. novomodelo run e os pontos de entrada Python os geram antes do início do treinamento (training) ou da simulação. novomodelo validate executa ambas as cargas que a execução aplicaria, lendo o checkpoint da FCF completa de <output dir>/<policy.path> (--output, padrão <CASE_DIR>/output/), e encerra com código 1 em toda recusa que novomodelo run faria. Esses erros não são variantes de LoadError, e a carga do caso não os retorna.

Uma carga da FCF completa executa suas verificações na ordem indicada em Ordem das verificações. As verificações de uma carga de fronteira estão listadas em Requisitos de compatibilidade. Um manifest.bin cujo format_version não seja 4 falha antes dessas verificações: failed to read policy checkpoint: serialization error for entity checkpoint_manifest: unsupported checkpoint manifest format_version {n}; expected 4; re-run the program that produced it with novomodelo {running}; for a converted boundary policy, convert it again, código de saída 1.

Como uma falha de carga da política chega até você

Seção intitulada “Como uma falha de carga da política chega até você”
CanalRecusaCheckpoint ilegível ou ausente
novomodelo run, carga da FCF completaCódigo de saída 1. error: {message} e a dica de validação no stderr.Código de saída 1: error: Policy directory not found: {path}. {requirement} ou error: failed to read policy checkpoint: {e}. Código de saída 2 para um checkpoint cuja leitura o sistema operacional recusa: error: I/O error in {path}: {source} e a dica de permissões.
novomodelo validate, carga da FCF completaCódigo de saída 1. Validation: 1 errors, 0 warnings in <case> e error: <output dir>/<policy.path>: {message}; em --json, fase WarmStartIncompatible, ResumeIncompatible ou SimulationPolicyIncompatible.Código de saída 1 (fase igual à de uma recusa), ou código de saída 2 com a fase IoError para um checkpoint cuja leitura o sistema operacional recusa.
novomodelo run e novomodelo validate, carga de fronteiraCódigo de saída 1. novomodelo run imprime error: {message} e uma linha de dica. novomodelo validate rotula a mensagem com policy.boundary: ; com --json, reporta a fase BoundaryReconciliationError.Código de saída 1. error: failed to read boundary policy checkpoint at {path}: {e} e uma linha de dica no stderr. Em novomodelo validate --json, fase BoundaryReconciliationError.
Python, carga da FCF completa (novomodelo.run.run, Study.train, Study.load_policy)PolicyIncompatibleError. A mensagem começa com policy validation error: .ValidationError para um diretório ausente, PolicyIncompatibleError para uma falha de leitura ou decodificação, CaseIoError para uma leitura recusada pelo sistema operacional. A mensagem é Policy directory not found: {path}. {requirement} ou failed to read policy checkpoint: {e}, sem prefixo.
Python, carga de fronteira (novomodelo.run.run, Study, Study.train)novomodelo.run.run e Study.train geram PolicyIncompatibleError para uma divergência de versão, com o prefixo de mensagem policy validation error: , e ValidationError para todas as demais recusas, com o prefixo de mensagem boundary cut error: . Study(...) é construído sem erro sobre um checkpoint que consegue ler.ValidationError. A mensagem começa com setup validation error: . É gerado na montagem do estudo, antes do treinamento.
novomodelo.results.load_policyNenhuma recusa: lê um checkpoint de qualquer versão do novomodelo sem compará-lo com um estudo.FileNotFoundError para um diretório ausente ou um manifest.bin ausente. OutputError para um arquivo cujo conteúdo não pode ser decodificado.

{requirement} nomeia o modo de execução: Cannot warm-start without a prior policy., Cannot resume without a prior checkpoint. ou Cannot run simulation-only mode without a trained policy.

Severidade: Erro

Quando ocorre: Uma carga da FCF completa ou uma carga de fronteira lê um checkpoint cujo manifest.bin registra outro software ou outra versão que não a do build em execução: os campos software e software_version são comparados de forma exata, de modo que um build de patch ou pré-lançamento diferente também é recusado. Um checkpoint cujo format_version não seja 4 é recusado antes desta verificação (Como uma falha de carga da política chega até você). Filtro de versão enuncia a regra.

Mensagem:

policy was written by {writer}, but this is novomodelo {running}; a policy loads only in the software and version that wrote it: re-run the program that produced it with novomodelo {running}; for a converted boundary policy, convert it again

{writer} é <software> <version>, <software>, which recorded no version, software that recorded no name, version <version> ou software that recorded no name or version; {running} é a versão do novomodelo que o carrega.

Classe Python: O Python gera PolicyIncompatibleError com o prefixo de mensagem policy validation error: , tanto para uma carga da FCF completa quanto para uma carga de fronteira. Em novomodelo validate --json, um checkpoint de fronteira gravado por outro software ou outra versão reporta a fase BoundaryReconciliationError e a mensagem prefixada com policy.boundary: .

Solução: Execute novamente o programa que produziu o checkpoint com a versão do novomodelo em uso; para uma política de fronteira convertida, converta-a novamente. Filtro de versão descreve ambos os caminhos.

Quando ocorre: Uma carga da FCF completa encontra um conjunto de cortes do checkpoint que não registra escala de custo ou que registra uma que não é um número positivo finito, ou um checkpoint que descreve um espaço de estados ou um grafo do estudo diferente do estudo atual. A verificação de escala de custo é o passo 2 da ordem das verificações, e as verificações de estado e de grafo são o passo 4. As verificações de identidade de entidades e de grafo só são executadas quando ambos os lados trazem o manifesto.

Mensagens:

Escala de custo (passo 2):

policy checkpoint predates self-describing cuts (its cuts/<pool>.bin for pool {pool} carries no cost_scale_factor); re-run the program that produced it with novomodelo {running}; for a converted boundary policy, convert it again
policy checkpoint pool {pool} records cost_scale_factor {factor}, which is not a finite positive number; re-run the program that produced it with novomodelo {running}; for a converted boundary policy, convert it again

{pool} é o id do estágio do conjunto de cortes, e é reportado o primeiro conjunto que falha.

Estado e grafo (passo 4):

policy state_dimension mismatch: policy has {n}, current system has {n} (a lag-state depth mismatch is a common cause)
policy num_stages mismatch: policy has {n}, current system has {n}
policy n_pools mismatch: policy has {n}, current system has {n}
entity manifest length mismatch: source has {n} slots, current study has {n}
entity-identity mismatch at slot {i}: source (entity_type={t}, entity_id={id}, subindex={s}) != current (entity_type={t}, entity_id={id}, subindex={s}); the cut coefficient at this slot would attach to the wrong state variable
graph manifest n_pools mismatch: source has {n}, current study has {n}
graph manifest node-count mismatch: source has {n} nodes, current study has {n}
graph manifest node {i} mismatch: source (id={id}, stage_id={id}, pool_id={id}) != current (id={id}, stage_id={id}, pool_id={id})
graph manifest edge-count mismatch: source has {n} edges, current study has {n}
graph manifest edge {i} mismatch: source ({source_id} -> {target_id}) != current ({source_id} -> {target_id})

Uma carga de fronteira recusa um conjunto de cortes resolvido sem cost_scale_factor com uma mensagem própria, e um cujo fator não seja um número positivo finito com a mensagem records cost_scale_factor acima:

boundary policy checkpoint at {path} predates self-describing cuts (its resolved cuts/<pool>.bin carries no cost_scale_factor); re-run the program that produced it with novomodelo {running}; for a converted boundary policy, convert it again

Classe Python: O Python gera PolicyIncompatibleError com o prefixo de mensagem policy validation error: para as mensagens da FCF completa, e ValidationError com o prefixo de mensagem boundary cut error: para a mensagem de fronteira.

Solução: Treine uma nova política para o estudo alterado ou restaure as entradas correspondentes; veja Ordem das verificações. Para uma recusa de escala de custo, execute novamente o programa que produziu o checkpoint com a versão do novomodelo em uso, como indica sua mensagem.

Quando ocorre: Uma carga com policy.mode = "resume" constata que o checkpoint não pode dar continuidade à execução interrompida de forma idêntica. As cinco verificações são executadas após as verificações estruturais, na ordem de Recusas de retomada, e a primeira que falha interrompe a execução com a fase ResumeIncompatible. Uma carga warm_start do mesmo checkpoint não faz nenhuma dessas verificações.

Mensagens:

resume needs the forward-pass count the checkpoint was written with: training.selection.forward_passes is {run} here and {stored} in the checkpoint; set it to {stored} or continue with policy.mode = warm_start
resume needs the trial-state history of training.cut_selection.selection.method = level1; the checkpoint holds none (it was written by a run without level1 or exports.states); continue with policy.mode = warm_start or retrain
resume needs every trial state of the run under training.cut_selection.selection.method = level1 without lookback_iterations; the checkpoint holds those of the last {stored} iterations only; set lookback_iterations to at most {stored} or continue with policy.mode = warm_start
resume needs the trial states of the last {window} iterations (training.cut_selection.selection.lookback_iterations = {window}); the checkpoint holds those of the last {stored} iterations only; set lookback_iterations to at most {stored} or continue with policy.mode = warm_start
resume needs the binding counters read by {reader}; the checkpoint holds none (it was written by a run without max_active_per_stage or the dynamic method); continue with policy.mode = warm_start or retrain
resume needs a whole checkpoint; the checkpoint's per-scenario bases are not whole (it was written when a run failed); resume from the last whole checkpoint or continue with policy.mode = warm_start

{reader} é training.cut_selection.max_active_per_stage quando o limite está definido, e training.cut_selection.selection.method = dynamic caso contrário. A retomada de uma execução que declarou policy.boundary também é recusada quando as linhas de fronteira diferem das do checkpoint; a mensagem é citada em Retomada com fronteira.

novomodelo validate rotula cada mensagem com <output dir>/<policy.path>: configuration validation error: . Por exemplo, a retomada, com training.selection.forward_passes igual a 2, de um checkpoint gravado com 1 reporta:

rs/output/./policy: configuration validation error: resume needs the forward-pass count the checkpoint was written with: training.selection.forward_passes is 2 here and 1 in the checkpoint; set it to 1 or continue with policy.mode = warm_start

Classe Python: PolicyIncompatibleError, com o prefixo de mensagem policy validation error: .

Solução: Siga a alternativa indicada na mensagem ou continue com policy.mode = "warm_start".

Quando ocorre: Uma carga da FCF completa lê um arquivo states/<pool>.bin que não se ajusta aos conjuntos de cortes carregados: um conjunto que o estudo não tem, um comprimento de estado diferente do do conjunto ou um estado armazenado em uma posição que não contém corte carregado.

pool {pool}: stored trial states for a pool the study does not have
pool {pool}: stored trial states have {n} values, the study's pool {dimension}
pool {pool}: a trial state is stored at slot {slot}, which holds no cut

Solução: Carregue um checkpoint gravado para o estudo atual ou treine uma nova política.

Quando ocorre: Uma execução com o método dynamic que simula com simulation.cut_set = "all" carrega uma política, ou linhas de policy.boundary, contendo uma linha incluída por "all" e que não está ativa (Configuração — Conjunto de cortes da simulação).

training.cut_selection.selection.method = dynamic cannot simulate simulation.cut_set = all over this policy: {pool} holds {held} cuts of which {active} are active (it was written by a run that deactivates cuts), and a dynamic lazy solve reads only the active cuts; set simulation.cut_set = active or use the level1 method

{pool} é pool {id} para o primeiro conjunto de cortes nessa situação da política carregada, ou the policy.boundary pool para as linhas de fronteira.

Solução: Defina simulation.cut_set como "active" ou use o método level1.

Divergência de tendência hidrológica na fronteira

Seção intitulada “Divergência de tendência hidrológica na fronteira”

Quando ocorre: Uma carga de fronteira (policy.boundary) encontra uma posição de defasagem de afluência do estudo atual que o checkpoint de fronteira não consegue suprir. Ou o checkpoint não precifica nenhum coeficiente de defasagem de afluência para uma hidrelétrica em uma profundidade de defasagem de que o estudo precisa, ou o coeficiente que contém se refere a um passado diferente do do estudo: ambos os lados trazem uma data de referência e as duas datas diferem. Requisitos de compatibilidade apresenta a ordem das verificações de fronteira.

Mensagens:

Nenhum coeficiente para uma hidrelétrica em uma profundidade de defasagem; {names} lista cada par ausente como hydro {id} at lag depth {depth}, separados por vírgulas:

boundary policy has no inflow-lag coefficient for {names}: the boundary is lag-depth-incompatible with the current study

Um coeficiente que se refere a um passado diferente; as duas datas são impressas como YYYY-MM-DD:

boundary policy's inflow-lag coefficient for hydro {id} at lag depth {depth} references a different past than the current study: boundary {date}, current {date}

Classe Python: O Python gera ValidationError com o prefixo de mensagem boundary cut error: . novomodelo validate rotula a mensagem com policy.boundary: .

Solução: Se o checkpoint não tiver coeficiente para uma hidrelétrica em uma profundidade de defasagem, treine o checkpoint de origem com inflow_lags: true no estágio seguinte ao estágio do conjunto de cortes de origem. Se as duas datas diferirem, atribua ao estágio do conjunto de cortes de origem e ao último estágio do estudo a mesma data de início, e faça o mesmo para cada par anterior de estágios; Requisitos de compatibilidade descreve ambas as condições.


As sobrescritas de perfil do solver por fase (training.solver.backward, training.solver.forward, simulation.solver) são validadas em relação à matriz de suporte do backend compilado na montagem do estudo, antes que qualquer PL de estágio seja construído, em todos os processos MPI; cada rejeição abaixo é um erro de configuração com mensagem própria.

novomodelo validate executa essas verificações em todos os casos: reporta uma rejeição com a fase StudySetupError (config.json: configuration validation error: …), ou BoundaryReconciliationError com policy.boundary configurado. novomodelo run recusa o caso antes do treinamento. Ambos encerram com código 1.

Quando ocorre: Um binário compilado com o backend CLP (veja Instalação — Build com CLP) rejeita de imediato qualquer campo de sobrescrita do perfil do solver — as opções próprias do CLP não foram avaliadas em relação a esses campos, de modo que o novomodelo se recusa a aplicar silenciosamente a ele um valor pensado para o HiGHS. Um bloco "solver": {} vazio e a ausência do bloco solver são ambos válidos; apenas um campo efetivamente definido dispara o erro. Quando um perfil define mais de um campo, apenas o primeiro campo na ordem de declaração é nomeado, de modo que corrigir um campo por vez revela um erro por ciclo de correção, em vez de um relatório combinado.

Exemplo:

solver profile field "dual_edge_weight" for phase "backward" is unsupported on backend "clp": rejected until CLP is re-measured

Para primal_feasibility_tolerance, o token do campo traz também o valor definido:

solver profile field "primal_feasibility_tolerance" (1e-7) for phase "forward" is unsupported on backend "clp": rejected until CLP is re-measured

"<phase>" é forward, backward ou simulation.

Solução: Remova o campo de sobrescrita de config.json em um binário compilado com CLP ou passe para o backend padrão HiGHS, se a sobrescrita for necessária.

Backend HiGHS: seis verificações de intervalo por campo

Seção intitulada “Backend HiGHS: seis verificações de intervalo por campo”

O backend padrão (highs) aceita todos os campos do perfil do solver. Os enums fechados (dual_edge_weight, scale, price, presolve) e use_warm_start são sempre válidos — toda variante é verificada na leitura de config.json, de modo que não há verificação de intervalo separada em tempo de execução para eles. Os seis campos numéricos restantes têm o intervalo verificado na montagem do estudo; cada falha nomeia o campo, o valor rejeitado e a fase (forward / backward / simulation) cujo perfil o definiu.

CampoRegraMensagem
primal_feasibility_tolerancedeve ser finitounsupported primal_feasibility_tolerance {value} for backend "highs" in phase "{phase}": value must be finite
dual_feasibility_tolerancedeve ser finito e >= 0.0000000001unsupported dual_feasibility_tolerance {value} for backend "highs" in phase "{phase}": value must be finite and >= 0.0000000001
simplex_update_limitdeve ser <= 2147483647unsupported simplex_update_limit {value} for backend "highs" in phase "{phase}": value must be <= 2147483647
cost_perturbationdeve ser finito e >= 0unsupported cost_perturbation {value} for backend "highs" in phase "{phase}": value must be finite and >= 0
factor_pivot_thresholddeve estar em [0.0008, 0.5]unsupported factor_pivot_threshold {value} for backend "highs" in phase "{phase}": value must be in [0.0008, 0.5]
steepest_edge_devex_fallback_thresholddeve ser finito e >= 1.0unsupported steepest_edge_devex_fallback_threshold {value} for backend "highs" in phase "{phase}": value must be finite and >= 1.0

0.0000000001 é 1e-10 escrito por extenso; 2147483647 é o maior inteiro de 32 bits com sinal; [0.0008, 0.5] é o próprio intervalo de limiar de pivoteamento aceito pelo HiGHS.

Solução: Ajuste o campo problemático para que atenda à regra da tabela. {phase} na mensagem identifica qual de training.solver.backward, training.solver.forward ou simulation.solver definiu o valor inválido.


Uma falha durante novomodelo run imprime error: {message} no stderr, seguido de linhas de dica que dependem do código de saída:

  • Código 1, uma recusa encontrada durante a execução (por exemplo, uma divergência de --threads), acrescenta -> run `novomodelo validate <CASE_DIR>` for a full diagnostic report.
  • Código 2, cuja mensagem é I/O error in {context}: {source}, acrescenta -> check that the path exists and you have read/write permissions.
  • Código 3 acrescenta -> check constraint bounds (hydros may have conflicting min/max storage) e -> run `novomodelo validate <CASE_DIR>` for a full diagnostic report.
  • Código 4 acrescenta -> this may indicate a software or environment problem e -> report this at https://github.com/ons-ccee-epe/novomodelo/issues.

Com dois ou mais processos MPI, cada processo que falha (um rank MPI) imprime primeiro rank {rank}: em uma linha própria e depois as mesmas linhas, e o job é encerrado com o código de saída desse processo. Quando o rank 0 não consegue gravar as saídas da execução, todos os ranks encerram com o código do rank 0, e os demais imprimem rank 0 failed to write the run outputs; failing on every rank in lockstep. Um checkpoint que não se ajusta ao estudo é recusado antes do início do treinamento ou da simulação; veja Erros de carga da política.

Um panic, uma falha interna, imprime sua mensagem no stderr e encerra com código 101. Com dois ou mais processos MPI, o processo que entra em panic imprime em seguida rank {rank}: panicked; aborting the MPI job e aborta o job inteiro com código de saída 101.

Uma falha dentro de uma iteração de treinamento encerra o treinamento e sai com o código do seu erro: 3 para uma falha de PL ou do solver, 4 para uma falha de comunicação, 1 para uma recusa. Uma execução sem --quiet imprime antes Training failed after {n} iterations. Partial outputs written to {dir}; the partial policy is in {policy}. no stderr, em que {policy} é o diretório da política acrescido de .partial: uma execução que falha grava sua política parcial ao lado de policy.path e nunca substitui um checkpoint em policy.path. A execução também registra ERROR training failed after {n} iterations: {error} no stderr, inclusive com --quiet. Sob MPI, um processo que falha primeiro pode abortar o job antes que o processo raiz imprima essas linhas. As mesmas falhas de PL na simulação encerram com código 3; veja Falhas da simulação.

MensagemCódigo de saídaQuando ocorreSolução
LP infeasible at stage {stage}, iteration {iteration}, scenario {scenario}3Um PL de estágio de uma iteração de treinamento não tem solução viável; {stage} e {scenario} são posições a partir de 0.Verifique os limites das restrições nesse estágio, como uma restrição genérica com folga desabilitada ou limites conflitantes de hidrelétricas; novomodelo validate não resolve os PLs dos estágios, de modo que pode aceitar um caso assim.
{solver_message}3Um PL de estágio de uma iteração de treinamento termina em uma falha do solver diferente de inviabilidade; {solver_message} é uma das mensagens do solver abaixo, por exemplo LP is unbounded.Procure {solver_message} nas linhas abaixo.
LP is unbounded3A função objetivo do PL do estágio é ilimitada inferiormente.Procure no caso um limite ausente ou um custo com sinal trocado.
numerical difficulty: {message}3O solver reporta dificuldades numéricas que persistem em todas as suas novas tentativas; {message} é a descrição do solver.Reporte o caso com a mensagem.
time limit exceeded after {seconds}s ou iteration limit reached after {iterations} iterations3Uma única resolução de PL termina no seu limite de tempo ou no limite de iterações simplex do solver.Reporte o caso com a mensagem.
internal solver error (code {code}): {message} ou internal solver error: {message}3O solver falha de um modo que não consegue classificar.Reporte o caso com a mensagem.
basis inconsistent: num_row={num_row}, total_basic={total_basic} (col_basic={col_basic}, row_basic={row_basic}) ou basis row count mismatch: lp_rows={lp_rows}, basis_rows={basis_rows}3O solver rejeita uma base de aproveitamento (warm-start da base) que não se ajusta ao PL.Reporte o caso com a mensagem.
non-uniform n_workers_local across MPI ranks: local={local}, min={min}, max={max}; all ranks must run with the same --threads value1Os processos MPI de um mesmo job foram iniciados com valores diferentes de --threads, e a simulação backward da primeira iteração detecta isso; local é a quantidade de threads do processo que imprime, e min e max são a menor e a maior quantidade.Inicie todos os processos do job com o mesmo valor de --threads.
{solver} initialisation failed: {e}3O backend do solver (HiGHS ou CLP) não consegue criar sua instância de solver no início do treinamento; {e} é a mensagem do backend.Reporte-o com a mensagem completa.
{solver} initialisation failed for simulation pool: {e}3O backend do solver não consegue criar as instâncias de solver dos workers da simulação.Reporte-o com a mensagem completa.

Um PL de estágio inviável na primeira iteração de treinamento de uma execução com um único processo, em um caso que novomodelo validate aceita, imprime:

ERROR training failed after 0 iterations: infeasible subproblem at stage 0, iteration 1, scenario 0
Training failed after 0 iterations. Partial outputs written to ./out; the partial policy is in ./out/policy.partial.
error: LP infeasible at stage 0, iteration 1, scenario 0
-> check constraint bounds (hydros may have conflicting min/max storage)
-> run `novomodelo validate <CASE_DIR>` for a full diagnostic report

Quando alguma resolução de PL da execução devolveu uma solução primal ótima que viola um limite de linha, novomodelo run imprime uma linha no stderr ao final da execução (apenas no rank 0; --quiet não a suprime). A execução continua bem-sucedida e o código de saída não muda:

warning: LP solves returned a primal solution that misses a row bound by more than the primal feasibility tolerance plus 1e-11 of the row's magnitude: {n} of {m} (forward {f}, backward {b}, lower bound {l}, simulation {s}); per-stage counts are in the lp_row_violations column of solver/iterations.parquet

Uma linha é contada quando sua violação excede a tolerância de viabilidade primal do solver mais 1e-11 vezes a magnitude da linha: a soma dos valores absolutos de seus termos na solução devolvida, tomada como no mínimo 1. O novomodelo.run do Python imprime o mesmo texto com o prefixo novomodelo-python: . Uma contagem acima de zero significa que as saídas recalculadas a partir dessa resolução (balanços, duais, cortes) podem não fechar; reporte-a com o caso.

Uma falha de PL de estágio na simulação encerra com código 3, e todas as demais falhas da simulação encerram com código 4.

MensagemCódigo de saídaQuando ocorreSolução
LP infeasible at scenario {scenario_id}, stage {stage_id}: {solver_message}3Um PL de estágio de um cenário da simulação não tem solução viável; {solver_message} é LP infeasible.Verifique os limites das restrições nesse estágio, como uma restrição genérica com folga desabilitada; novomodelo validate não resolve os PLs dos estágios, de modo que pode aceitar um caso assim.
solver error at scenario {scenario_id}, stage {stage_id}: {solver_message}3Um PL de estágio de um cenário da simulação termina em uma falha do solver diferente de inviabilidade; {solver_message} é uma das mensagens do solver de Falhas do solver.Localize a mensagem do solver nessas linhas.
stochastic error: {detail}4O amostrador de cenários da simulação não pode ser construído ou falha ao amostrar; {detail} é a mensagem do modelo estocástico.Veja Falhas estocásticas durante uma execução.
invalid simulation configuration: {detail}4A montagem da simulação falha em uma verificação interna de consistência.Reporte o caso com a mensagem.
simulation output channel closed unexpectedly ou simulation drain thread panicked4A thread que grava os resultados da simulação para antes do fim da simulação.Reporte o caso com a saída completa da execução.
simulation cost aggregation error: I/O error during simulation output: {message}4A coleta dos custos por cenário entre os processos MPI falha ao final da simulação; {message} nomeia a coleta, allgatherv(counts) ou allgatherv(costs), e o erro de comunicação. Trata-se de uma falha de comunicação, e não de um erro do sistema de arquivos; encerra com código 4.Veja Falhas de comunicação.
a peer rank failed simulation; failing on every rank in lockstep4Outro processo MPI falha durante a simulação, e este processo é encerrado junto com ele.Leia o erro impresso sob a linha rank {rank}: do processo que falhou primeiro.
MensagemCódigo de saídaQuando ocorreSolução
communication backend error: communication backend 'mpi' is not available in this build (available: local)4--comm-backend mpi é informado em um binário compilado sem suporte a MPI, que oferece apenas o backend local.Execute o build novomodelo-mpi sob um lançador MPI (veja Implantação em HPC e clusters) ou remova --comm-backend mpi para executar em um único processo.
communication backend error: 'mpi' backend initialization failed: {source}4O runtime MPI não consegue ser inicializado em um build com MPI; {source} traz a mensagem da biblioteca MPI.Verifique se o runtime MPI está instalado e se o job é iniciado sob mpiexec, mpirun ou srun.
collective operation '{operation}' failed with MPI error code {code}: {message}4Uma operação coletiva MPI (broadcast, barrier, allreduce ou allgatherv) falha durante a execução. O texto segue um rótulo que nomeia a etapa, como broadcast error (data): , post-training barrier error: ou simulation path gather error: .Leia a mensagem da biblioteca MPI e a saída dos demais processos para identificar o processo que falhou primeiro.
cut_wire: unsupported version {version}1Na simulação backward de uma iteração de treinamento, um processo lê um registro de corte cujo byte de versão não é o que seu próprio binário grava, o que ocorre quando os processos de um mesmo job executam builds com versões diferentes do formato de transmissão de cortes. {version} é o byte gravado pelo processo remetente. A mensagem acrescenta a dica de validação.Reinicie todos os processos com o mesmo binário do novomodelo.
try_from_broadcast_payload: unsupported wire version {version} at stage {stage} (expected {expected})1Um processo lê bases de PL armazenadas que outro processo gravou com uma versão do formato de transmissão diferente da sua: o rank 0, quando coleta as bases de todos os processos em um checkpoint periódico e ao final do treinamento, e todos os demais processos, quando leem as bases de aproveitamento (warm-start) que o rank 0 transmite ao final do treinamento. {version} é a versão gravada pelo processo remetente e {stage}, a posição do nó a partir de 0. A dica de novomodelo validate que a segue não se aplica.Reinicie todos os processos com o mesmo binário do novomodelo.
gather_basis_store: rank {rank} sent more than its {passes} rows at node {node} ou gather_basis_store: rank {rank}'s basis payload at node {node} does not fit an i32 count1O rank 0 não consegue decodificar as bases de PL armazenadas que coleta de todos os processos em um checkpoint periódico ou ao final do treinamento, ou as bases que um processo mantém para um nó excedem uma contagem MPI. A dica de novomodelo validate que a segue não se aplica.Reporte o caso com a mensagem.
rank 0 signaled broadcast failure (length 0)4O rank 0 falha ao carregar o caso, antes de transmitir o estudo, de modo que os demais processos recebem um broadcast vazio; o rank 0 encerra com o código do seu próprio erro.Corrija o erro que o rank 0 imprime sob sua linha rank 0:.
hydro model preprocessing error on non-root rank: {e}4Um processo diferente do rank 0 não consegue preparar os modelos hidrelétricos, que ele reconstrói a partir do diretório do caso.Dê a todos os processos acesso de leitura ao mesmo diretório do caso e leia {e} para identificar a causa.
opening tree differs across MPI ranks (fingerprints {min:#018x} to {max:#018x}); every rank must build the same tree from the broadcast inputs4Em dois ou mais processos MPI, os resumos (digests) da árvore de aberturas que os ranks construíram diferem depois da montagem, de modo que eles treinariam contra árvores diferentes; {min} e {max} são o menor e o maior resumo, cada um com 0x e 16 dígitos hexadecimais (Árvore de aberturas entre ranks MPI).Reporte o caso com a mensagem.
opening tree fingerprint exchange failed: {e}4A troca dos resumos da árvore de aberturas entre os processos MPI falha; {e} é o erro de comunicação.Leia {e} para saber qual operação falhou.
enumerated training at world >= 2 requires a graph with no interior branching (a deterministic trunk + terminal fan): node {node_id} is a non-leaf node not shared by every root→leaf path — the enumerated forward's per-rank state exchange is elided for it, so the replicated backward would cut against a zeroed incoming state on any rank that never visits it, pending the interior-node state-exchange fix1O treinamento enumerado (training.selection.method "enumerated") é executado em dois ou mais processos MPI sobre um grafo da política com um nó de ramificação interno; a mensagem não tem prefixo e é seguida de -> run `novomodelo validate <CASE_DIR>` for a full diagnostic report, embora novomodelo validate não verifique essa condição e encerre com código 0 no caso.Mantenha toda ramificação no último estágio, execute em um único processo ou use a seleção amostrada.

Solicitar o backend MPI a partir de um binário compilado sem suporte a MPI imprime:

error: communication backend error: communication backend 'mpi' is not available in this build (available: local)
-> this may indicate a software or environment problem
-> report this at https://github.com/ons-ccee-epe/novomodelo/issues

Uma falha do sistema de arquivos ao gravar o checkpoint da política ou os resultados do treinamento e da simulação encerra com código 2, exceto a gravação dos resultados de um único cenário da simulação, descrita na última linha. Os arquivos de training/ gravados antes do início do treinamento encerram com código 4 em qualquer falha, de modo que um diretório --output sem permissão de gravação termina com código 4, a menos que antes falhe a remoção de uma saída obsoleta, o que encerra com código 2.

MensagemCódigo de saídaQuando ocorreSolução
I/O error in {context}: {source}2Uma gravação do checkpoint da política ou dos resultados do treinamento ou da simulação, após o início do treinamento, falha no sistema de arquivos, por exemplo quando o disco está cheio ou um arquivo de resultados não pode ser criado; {context} é o caminho.Verifique se {context} existe e permite gravação e se há espaço livre em disco; depois, execute novamente.
I/O error in checkpoint write at iteration {n}: {path}: {source}2Um checkpoint periódico não pode ser gravado em policy.path.Verifique se o diretório da política permite gravação e se há espaço em disco.
checkpoint write at iteration {n}: refusing to write a checkpoint: {entry}, found in {dir}, is not part of a checkpoint (manifest.bin, metadata.json, cuts/, basis/, states/); move it elsewhere or write the checkpoint to another directory1O diretório da política contém uma entrada que nenhum gravador de checkpoint deixa ali; nada é alterado em disco.Mova a entrada ou defina policy.path como outro diretório.
checkpoint write at iteration {n}: {e}4A codificação de um checkpoint periódico falha; {e} é a mensagem do codificador.Reporte o caso com a mensagem.
I/O error in {path}: {source}2Uma saída obsoleta em --output, como um marcador _SUCCESS, não pode ser removida antes do início do treinamento; {path} é a entrada.Torne a entrada removível ou aponte --output para um diretório sem ela.
failed to write hydro model summary: {e}, failed to write provenance report: {e} ou failed to write scaling report: {e}4Um dos arquivos de training/ que novomodelo run grava antes do início do treinamento não pode ser gravado; {e} é a mensagem do gravador, por exemplo I/O error accessing {path}: {source}.Aponte --output para um diretório que o processo possa criar e no qual possa gravar.
rank 0 pre-training export failed; failing on every rank in lockstep4Sob MPI, o rank 0 falha em uma dessas gravações ou remoções, e todos os demais processos imprimem esta mensagem.Corrija o erro que o rank 0 imprime sob sua linha rank 0:.
serialization error for entity {entity}: {message}4A codificação de uma tabela de saída falha para a coleção de entidades indicada, ou a gravação de um checkpoint da política recusa seus conteúdos antes de gravar qualquer coisa: {entity} é então policy_checkpoint_structure, policy_checkpoint_dates ou policy_checkpoint_size, e {message} nomeia o arquivo e a regra violada (Conteúdo do diretório de checkpoint).Reporte o caso com a mensagem.
manifest error for {manifest_type}: {message}4A construção de um manifesto de saída falha.Reporte o caso com a mensagem.
ERROR simulation write error: {e}0Os resultados de um cenário da simulação não podem ser gravados. A execução continua e encerra com código 0, e scenarios.failed em simulation/metadata.json conta os cenários que falharam.Corrija a causa indicada em {e}, execute novamente a simulação e verifique scenarios.failed após cada execução.

Uma recusa do modelo estocástico gerada durante a montagem do estudo encerra com código 1 em ambos os comandos; StochasticPreparationError a cita. O stochastic error: … do amostrador da simulação encerra com código 4 (Falhas da simulação).