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.
Como esses erros chegam até você
Seção intitulada “Como esses erros chegam até você”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 prefixoerror:; os avisos (após uma validação bem-sucedida) são impressos como linhas com o prefixowarning:. -
novomodelo validate --json— em caso de sucesso, um objeto JSON no stdout:{ configured, boundary_date, report }, maispolicy_load: { mode, unused_stored_bases }quando a execução carregaria uma política (modewarm_start,resumeousimulation_only), sem chaveerror;configuredétruequandopolicy.boundaryestá configurado e a execução o aplica, o que só ocorre em uma execução que treina, efalsecaso contrário. Em caso de falha, essas três chaves sãonulle uma chaveerrorcontém{ phase, message }. O campophaseé o nome da variante deLoadErrorque falhou, um dos seis tipos da fase de preparação ou um tipo de carga da política (WarmStartIncompatible,ResumeIncompatible,SimulationPolicyIncompatibleouIoErrorpara um checkpoint cuja leitura o sistema operacional recusa); ele nomeia uma variante deLoadError, um tipo de preparação ou um tipo de carga da política, nunca oErrorKindde um diagnóstico coletado. Uma falha na carga do caso reportaConstraintErrorem 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; seumessageconté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ódigo2.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 }] }.errorscontém no máximo uma entrada: nenhuma quandovalidé verdadeiro, uma em caso de falha. Seukindé a mesma string dophaseda CLI, e seumessageé o texto completo do erro, que, em uma falha na carga do caso, começa comconstraint violation:. Para um diretório do caso ausente, em que a CLI não imprime objeto JSON, o Python ainda retorna uma entradaIoError. Okindde cada aviso é o nome doErrorKind. -
Classes de exceção Python de
novomodelo.errors— a carga do caso geraValidationErrorouCaseIoError; uma recusa na carga da política gera a classe do seu erro:PolicyIncompatibleErrorpara um checkpoint recusado, ausente ou que não pode ser decodificado,CaseIoErrorpara uma leitura de checkpoint recusada pelo sistema operacional, eValidationErrorpara um diretório da política ausente ou uma reconciliação de fronteira recusada (veja Erros de carga da política). Vejanovomodelo.errorspara 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.
Índice de tipos
Seção intitulada “Índice de tipos”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.
| Tipo | Reportado como | Severidade | Código de saída |
|---|---|---|---|
FileNotFound | linha de relatório [FileNotFound] | Erro | 1 |
ParseError | linha de relatório [ParseError]; valor de phase | Erro | 1 como linha de relatório; como valor de phase, 4 (novomodelo validate) ou 1 (novomodelo run) |
SchemaViolation | linha de relatório [SchemaViolation] | Erro | 1 |
InvalidReference | linha de relatório [InvalidReference] | Erro | 1 |
DuplicateId | linha de relatório [DuplicateId] | Erro | 1 |
InvalidValue | linha de relatório [InvalidValue] | Erro | 1 |
CycleDetected | linha de relatório [CycleDetected] | Erro | 1 |
DimensionMismatch | linha de relatório [DimensionMismatch] | Erro | 1 |
BusinessRuleViolation | linha de relatório [BusinessRuleViolation] | Erro | 1 |
WarmStartIncompatible | valor de phase (carga da política recusada); linha warning: | Erro; Aviso | 1 (2 sob a fase IoError); 0 para um aviso |
ResumeIncompatible | valor de phase (carga da política recusada); linha warning: | Erro; Aviso | 1 (2 sob a fase IoError); 0 para um aviso |
SimulationPolicyIncompatible | valor de phase (carga da política recusada); linha warning: | Erro; Aviso | 1 (2 sob a fase IoError); 0 para um aviso |
NotImplemented | linha de relatório [NotImplemented] | Erro | 1 |
UnusedEntity | linha warning: | Aviso | 0 |
ModelQuality | linha warning: | Aviso | 0 |
SemanticAmbiguity | linha warning: | Aviso | 0 |
IoError | valor de phase | Erro | 2, inclusive para uma leitura da política recusada pelo sistema operacional |
SchemaError | valor de phase | Erro | 1, 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) |
ConstraintError | valor de phase | Erro | 1 |
ConfigValidationError | valor de phase | Erro | 1 |
StochasticPreparationError | valor de phase | Erro | 1, ou 2 para uma leitura de entrada estocástica, como uma árvore de aberturas declarada e ausente (ambos os subcomandos) |
StudySetupError | valor de phase | Erro | 1 |
HydroModelsPreparationError | valor de phase | Erro | 1 |
GenericConstraintValidationError | valor de phase | Erro | 1 |
BoundaryReconciliationError | valor de phase | Erro | 1 |
PolicySoftwareMismatch | recusa na carga da política | Erro | 1 |
| Bases armazenadas não utilizadas | linha warning: | Aviso | 0 |
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.
Tipos de relatório de validação
Seção intitulada “Tipos de relatório de validação”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.
FileNotFound
Seção intitulada “FileNotFound”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 directoryUm 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.
ParseError
Seção intitulada “ParseError”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:
| Campo | Descrição |
|---|---|
path | Caminho do arquivo cuja análise falhou |
message | Descrição legível da falha de análise |
Exemplo:
[ParseError] stages.json: parse error: EOF while parsing a list at line 2 column 0Um 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 69Uma 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 5Soluçã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:
| Campo | Descrição |
|---|---|
path | Sempre constraints/generic_constraints.json |
message | Uma 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 12Solução: Remova o campo desconhecido, mantendo apenas as cinco chaves aceitas. Veja Restrições genéricas para a gramática.
SchemaViolation
Seção intitulada “SchemaViolation”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 -100Um 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 > 0Um config.json sem training.selection:
[SchemaViolation] config.json: field training.selection: a forward-pass count is required via training.selectionDois barramentos com o mesmo id em system/buses.json:
[SchemaViolation] system/buses.json: field buses[1].id: duplicate id 0 in buses arraySoluçã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 absentslack.penalty must be > 0.0 when enabled, got {value}slack.penalty is set but slack.enabled is falseslack.penalty_basis is set but slack.enabled is falseUm 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>Regras de carga da configuração
Seção intitulada “Regras de carga da configuração”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.
| Regra | Campo | Mensagem |
|---|---|---|
Nenhuma regra iteration_limit | training.stopping_rules | must contain an iteration_limit rule |
interval_iterations ausente ou menor que 1, com checkpointing habilitado | policy.checkpointing.interval_iterations | must 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.
policy.path recusado
Seção intitulada “policy.path recusado”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:
| Campo | Descrição |
|---|---|
path | Sempre constraints/generic_constraints.json |
field | expressions[i].name — o índice da entrada em colisão |
message | name "<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 sharedSoluçã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.
Ciclo de referências entre expressões nomeadas
Seção intitulada “Ciclo de referências entre expressões nomeadas”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:
| Campo | Descrição |
|---|---|
path | Sempre constraints/generic_constraints.json |
field | Sempre expressions |
message | named-expression reference cycle detected: <a> -> <b> -> ... -> <a> |
Exemplo:
[SchemaViolation] constraints/generic_constraints.json: field expressions: named-expression reference cycle detected: fnese -> fnese_margin -> fneseSoluçã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:
| Campo | Descrição |
|---|---|
path | Sempre constraints/generic_constraints.json |
field | constraints[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.
Expressão de restrição genérica rejeitada
Seção intitulada “Expressão de restrição genérica rejeitada”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).
| Erro | Mensagem após o fragmento citado |
|---|---|
Um @name declarado nem como parâmetro escalar nem como expressão nomeada | unknown name "@<name>": no scalar parameter or named expression with this name was declared |
| Um produto de dois termos que contêm variáveis do PL | product 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 PL | division by an expression containing LP variables |
| Uma constante formada por números que divide por zero | division by zero |
| Um literal numérico grande demais para ser representado | numeric literal <text> is not finite |
| Uma parte constante em uma expressão sem operador relacional | an expression without a relational operator cannot have a constant part; put the bound in generic_constraint_bounds.parquet or use <=, >= or == |
| Dois operadores relacionais | a 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ênteses | a relational operator is only allowed at the top level |
Um < ou > isolado | bare '<' 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íveis | expression nests deeper than 256 levels |
| Um corpo de expressão nomeada com operador relacional | a 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:
| Campo | Descrição |
|---|---|
path | Sempre constraints/generic_constraints.json |
field | constraints[i].expression ou expressions[i].expression |
message | O 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 linearSoluçã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.
Entrada de parâmetro escalar rejeitada
Seção intitulada “Entrada de parâmetro escalar rejeitada”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.
| Erro | Campo | Mensagem |
|---|---|---|
Um campo de conteúdo de outro tipo, como values em um constant | scalar_parameters[i].<field> | "values" is only valid for kind "per_stage" or "seasonal", not "constant" |
Um parâmetro expression sem sua fórmula | scalar_parameters[i].expression | "expression" kind requires an "expression" field |
| Uma variável do PL na fórmula | scalar_parameters[i].expression | an LP variable cannot appear in a scalar-parameter expression |
Um @name que não é parâmetro escalar | scalar_parameters[i].expression | unknown scalar parameter "@<name>"; a named expression cannot appear in a scalar-parameter expression |
| Um operador relacional na fórmula | scalar_parameters[i].expression | a scalar-parameter expression cannot contain a relational operator |
| Uma constante que divide por zero | scalar_parameters[i].expression | division by zero |
Um ciclo de referências entre parâmetros expression | scalar_parameters | expression-parameter reference cycle detected: <a> -> <b> -> ... -> <a> |
Campos:
| Campo | Descrição |
|---|---|
path | Sempre constraints/generic_parameters.json |
field | O campo indicado na tabela acima |
message | Uma 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 expressionSoluçã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.
Argumento de patamar repetido
Seção intitulada “Argumento de patamar repetido”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:
| Campo | Descrição |
|---|---|
path | Sempre constraints/generic_constraints.json |
field | constraints[<i>].expression ou expressions[<i>].expression |
message | repeated 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.
Coluna Parquet desconhecida
Seção intitulada “Coluna Parquet desconhecida”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:
| Campo | Descrição |
|---|---|
path | O arquivo Parquet |
field | O nome da coluna não listada |
message | Uma 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_ratioemscenarios/inflow_ar_coefficients.parquet,reference_volume_hm3emsystem/hydro_energy_productivity.parquetedateemscenarios/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_m3sUma 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 columnUm 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_m3sSoluçã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).
Coluna Parquet obrigatória ausente
Seção intitulada “Coluna Parquet obrigatória ausente”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:
| Campo | Descrição |
|---|---|
path | O arquivo Parquet |
field | O nome da coluna obrigatória |
message | missing 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.
Regras de admissão da fonte de cenários
Seção intitulada “Regras de admissão da fonte de cenários”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.
| Regra | Campo | Mensagem |
|---|---|---|
openings sob simulation | simulation.scenario_source.openings | openings is only valid under training.scenario_source, not simulation.scenario_source |
historical_years sem classe historical | {section}.scenario_source.historical_years | historical_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.scheme | historical scheme is only valid for the inflow class |
seed ausente | {section}.scenario_source.seed | seed is required when any class uses out_of_sample or external scheme |
Intervalo historical_years invertido | {section}.scenario_source.historical_years | range '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 schemenovomodelo 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 sobtraining.scenario_source.historical_years: remova-o ou defina a classe de afluências com o esquemahistorical.loadouncs: use outro esquema; apenas a classe de afluências aceitahistorical.seed: adicione-a ao bloco.- Intervalo
historical_yearsinvertido: definafromnão posterior ato.
Um arquivo de árvore de aberturas declarado e ausente é reportado na fase estocástica: Arquivo da árvore de aberturas ausente.
Intervalo estimation.history_years invertido
Seção intitulada “Intervalo estimation.history_years invertido”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.
Antecedência inválida de térmica antecipada
Seção intitulada “Antecedência inválida de térmica antecipada”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_stagesnegativo. - 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 0error: [SchemaViolation] system/thermals.json: field thermals[0].anticipated_config.lead_time_hours: lead_time_hours must be finite and > 0.0, got -1error: [ParseError] system/thermals.json: parse error: data did not match any variant of untagged enum RawAnticipatedConfig at line 18 column 5error: [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 horizonUma 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.
Inversão da faixa de vertimento
Seção intitulada “Inversão da faixa de vertimento”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:
| Campo | Descrição |
|---|---|
description | Conté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 -5Soluçã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.
Capacidade negativa do canal de desvio
Seção intitulada “Capacidade negativa do canal de desvio”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:
| Campo | Descrição |
|---|---|
description | Conté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 -5Soluçã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.
InvalidReference
Seção intitulada “InvalidReference”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:
| Campo | Descrição |
|---|---|
description | Conté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 nothingSoluçã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.
DuplicateId
Seção intitulada “DuplicateId”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 plantSoluçã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.
InvalidValue
Seção intitulada “InvalidValue”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 blockSoluçã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:
| Campo | Descrição |
|---|---|
description | Conté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 requiredSoluçã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.
Limite de desvio sem canal declarado
Seção intitulada “Limite de desvio sem canal declarado”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:
| Campo | Descrição |
|---|---|
description | Conté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_hm3de uma linha fica acima domax_storage_hm3do reservatório emsystem/hydros.json, ou seumin_storage_hm3fica abaixo domin_storage_hm3do reservatório (o volume morto), além de uma tolerância relativa de1e-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 umhydro_idque o caso não declara é reportada, em vez disso, comoInvalidReference. - 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_hm3excede seumax_storage_hm3é recusado antes, comoSchemaViolationdesystem/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:
| Campo | Descrição |
|---|---|
description | Conté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 rangeNo 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.
Armazenamento inicial recusado na carga
Seção intitulada “Armazenamento inicial recusado na carga”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_hm3de uma hidrelétrica sem configuração defillingestá fora da faixa[min_storage_hm3, max_storage_hm3]da própria hidrelétrica emsystem/hydros.json, além de uma tolerância relativa de1e-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 cujomin_storage_hm3excede seumax_storage_hm3reporta, em vez disso, aqueleSchemaViolation. - Uma hidrelétrica com configuração de
fillingestá listada emstorage, ou uma hidrelétrica sem essa configuração está listada emfilling_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:
| Campo | Descrição |
|---|---|
description | Conté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.
CycleDetected
Seção intitulada “CycleDetected”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 acyclicnovomodelo 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.
DimensionMismatch
Seção intitulada “DimensionMismatch”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 0Soluçã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.
BusinessRuleViolation
Seção intitulada “BusinessRuleViolation”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 dispatchSoluçã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:
| Campo | Descrição |
|---|---|
description | Conté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 upstreamSoluçã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:
| Campo | Descrição |
|---|---|
description | Conté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:
| Campo | Descrição |
|---|---|
description | Conté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:
| Campo | Descrição |
|---|---|
description | Conté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 windowSoluçã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.
Fronteira pós-estudo desancorada ou malformada
Seção intitulada “Fronteira pós-estudo desancorada ou malformada”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_hoursde 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_boundspara 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:
| Campo | Descrição |
|---|---|
description | Conté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:
| Campo | Descrição |
|---|---|
description | Conté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:
| Campo | Descrição |
|---|---|
description | Uma 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 stageSoluçã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.
Referências por patamar de restrição genérica
Seção intitulada “Referências por patamar de restrição genérica”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
Kem 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 - 1em um estágio paralelo comK > 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:
- Um patamar de evaporação igual ou maior que
K. - Um patamar de evaporação de 1 a
K - 1em um estágio paralelo. - Uma fronteira interna de armazenamento em um estágio paralelo.
- Um patamar de armazenamento igual ou maior que
K. - 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 blockerror: [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).
Restrições genéricas com volume do estágio
Seção intitulada “Restrições genéricas com volume do estágio”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 termohydro_storage_initial,hydro_storage_final,hydro_useful_volume_initialouhydro_useful_volume_finalsem argumento de patamar, esteja ele escrito na expressão ou trazido por uma expressão nomeada; - um parâmetro
per_stage_blocklido por um coeficiente ou limite, diretamente ou por meio de parâmetrosexpression; - uma linha da restrição em
constraints/generic_constraint_bounds.parquetcomblock_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 argumenterror: [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 blockerror: [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_idSoluçã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 yearsA 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.
WarmStartIncompatible
Seção intitulada “WarmStartIncompatible”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.
ResumeIncompatible
Seção intitulada “ResumeIncompatible”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.
Bases armazenadas não utilizadas
Seção intitulada “Bases armazenadas não utilizadas”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.
SimulationPolicyIncompatible
Seção intitulada “SimulationPolicyIncompatible”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.NotImplemented
Seção intitulada “NotImplemented”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.
UnusedEntity
Seção intitulada “UnusedEntity”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.
ModelQuality
Seção intitulada “ModelQuality”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 0Os 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 inflowHydro {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 excessO 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 MWA 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.
SemanticAmbiguity
Seção intitulada “SemanticAmbiguity”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:
-
thermal_generation(N)em uma térmica antecipada. Uso dethermal_generation(N)em uma restrição genérica quando a térmicaNé uma térmica antecipada.thermal_generationrefere-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 usaranticipated_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, substituathermal_generation(N)poranticipated_decision(N). -
Tags de energia armazenada que não se cancelariam. Uma restrição referencia tags calculadas — nos coeficientes da expressão, nos seus limites (um
@emaxno lado direito conta) ou por meio de um parâmetroexpressionque as lê — em uma de duas formas:- um teto
max_stored_energy(h)junto a uma tag de produtibilidade da mesma hidrelétrica diferente deintegrated_accumulated_productivity(h)(ou um tetomax_stored_energy_mwh(h)junto a uma tag de produtibilidade em MWh diferente deintegrated_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
_mwhe_mwh_per_hm3) misturadas com tags brutas. As duas famílias diferem por um fator de ; o aviso dizConstraint "<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_productivitycomo o coeficiente correspondente amax_stored_energy, ouintegrated_accumulated_productivity_mwh_per_hm3commax_stored_energy_mwh, e mantenha cada restrição em uma única família; veja o exemplo da curva de segurança. - um teto
O aviso é impresso por novomodelo validate em sua saída legível; a saída
de sucesso de --json não traz avisos.
Tipos de falha de carga
Seção intitulada “Tipos de falha de carga”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.
IoError
Seção intitulada “IoError”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:
| Campo | Descrição |
|---|---|
path | Caminho do arquivo que não pôde ser lido |
source | Erro 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].
SchemaError
Seção intitulada “SchemaError”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:
| Campo | Descrição |
|---|---|
path | Caminho do arquivo que contém a entrada inválida |
field | Caminho, separado por pontos, do campo problemático (por exemplo, "hydros[3].bus_id") |
message | Descriçã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.
ConstraintError
Seção intitulada “ConstraintError”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:
| Campo | Descrição |
|---|---|
description | Todas 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.
Tipos da fase de preparação
Seção intitulada “Tipos da fase de preparaçã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.
ConfigValidationError
Seção intitulada “ConfigValidationError”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 presentRecusas da configuração de seleção de cortes
Seção intitulada “Recusas da configuração de seleção de cortes”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ção | Reportado como | Mensagem |
|---|---|---|
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_frequency | ConfigValidationError | config.json: configuration validation error: cut_selection config error: cut_selection.lookback_iterations (2) must be >= cut_selection.check_frequency (5) |
row_activity_tolerance negativo | ConfigValidationError | config.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 1 | ConfigValidationError | config.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 fase | StudySetupError | config.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 dynamic | StudySetupError | config.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 methodtraining.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 selectionUm 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 affectedStochasticPreparationError
Seção intitulada “StochasticPreparationError”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.
Recusas da biblioteca histórica
Seção intitulada “Recusas da biblioteca histórica”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 yearnovomodelo 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 reportnovomodelo 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.
Recusas do modelo de afluências
Seção intitulada “Recusas do modelo de afluências”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:Este é um erro do modelo estocástico.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 coefficientsnovomodelo validateo imprime após o prefixoscenarios/inflow_history.parquet: stochastic error:e encerra com código1.novomodelo runo imprime comoerror: stochastic error: invalid PAR parameters …com a dica de validação e encerra com código1. - 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.jsono registra comonegative_residual_variance. A mensagem nomeia o id da hidrelétrica e o id do período sazonal:Este é umI/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)ConstraintErrorgerado durante a montagem do modelo, de modo que chega ao comando como erro de carga.novomodelo validateo imprime com o rótulo de arquivoscenarios/e encerra com código1.novomodelo runo imprime sem o prefixoI/O error:, seguido de uma dica para executarnovomodelo validate, e também encerra com código1.
Número de aberturas do grupo de ruído
Seção intitulada “Número de aberturas do grupo de ruído”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.
Arquivo da árvore de aberturas ausente
Seção intitulada “Arquivo da árvore de aberturas ausente”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 absentExemplo: 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 absenterror: 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 permissionsSolução: Forneça scenarios/noise_openings.parquet ou declare openings
como {"source": "generated"}. Configuração
descreve a chave openings.
StudySetupError
Seção intitulada “StudySetupError”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 yearHydroModelsPreparationError
Seção intitulada “HydroModelsPreparationError”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.jsonGenericConstraintValidationError
Seção intitulada “GenericConstraintValidationError”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 tripleparameter '<name>': PerStageBlock cell (stage=<s>, block=<b>) lies outside the study's (stage, block) gridparameter '<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.parquetBoundaryReconciliationError
Seção intitulada “BoundaryReconciliationError”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 againA 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.
Erros de carga da política
Seção intitulada “Erros de carga da política”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ê”| Canal | Recusa | Checkpoint ilegível ou ausente |
|---|---|---|
novomodelo run, carga da FCF completa | Có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 completa | Có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 fronteira | Có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_policy | Nenhuma 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.
PolicySoftwareMismatch
Seção intitulada “PolicySoftwareMismatch”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.
Divergência estrutural
Seção intitulada “Divergência estrutural”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 againpolicy 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 variablegraph 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 againClasse 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.
Recusas de retomada
Seção intitulada “Recusas de retomada”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_startresume 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 retrainresume 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_startresume 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_startresume 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 retrainresume 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_startClasse 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".
Recusas de estados visitados armazenados
Seção intitulada “Recusas de estados visitados armazenados”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 havepool {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 cutSolução: Carregue um checkpoint gravado para o estudo atual ou treine uma nova política.
Recusa do conjunto de cortes da simulação
Seção intitulada “Recusa do conjunto de cortes da simulação”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 studyUm 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.
Validação do perfil do solver
Seção intitulada “Validação do perfil do solver”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.
Backend CLP: toda sobrescrita é rejeitada
Seção intitulada “Backend CLP: toda sobrescrita é rejeitada”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-measuredPara 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.
| Campo | Regra | Mensagem |
|---|---|---|
primal_feasibility_tolerance | deve ser finito | unsupported primal_feasibility_tolerance {value} for backend "highs" in phase "{phase}": value must be finite |
dual_feasibility_tolerance | deve ser finito e >= 0.0000000001 | unsupported dual_feasibility_tolerance {value} for backend "highs" in phase "{phase}": value must be finite and >= 0.0000000001 |
simplex_update_limit | deve ser <= 2147483647 | unsupported simplex_update_limit {value} for backend "highs" in phase "{phase}": value must be <= 2147483647 |
cost_perturbation | deve ser finito e >= 0 | unsupported cost_perturbation {value} for backend "highs" in phase "{phase}": value must be finite and >= 0 |
factor_pivot_threshold | deve 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_threshold | deve ser finito e >= 1.0 | unsupported 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.
Erros de execução
Seção intitulada “Erros de execução”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
3acrescenta-> check constraint bounds (hydros may have conflicting min/max storage)e-> run `novomodelo validate <CASE_DIR>` for a full diagnostic report. - Código
4acrescenta-> this may indicate a software or environment probleme-> 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.
Falhas do solver
Seção intitulada “Falhas do solver”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.
| Mensagem | Código de saída | Quando ocorre | Solução |
|---|---|---|---|
LP infeasible at stage {stage}, iteration {iteration}, scenario {scenario} | 3 | Um 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} | 3 | Um 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 unbounded | 3 | A 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} | 3 | O 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} iterations | 3 | Uma ú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} | 3 | O 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} | 3 | O 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 value | 1 | Os 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} | 3 | O 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} | 3 | O 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 0Training 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 reportResoluções que violam um limite de linha
Seção intitulada “Resoluções que violam um limite de linha”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.parquetUma 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.
Falhas da simulação
Seção intitulada “Falhas da simulação”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.
| Mensagem | Código de saída | Quando ocorre | Solução |
|---|---|---|---|
LP infeasible at scenario {scenario_id}, stage {stage_id}: {solver_message} | 3 | Um 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} | 3 | Um 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} | 4 | O 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} | 4 | A 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 panicked | 4 | A 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} | 4 | A 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 lockstep | 4 | Outro 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. |
Falhas de comunicação
Seção intitulada “Falhas de comunicação”| Mensagem | Código de saída | Quando ocorre | Soluçã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} | 4 | O 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} | 4 | Uma 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} | 1 | Na 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}) | 1 | Um 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 count | 1 | O 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) | 4 | O 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} | 4 | Um 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 inputs | 4 | Em 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} | 4 | A 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 fix | 1 | O 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/issuesFalhas na gravação das saídas
Seção intitulada “Falhas na gravação das saídas”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.
| Mensagem | Código de saída | Quando ocorre | Solução |
|---|---|---|---|
I/O error in {context}: {source} | 2 | Uma 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} | 2 | Um 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 directory | 1 | O 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} | 4 | A 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} | 2 | Uma 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} | 4 | Um 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 lockstep | 4 | Sob 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} | 4 | A 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} | 4 | A construção de um manifesto de saída falha. | Reporte o caso com a mensagem. |
ERROR simulation write error: {e} | 0 | Os 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. |
Falhas estocásticas durante uma execução
Seção intitulada “Falhas estocásticas durante uma 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).