Formato do caso
Um diretório de caso do Novo Modelo é uma pasta autocontida que reúne todos os dados de entrada
de um único estudo do sistema elétrico. novomodelo validate carrega e verifica o
diretório sem resolver o problema, e novomodelo run o carrega antes da resolução;
os erros de carga estão listados em Códigos de erro.
Os arquivos do caso são documentados da seguinte forma: config.json no final desta página, e os demais arquivos em oito páginas. O Resumo dos arquivos abaixo associa cada arquivo à sua página e seção.
Estrutura do diretório
Seção intitulada “Estrutura do diretório”my_case/├── config.json # Configuração do solver (obrigatório)├── penalties.json # Penalidades padrão globais (obrigatório)├── stages.json # Sequência de estágios e grafo da política (obrigatório)├── initial_conditions.json # Armazenamento dos reservatórios no início do estudo (obrigatório)├── post_study_stages.json # Calendário da fronteira pós-estudo + limites térmicos (opcional)├── system/│ ├── buses.json # Barramentos elétricos (obrigatório)│ ├── lines.json # Linhas de transmissão (opcional)│ ├── hydros.json # Usinas hidrelétricas (obrigatório)│ ├── thermals.json # Usinas termelétricas (opcional)│ ├── non_controllable_sources.json # Fontes intermitentes (opcional)│ ├── pumping_stations.json # Usinas elevatórias (opcional)│ ├── energy_contracts.json # Contratos bilaterais (opcional)│ ├── hydro_geometry.parquet # Tabelas de geometria dos reservatórios (opcional)│ ├── hydro_production_models.json # Configurações da função de produção FPHA (opcional)│ ├── hydro_energy_productivity.parquet # Sobrescritas de conversão de energia por usina e estágio (opcional)│ ├── fpha_hyperplanes.parquet # Coeficientes dos hiperplanos da FPHA (opcional)│ └── tailrace_curves.parquet # Curvas de jusante polinomiais de 4ª ordem por partes (opcional)├── scenarios/│ ├── inflow_history.parquet # Série histórica de vazões (opcional)│ ├── inflow_seasonal_stats.parquet # Estatísticas sazonais do modelo PAR (opcional)│ ├── inflow_ar_coefficients.parquet # Coeficientes autorregressivos do PAR (opcional)│ ├── inflow_annual_component.parquet # Componente anual do PAR(p)-A (opcional)│ ├── external_inflow_scenarios.parquet # Cenários externos de afluência (opcional)│ ├── external_load_scenarios.parquet # Cenários externos de carga (opcional)│ ├── external_ncs_scenarios.parquet # Cenários externos de NCS (opcional)│ ├── load_seasonal_stats.parquet # Estatísticas sazonais do modelo de carga (opcional)│ ├── load_factors.json # Fatores de escala da carga (opcional)│ ├── non_controllable_factors.json # Fatores de escala por patamar das NCS (opcional)│ ├── non_controllable_stats.parquet # Disponibilidade estocástica das NCS (opcional)│ ├── correlation.json # Modelo de correlação entre séries (opcional)│ └── noise_openings.parquet # Árvore de aberturas da simulação backward fornecida pelo usuário (opcional)└── constraints/ ├── thermal_bounds.parquet # Limites térmicos variáveis por estágio (opcional) ├── hydro_bounds.parquet # Limites hidrelétricos variáveis por estágio (opcional) ├── hydro_unit_group_bounds.parquet # Limites de grupos de unidades geradoras variáveis por estágio (opcional) ├── line_bounds.parquet # Limites de linhas variáveis por estágio (opcional) ├── pumping_bounds.parquet # Limites de bombeamento variáveis por estágio (opcional) ├── contract_bounds.parquet # Limites de contratos variáveis por estágio (opcional) ├── ncs_bounds.parquet # Limites de geração disponível das NCS variáveis por estágio (opcional) ├── generic_constraints.json # Restrições de PL definidas pelo usuário (opcional) ├── generic_constraint_bounds.parquet # Limites das restrições genéricas (opcional) ├── generic_parameters.json # Parâmetros nomeados para expressões de restrições (opcional) ├── penalty_overrides_bus.parquet # Sobrescritas de penalidades de barramentos por estágio (opcional) ├── penalty_overrides_line.parquet # Sobrescritas de penalidades de linhas por estágio (opcional) ├── penalty_overrides_hydro.parquet # Sobrescritas de penalidades hidrelétricas por estágio (opcional) └── penalty_overrides_ncs.parquet # Sobrescritas de penalidades das NCS por estágio (opcional)Resumo dos arquivos
Seção intitulada “Resumo dos arquivos”Obrigatório é Sim para um arquivo que todo caso deve conter; um arquivo marcado Não ainda pode ser exigido por uma configuração específica, e a respectiva seção na página indicada informa a condição ou o seu uso.
| Arquivo | Formato | Obrigatório | Página | Descrição |
|---|---|---|---|---|
config.json | JSON | Sim | Formato do caso | Configuração do solver |
penalties.json | JSON | Sim | Arquivos de penalidades | Penalidades padrão globais |
stages.json | JSON | Sim | Arquivos de estágios | Sequência de estágios e grafo da política (policy graph) |
initial_conditions.json | JSON | Sim | Arquivos de condições iniciais | Armazenamento inicial dos reservatórios |
post_study_stages.json | JSON | Não | Arquivos de estágios | Calendário da fronteira pós-estudo e limites de entrega por usina termelétrica |
system/buses.json | JSON | Sim | Arquivos das entidades do sistema | Cadastro de barramentos elétricos |
system/lines.json | JSON | Não | Arquivos das entidades do sistema | Cadastro de linhas de transmissão |
system/hydros.json | JSON | Sim | Arquivos de usinas hidrelétricas | Cadastro de usinas hidrelétricas |
system/thermals.json | JSON | Não | Arquivos das entidades do sistema | Cadastro de usinas termelétricas |
system/non_controllable_sources.json | JSON | Não | Arquivos das entidades do sistema | Cadastro de fontes intermitentes |
system/pumping_stations.json | JSON | Não | Arquivos das entidades do sistema | Cadastro de usinas elevatórias |
system/energy_contracts.json | JSON | Não | Arquivos das entidades do sistema | Cadastro de contratos bilaterais de energia |
system/hydro_geometry.parquet | Parquet | Não | Arquivos de modelos de produção | Tabelas de cota da geometria dos reservatórios |
system/hydro_production_models.json | JSON | Não | Arquivos de modelos de produção | Configurações da função de produção FPHA |
system/hydro_energy_productivity.parquet | Parquet | Não | Arquivos de modelos de produção | Sobrescritas de conversão de energia por usina e estágio |
system/fpha_hyperplanes.parquet | Parquet | Não | Arquivos de modelos de produção | Coeficientes dos hiperplanos da FPHA |
system/tailrace_curves.parquet | Parquet | Não | Arquivos de modelos de produção | Curvas de jusante polinomiais de 4ª ordem por partes com famílias de remanso |
scenarios/inflow_history.parquet | Parquet | Não | Arquivos de cenários | Série histórica de vazões |
scenarios/inflow_seasonal_stats.parquet | Parquet | Não | Arquivos de cenários | Estatísticas sazonais do modelo PAR |
scenarios/inflow_ar_coefficients.parquet | Parquet | Não | Arquivos de cenários | Coeficientes autorregressivos do PAR |
scenarios/inflow_annual_component.parquet | Parquet | Não | Arquivos de cenários | Componente anual do PAR(p)-A |
scenarios/external_inflow_scenarios.parquet | Parquet | Não | Arquivos de cenários | Realizações de cenários externos de afluência (hydro_id, stage_id, scenario_id, value_m3s) |
scenarios/external_load_scenarios.parquet | Parquet | Não | Arquivos de cenários | Realizações de cenários externos de carga (bus_id, stage_id, scenario_id, value_mw) |
scenarios/external_ncs_scenarios.parquet | Parquet | Não | Arquivos de cenários | Realizações de cenários externos de NCS (ncs_id, stage_id, scenario_id, availability_factor) |
scenarios/load_seasonal_stats.parquet | Parquet | Não | Arquivos de cenários | Estatísticas sazonais do modelo de carga |
scenarios/load_factors.json | JSON | Não | Arquivos de cenários | Fatores de escala da carga por barramento/estágio |
scenarios/non_controllable_factors.json | JSON | Não | Arquivos de cenários | Fatores de escala por patamar das NCS por fonte/estágio |
scenarios/non_controllable_stats.parquet | Parquet | Não | Arquivos de cenários | Fatores de disponibilidade estocástica das NCS |
scenarios/correlation.json | JSON | Não | Arquivos de cenários | Modelo de correlação entre séries |
scenarios/noise_openings.parquet | Parquet | Não | Arquivos de cenários | Árvore de aberturas da simulação backward fornecida pelo usuário |
constraints/thermal_bounds.parquet | Parquet | Não | Arquivos de restrições | Limites de geração térmica variáveis por estágio |
constraints/hydro_bounds.parquet | Parquet | Não | Arquivos de restrições | Limites operativos hidrelétricos variáveis por estágio |
constraints/hydro_unit_group_bounds.parquet | Parquet | Não | Arquivos de restrições | Limites de grupos de unidades geradoras variáveis por estágio e, opcionalmente, por patamar |
constraints/line_bounds.parquet | Parquet | Não | Arquivos de restrições | Capacidade de fluxo das linhas variável por estágio |
constraints/pumping_bounds.parquet | Parquet | Não | Arquivos de restrições | Limites de vazão de bombeamento variáveis por estágio |
constraints/contract_bounds.parquet | Parquet | Não | Arquivos de restrições | Limites de potência dos contratos variáveis por estágio |
constraints/ncs_bounds.parquet | Parquet | Não | Arquivos de restrições | Limites de geração disponível das NCS variáveis por estágio |
constraints/generic_constraints.json | JSON | Não | Arquivos de restrições | Restrições de PL definidas pelo usuário |
constraints/generic_constraint_bounds.parquet | Parquet | Não | Arquivos de restrições | Limites do lado direito (RHS) das restrições genéricas |
constraints/generic_parameters.json | JSON | Não | Arquivos de restrições | Parâmetros nomeados para expressões de restrições |
constraints/penalty_overrides_bus.parquet | Parquet | Não | Arquivos de penalidades | Custo de excesso dos barramentos variável por estágio |
constraints/penalty_overrides_line.parquet | Parquet | Não | Arquivos de penalidades | Custo de intercâmbio das linhas variável por estágio |
constraints/penalty_overrides_hydro.parquet | Parquet | Não | Arquivos de penalidades | Custos de penalidade hidrelétricos variáveis por estágio |
constraints/penalty_overrides_ncs.parquet | Parquet | Não | Arquivos de penalidades | Custo de corte de geração (curtailment) das NCS variável por estágio |
Convenções
Seção intitulada “Convenções”-
Ids de estágio. Toda coluna ou campo
stage_idnão nulo designa umiddeclarado emstages.json, nunca uma posição, excetoschedule[].stage_iddescenarios/correlation.json, que a amostragem fora da amostra (out-of-sample) da simulação forward e da simulação final associa pela posição (a partir de 0) entre os estágios do estudo, e as chaves de estágio de um parvaluesdeper_stageou de uma triplablock_valuesdeper_stage_blockemconstraints/generic_parameters.json, que são posições (a partir de 0) entre os estágios do estudo. Os ids dos estágios do estudo são não negativos e podem ter lacunas ou começar acima de0; os ids depre_study_stages[]são negativos. -
Ids de patamar.
block_idé o índice (a partir de 0) de um patamar dentro de seu estágio; os valores deblocks[].idde um estágio vão de0..n-1. -
Colunas Parquet. Um arquivo Parquet de entrada traz apenas as colunas listadas na respectiva tabela, obrigatórias ou opcionais. O Novo Modelo verifica os nomes das colunas de cada arquivo ao abri-lo, antes de ler qualquer linha ou verificar qualquer tipo, e recusa a primeira coluna que a tabela não lista, na ordem das colunas do arquivo, com um
SchemaViolationque a nomeia e, conforme a coluna, nomeia a coluna mais próxima que o arquivo pode trazer, lista todas elas ou dá uma instrução própria. ODataFrame.to_parquetdo 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 adicional__index_level_0__; portanto, passeindex=False. -
Tipos das colunas Parquet. Cada coluna Parquet deve ter exatamente o tipo indicado na respectiva tabela. Uma coluna de outro tipo é rejeitada na carga com
column "<name>" has type <actual> but <expected> is required, e uma coluna obrigatória ausente commissing required column "<name>". O pandas grava inteiros comoint64; portanto, converta-os (por exemplodf["stage_id"] = df["stage_id"].astype("int32")) ou passe um esquema pyarrow explícito parapa.Table.from_pandas(df, schema=schema).Os nomes dos tipos correspondem aos das bibliotecas de gravação da seguinte forma:
Tipo pyarrow polars pandas Int32pa.int32()pl.Int32int32UInt32pa.uint32()pl.UInt32uint32Float64pa.float64()pl.Float64float64Date32pa.date32()pl.Dateobjetos datetime.date(dtype object) -
Compressão. Os arquivos Parquet de entrada devem estar sem compressão ou com compressão zstd; Snappy, gzip e LZ4 são rejeitados na carga (
Parquet error: Disabled feature at compile time: snappara Snappy). Opq.write_tabledo pyarrow e oDataFrame.to_parquetdo pandas gravam em Snappy por padrão; portanto, passecompression="zstd"; owrite_parquetdo polars já usa zstd por padrão. -
$schema. Todo arquivo JSON aceita uma chave opcional$schemado tipo string para validação no editor; seu valor não é verificado. Os exemplos apontam para os esquemas da versão mais recente documentada do novomodelo (https://docs.modelossetoreletrico.org.br/schemas/<name>.schema.json, incorporados a partir do novomodelo); Esquemas JSON informa a URL de cada versão da documentação.
Campos comuns às entidades
Seção intitulada “Campos comuns às entidades”operational_start_date é obrigatório em toda entidade dos sete arquivos de cadastro: system/buses.json, system/lines.json, system/hydros.json, system/thermals.json, system/non_controllable_sources.json, system/pumping_stations.json e system/energy_contracts.json.
É uma data ISO 8601 (YYYY-MM-DD) que registra quando a entidade entra no histórico operativo do cadastro.
A data é informação de procedência e a primeira chave da ordem canônica das entidades (operational_start_date, id). As entidades são ordenadas por data e depois por id, nunca por nome; assim, renomear uma entidade não altera sua posição, enquanto um novo id ou uma nova data pode movê-la. A data não condiciona a entrada em operação: para as entidades que têm janela de operação, apenas entry_stage_id e exit_stage_id a determinam (system/buses.json não tem janela). Visão geral da modelagem dos elementos do sistema — Data de início operativo descreve a ordenação e a independência em relação à janela de operação.
config.json
Seção intitulada “config.json”config.json contém os parâmetros da execução. Apenas a seção training é obrigatória, e ela deve conter training.selection e
training.stopping_rules; todas as demais seções são opcionais.
Configuração documenta cada chave com seu tipo, valor padrão e regras de admissão;
sua seção Resolução das sementes explica como as sementes conduzem os sorteios aleatórios.
Exemplo mínimo válido:
{ "$schema": "https://docs.modelossetoreletrico.org.br/schemas/config.schema.json", "training": { "selection": { "method": "sampled", "forward_passes": 192 }, "stopping_rules": [{ "type": "iteration_limit", "limit": 200 }] }}