Pular para o conteúdo principal

Referência do YAML dos Cards

Valores provisórios nas RE 455 e RE 457 da Base Myria

As fórmulas das restrições RE 455 e RE 457 da Base Myria usam um cadastro provisório e fictício de carga líquida e de geração de pequenas usinas para as áreas AM, AP, RR, Laranjal do Jari, Jurupari e Oriximiná (campos carga_liquida_* e pq_*, marcados com perfil_provisorio: ficticio_cadastral). Esses valores não são série do ONS. Se esses limites importam para o seu estudo, use uma base própria com valores de origem conhecida e registre unidade, vigência e origem de cada valor.

Esta página descreve o formato YAML v5 dos Cards e da base. Para escolher e aplicar Cards no Portal, veja Cards. Para um exemplo pronto de cada família, veja Exemplos das famílias YAML.

Estrutura de um documento​

Base e Card usam o mesmo formato. Todo documento declara versao: 5, um tipo e um titulo, e organiza as regras em duas seções. Este Card é um ponto de partida válido:

versao: 5
tipo: card
titulo: sensibilidade-carga-sudeste
descricao: Acrescenta 1.000 MWmed de carga no Sudeste no primeiro mês.
montar:
  newave:
    SISTEMA:
      carga:
        - submercado: SE
          somar:
            mes_1: 1000
  decomp:
    DP:
      - submercado: SE
        periodo: mes_1..mes_1
        patamar: todos
        somar: 1000
antes_de_rodar:
  decomp:
    HQ:
      - HQ 35:
          limite_superior:
            - se: volume_inicial(24) < 20
              entao: 140
            - senao: _
  • tipo é base (documento completo que monta o deck) ou card (alterações aplicadas depois da base, na ordem da rodada).
  • titulo é obrigatório; descricao é opcional.
  • montar roda na montagem do deck. Uma entrada com composição cria uma estrutura; uma entrada só com seletor altera o que já existe. Vale na base e no Card: um Card de sensibilidade pode, por exemplo, criar uma restrição extra.
  • antes_de_rodar roda imediatamente antes da execução e lê o estado de partida (volume_inicial(uhe) e mes_pmo). Ela nunca cria estrutura. Veja Antes de rodar.
  • Declare só os modelos e as seções que você usa. Um modelo ou uma seção sem nenhuma família (por exemplo, só com comentários) é recusado.
  • politicas e cadastros só podem aparecer em um documento tipo: base.
  • Dentro de newave e decomp, cada chave é uma família, como newave.MODIF ou decomp.HQ. A lista completa está na tabela de famílias.
  • Usinas são sempre identificadas pelo código do arquivo do modelo: em newave, o do CONFHD.DAT; em decomp, o do bloco UH. O nome da usina pode ir num comentário (uhe: 46 # Porto Primavera).
  • Submercados são escritos pela sigla em maiúsculas (SE, S, NE, N, FC, IV), também no seletor (submercado: SE); o nome (sudeste) ou a sigla em minúsculas é recusado com invalid_submarket. Uma rota é sempre [origem, destino], como rota: [S, SE], também nos membros do AGRINT, nos termos de restrição elétrica, em sistema(S, SE, 0) e em agrint([[S, SE]], 0). O único código numérico aceito é o do nó fictício 11, que não tem sigla no deck NEWAVE ([11, SE]).
  • REEs são escritos pelo nome do REE.DAT em minúsculas (ree: sudeste). O código numérico só vale num Card, para um REE novo criado por ele (código 13 ou maior).

Como a rodada referencia os Cards​

No estudo.yaml, toda rodada executável declara deck_rules. Esse bloco não contém as regras: ele referencia documentos que o Myria já recebeu, validou e guardou no Gitea da sua organização.

Sem base própria, a rodada usa a Base Myria atual:

deck_rules:
  ajustes: []

ajustes é obrigatório, mas pode ser uma lista vazia. Com base própria e Cards, na ordem em que serão aplicados:

deck_rules:
  base:
    tipo: upload
    id: base-exemplo-202608
    sha256: bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
  ajustes:
    - tipo: upload
      id: hidrologia
      sha256: 1111111111111111111111111111111111111111111111111111111111111111
    - tipo: upload
      id: sensibilidade-carga
      sha256: 2222222222222222222222222222222222222222222222222222222222222222
  • base é opcional. Quando presente, aponta para um documento tipo: base e substitui a Base Myria.
  • ajustes aceita até 20 documentos tipo: card.
  • tipo é sempre upload.
  • id é o identificador devolvido quando o arquivo foi recebido: até 200 caracteres, começando por letra ou número, com letras, números, ponto, sublinhado, dois-pontos ou hífen.
  • sha256 tem 64 caracteres hexadecimais minúsculos e identifica exatamente o conteúdo recebido.

Qualquer mudança no arquivo gera outro id e outro sha256, e o arquivo precisa ser enviado de novo. Cada documento pode aparecer uma única vez entre a base e os Cards de uma rodada; para repetir um efeito, escreva-o em outro Card.

Não informe em deck_rules organização, repositório, caminho, branch, tag, commit, nome de catálogo nem conteúdo YAML embutido. O Myria resolve essas informações a partir do id e do sha256. Cada rodada tem exatamente uma base efetiva: a Base Myria, quando base é omitido, ou o documento indicado.

Onde os YAMLs ficam​

Os arquivos de regras ficam na pasta regras/ do repositório arquivos de cada organização:

org-myria/arquivos/regras/base.yaml
org-myria/arquivos/regras/cards/
org-myria/arquivos/regras/cadastros/
org-myria/arquivos/regras/newave_onsccee.yaml
org-myria/arquivos/regras/decomp_onsccee.yaml
org-{slug}/arquivos/regras/bases/
org-{slug}/arquivos/regras/ajustes/
org-{slug}/arquivos/regras/fontes/
org-{slug}/arquivos/regras/cadastros/
  • regras/base.yaml, na org-myria, é a Base Myria: a versão mais recente em main é a base oficial.
  • regras/cards/, na org-myria, guarda os Cards oficiais do catálogo Myria.
  • regras/cadastros/, na org-myria, guarda os cadastros oficiais lidos pela Base Myria. Uma organização com base própria mantém os seus cadastros no próprio repositório, no caminho que a base declarar (por convenção, também em regras/cadastros/).
  • newave_onsccee.yaml e decomp_onsccee.yaml são os perfis oficiais da conversão de decks ONS para CCEE.
  • regras/bases/ e regras/ajustes/ recebem as bases e os Cards enviados pela sua organização, já validados.
  • regras/fontes/ guarda o arquivo original de cada envio (YAML ou planilha Excel), como foi recebido.

Ao receber um YAML pelo Portal ou pela API, o Myria publica o documento na pasta correspondente ao tipo (bases/ ou ajustes/), guarda o original em fontes/ e fixa o commit exato. A pasta regras/exemplos/ da org-myria é reservada e pode estar vazia; os exemplos mantidos pela Myria estão em Exemplos das famílias YAML.

Base própria​

Você pode substituir a Base Myria por um documento tipo: base completo. O caminho mais seguro é partir de uma cópia da Base Myria publicada no Gitea e alterar só o que você precisa. Uma base própria precisa declarar:

  1. As seis listas de restrições DECOMP em montar, mesmo que vazias: decomp.RI, decomp.IA, decomp.RE, decomp.HV, decomp.HQ e decomp.HE. Elas são a única fonte dessas restrições na rodada: o Myria descarta as restrições desses seis blocos que vieram no DADGER de entrada e as reconstrói a partir da base. Os Cards são aplicados depois. A forma de cada criação está em Restrições da base.
  2. Todas as políticas de construção, em politicas.newave e politicas.decomp (veja abaixo). O montador não completa política ausente: falta de uma delas bloqueia a montagem com o nome da política na mensagem.
  3. O bloco cadastros, com as seis chaves e os arquivos presentes no repositório arquivos da sua organização. Veja Cadastros oficiais.

A política do gerenciador de PLs do NEWAVE é a primeira conferida, já no envio do arquivo:

politicas:
  newave:
    gerenciador_pls: desligar   # ou manter

desligar zera os cinco flags GER.PLs E NV1 E NV2 do DGER.DAT; manter preserva o DGER de entrada. Um Card não pode redefinir essa política. As fontes de ADTERM e DADGNL não são políticas da base: elas são escolhidas na configuração da rodada.

As demais políticas são os parâmetros de construção que o montador escreve no DGER e no DADGER e as regras de rolagem. Na Base Myria (os itens com [...] estão resumidos; a lista completa está no arquivo publicado):

politicas:
  newave:
    dger:
      calcula_volume_inicial: 1          # CALCULA VOL.INICIAL
      earm_inicial_por_ree: zerar        # zerar | manter
      arquivos_de_cortes:                # TRATA ARQS CORTES
        gerar_arquivo_unico: 1
        manter_arquivos_por_periodo: 1
        periodos: [mes_2, mes_3, 60]     # mes_1 é o PMO; números são períodos NEWAVE
    extensao_do_horizonte:               # ano novo que entra no horizonte na rolagem
      arquivos_anuais:
        regra: repetir_ultimo_ano        # unica regra disponivel
        arquivos: [C_ADIC, CURVA, CVAR, DSVAGUA, EXPT, PATAMAR, SISTEMA, TERM, VOLUMES_REFERENCIA]
      cvu_estrutural: extrapolar_linear  # ou repetir_ultimo_ano
      vigencia_sem_fim: fim_do_horizonte # RE, CLAST e EXPT sem fim; ou erro
    correspondencia_decomp:              # como o EARM do DECOMP chega ao CONFHD
      postos: {251: 21, 255: 148, 277: 272}    # posto do CONFHD -> UHE do DECOMP
      usinas_derivadas: [{uhe: 291, origem: 251, divisor: 0.55}]
      usar_inicial_se_extremo: [27, 90, 155]   # EARM 0% ou 100% vira o Inicial
    earm:
      fonte_por_modo: {newave_copy_only: keep_base, newave_monthly_roll: decomp, newave_direct_runtime: keep_base}
    rolagem:
      ree_fim_individualizado_meses_apos_pmo: 12   # data hibrida do REE.DAT
      termicas_sem_dado: {POTEF: 0, FCMAX: 100, TEIFT: 0, IPTER: 0, GTMIN: 0}
  decomp:
    UE: [...]               # estações de bombeamento; submercado pela sigla
    RQ: {rees: [sudeste, madeira, tpires, itaipu, parana, sul, nordeste, norte, bmonte, man-ap, iguacu, prnpanema], percentual_semanas: 100, percentual_mes_estocastico: 0}
    CX: [...]               # acoplamento de complexos NEWAVE × DECOMP
    vazoes_laterais: [...]  # registros VL, VU e VA
    VI: {herdar_do_dadger_base: [{uhe: 156, nome: TRES MARIAS}, {uhe: 162, nome: QUEIMADO}]}
    IR: [{tipo: NORMAL, parametros: [17, 61]}]
    CI: [{numero: 0, submercado: S, estagio: 1, patamares: [...]}]   # contratos de importação e exportação; submercado pela sigla
    GEVAZP: {historico_de_vazoes_anos_antes: 2, agregacao: 6, ordem_maxima_parp: 11, ..., estrutura_da_arvore: herdar_do_dadger_base, estudo_decomp: 0, imprime_prevs: 0, imprime_vazpast: 0, tendencia_hidrologica_vazpast: 0}
    UH: {promover_newave_ate: mes_2}   # UHE NE com maquina no EXPH ate este mes entra no UH
    SB: [{numero: 1, sigla: SE}, {numero: 2, sigla: S}, {numero: 3, sigla: NE}, {numero: 4, sigla: N}, {numero: 11, sigla: FC}]
    CD: {numero: 1, nome: 1PDEF, submercados: [SE, S, NE, N], limites_percentuais: [100, 100, 100], custo: primeira_cd_do_dadger_base}
    TX: {valor: herdar_do_dadger_base}   # ou um número
    GP: {valor: herdar_do_dadger_base}
    NI: {valor: herdar_do_dadger_base}
    AR: {estagios: [1]}                  # estágios com CVaR
    EV: {modelo: 1, volume_referencia: INI}
    FD: {indisponibilidade_hidr: somente_ultimo_estagio}   # ou todos_os_estagios
    DP: {carga: sistema_mais_c_adic}     # ou sistema
    PQ:
      estagios_do_mes: {geracao_distribuida: media_ponderada_por_horas, demais_fontes: mes_pmo}
      ultimo_estagio: mes_seguinte
      fontes_em_todos_os_estagios: [UFVgd]
      arredondamento: truncar            # ou arredondar
    CT: {gmax_ip_a_partir_do_ano: 2, cvu_zero: gmax_igual_gtmin, gtmin_acima_do_gmax: reduzir_gtmin}
    formacao_de_restricoes: {refazer_em: [rv0]}   # revisões que refazem RI/IA/RE/HV/HQ/HE
    AC: {tucurui: {faixas_sobre: pre_ajuste}}     # ou efetivo
    DADGNL: {bengnl_despacha_quando: beneficio_maior_que_custo}

RQ.rees usa o nome do REE no REE.DAT e UE.submercado, a sigla do submercado (SE, S, NE, N ou FC), como no resto do YAML.

No DECOMP, herdar_do_dadger_base copia o registro do DADGER de entrada; se ele não existir, a montagem falha. CD.custo: primeira_cd_do_dadger_base copia o custo da primeira linha CD do DADGER de entrada; um número fixa o custo. PQ define o valor de cada estágio: as semanas do mês do PMO usam o mês do PMO ou a média de mês anterior, PMO e mês seguinte ponderada pelas horas do estágio (fontes de geração distribuída); o último estágio usa o mês seguinte; as fontes de fontes_em_todos_os_estagios são escritas em todas as semanas, as demais só no primeiro e no último estágio. CT.gmax_ip_a_partir_do_ano conta a partir do primeiro ano do MANUTT.DAT. AC.tucurui.faixas_sobre: pre_ajuste avalia as faixas de Tucuruí no volume inicial antes dos Cards; efetivo usa o volume final do EARM, depois dos Cards. As faixas, as máquinas por conjunto e o texto de cada faixa ficam no cadastro decomp-ac-v1.yaml. formacao_de_restricoes.refazer_em lista as revisões em que RI, IA, RE, HV, HQ e HE são reconstruídos a partir da base.

DADGNL.bengnl_despacha_quando define o criterio usado ao aplicar um BENGNL externo: beneficio_maior_que_custo despacha somente quando o beneficio medio supera o custo medio; beneficio_maior_ou_igual_ao_custo inclui a igualdade. O Myria le essa politica da Base selada da rodada. Politica ausente ou fonte adulterada bloqueia a aplicacao; o recibo registra o criterio utilizado.

O número de anos do horizonte NEWAVE é o No. DE ANOS DO EST do DGER.DAT base. Na virada do ano, só os arquivos listados em arquivos_anuais ganham o ano novo; arquivo fora da lista ou regra desconhecida bloqueia a montagem. Uma vigência sem fim em RE, CLAST ou EXPT vai até dezembro do último ano do horizonte base (vigencia_sem_fim: fim_do_horizonte) ou bloqueia a montagem (erro). O bloco CT do DECOMP lê do mesmo jeito os registros EXPT e CLAST com fim em branco: eles valem até o fim do horizonte do NEWAVE, e uma linha inválida desses arquivos bloqueia a montagem em vez de ser pulada. No ADTERM, o lag das usinas GNL vem do ADTERM.DAT base; usina GNL sem lag nele bloqueia a montagem. O REE.DAT preserva a linha FICT. INDIVIDUAL. do deck base. O EARM do NEWAVE agrupa os REEs pelos nomes e submercados do REE.DAT da rodada, e o Myria confere que os nomes de REE usados no YAML batem com esse arquivo.

Os períodos de arquivos_de_cortes contam a partir de janeiro do primeiro ano do estudo, como no próprio DGER.DAT; mes_2 e mes_3 são o primeiro e o segundo mês depois do PMO.

Alterar valores​

Cada entrada de montar faz uma única coisa. Para um valor que já existe, use uma das operações aceitas pelo campo:

  • definir informa o valor final, que precisa respeitar a faixa física do campo;
  • somar informa um delta na unidade do campo; o delta pode ser negativo;
  • multiplicar informa um fator sem unidade.

Em somar e multiplicar, o Myria lê o valor atual, aplica a operação e valida o resultado. Assim, uma faixa como 0..1 limita o valor final, mas não impede somar: -0.1 nem multiplicar: 1.2 se o resultado continuar válido.

Nos Cards DECOMP, periodo: mes_1..mes_1 seleciona todos os estágios do primeiro mês da rodada, e periodo: 2026-10..2026-12 seleciona os estágios que pertencem a essas competências. O Myria usa o calendário do próprio DADGER, por isso o Card não depende da quantidade de semanas do mês. Para escolher estágios avulsos, periodo também aceita estagio_7 (por exemplo, o mês estocástico), estagio_1..estagio_3 ou uma lista como [estagio_1, estagio_3]. periodo é a única chave de faixa de tempo. Meses são sempre um intervalo: um mês só é mes_1..mes_1 ou 2026-10..2026-10.

Para uma alteração valer somente em certas rodadas, acrescente aplicar_em à entrada de montar. pmo recebe um mês YYYY-MM ou uma lista sem repetições. No DECOMP, rv pode restringir a revisão (inteiro de 0 a 5 ou lista). O ano faz parte da seleção: janeiro/2027 não inclui janeiro/2028. Fora da seleção a entrada não altera o deck. Sem aplicar_em, o comportamento continua o mesmo.

montar:
  newave:
    C_ADIC:
      - nome: ANDE
        aplicar_em: {pmo: '2027-01'}
        definir: {'2027-03': 3005}
      - nome: ANDE
        aplicar_em: {pmo: ['2027-02', '2027-03']}
        definir: {'2027-03': 3305.5}

Neste exemplo, o mesmo dado de março recebe valores diferentes conforme o PMO da rodada. aplicar_em seleciona as rodadas; periodo e os mapas de valores selecionam os meses ou estágios alterados dentro delas. Assim, aplicar_em: {pmo: '2026-10', rv: 2} seleciona apenas a rodada RV2 de outubro, enquanto periodo: rv_2..rv_2 seleciona a semana RV2 no horizonte da rodada. As duas seleções podem ser combinadas. A conferência de referências avisa quando a entrada fica fora da seleção. Se a referência não informar o PMO ou a revisão necessária, a conferência indica essa limitação; a aplicação continua exigindo o calendário do deck da rodada.

O seletor vale nas alterações com definir, somar ou multiplicar de montar e nas criações de newave.MODIF; não se aplica às outras criações nem a antes_de_rodar. O calendário é lido do deck da rodada. Ausência desse contexto é erro, nunca autorização para aplicar todas as variantes. Duas declarações do mesmo documento que atingem a mesma célula continuam inválidas quando suas seleções se sobrepõem.

Em newave.MODIF, uma criação pode declarar se_existir: manter. Para um campo temporal, isso preserva o registro que já esteja vigente no mês pedido, inclusive quando ele começou antes. Se não houver registro vigente, a criação usa o valor informado. Nos campos constantes, preserva o registro existente. Sem essa opção, a criação continua recusando um registro duplicado. Esse passo de inicialização pode preceder uma alteração no mesmo Card; duas alterações numéricas sobre a mesma célula continuam sendo conflito.

montar:
  newave:
    MODIF:
      - aplicar_em: {pmo: '2027-01'}
        criar:
          uhe: 7
          campo: vazao_turbinada_maxima
          mes: mes_1
          valor: 99999
          se_existir: manter
      - aplicar_em: {pmo: '2027-01'}
        uhe: 7
        campo: vazao_turbinada_maxima
        definir: {mes_1: 500}

Aqui, 99999 é o limite não vinculante de turbinação máxima usado na inicialização; ele não substitui um limite já vigente. A alteração de um mês restaura o valor anterior no mês seguinte, dentro do horizonte do estudo.

Em EXPT, definir também pode acrescentar um registro para um mês sem valor explícito, desde que a usina exista no cadastro do deck. Somente o campo e o mês informados são acrescentados; os demais dados permanecem preservados. somar e multiplicar exigem um valor EXPT de origem. Registros com fim explícito conservam esse fim quando alterados.

Meses relativos (mes_N) contam a partir do PMO da rodada onde o Card é aplicado: mes_1 é o mês do PMO, mes_2 o seguinte. Valem em todas as famílias com período mensal, nos dois modelos: em periodo (periodo: mes_2..mes_4), como chave de mapa mensal (somar: {mes_2: 1000}, por exemplo em SISTEMA, CLAST, C_ADIC, CURVA, PATAMAR, AGRINT, RESTRICAO_ELETRICA) e em MODIF ao criar um registro (criar: {..., mes: mes_2}). Prefira mes_N quando o ajuste é "no 2º mês" ou "nos próximos 6 meses": o mesmo Card serve a qualquer rodada.

Para ir até o fim do horizonte, escreva fim no lugar do último mês: periodo: mes_3..fim (do 3º mês do PMO em diante), mes_1..fim (todo o horizonte) ou 2026-06..fim. O fim é resolvido na montagem: no NEWAVE, o último mês do horizonte do DGER.DAT da rodada; no DECOMP, o último estágio do DADGER. Assim o mesmo Card vai até o fim em rodadas com horizontes diferentes, e um início depois do horizonte da rodada não muda nada. No DECOMP também vale estagio_2..fim. fim só aparece em periodo (não em chave de mapa nem em criar); em famílias de mapa mensal, como SISTEMA.carga, use periodo com a operação (periodo: mes_3..fim e somar: 1000). Escolhemos fim como o segundo ponto do intervalo (inicio..fim) para manter a forma única de período; estagio_N..fim não existe no NEWAVE.

No DECOMP, estagio_N também é relativo à rodada (o estágio 1 é a primeira semana dela). Para cravar a semana de uma revisão do mês do PMO, use periodo: rv_2..rv_2 (ou rv_1..rv_3): numa rodada RV0 a RV2 é o estágio 3, numa RV2 é o estágio 1, e numa rodada que já passou da RV2 o Card não muda nada. rv_N só existe no DECOMP.

O patamar de carga é escrito pelo nome: patamar: pesada, media, leve ou todos, ou uma lista como [pesada, media] (todos não entra em lista). Mapas por patamar usam os mesmos nomes como chave ({pesada: 1200, media: 1150, leve: 1100}), inclusive patamares ao criar uma linha CT, DP, PQ ou IA. O patamar de déficit de newave.SISTEMA.custo_deficit não é patamar de carga e continua numérico.

O valor volta ao anterior depois do período​

No MODIF.DAT e nos limites de RE, HV e HQ do DADGER, um registro vale até o próximo registro do mesmo campo. Por isso, quando um Card altera um mês (campos temporais de newave.MODIF) ou um estágio (limites de decomp.RE, decomp.HV e decomp.HQ) e o mês ou estágio seguinte não tinha registro próprio, o Myria escreve nele o valor que vigorava antes da alteração. Assim, o Card muda só o período escolhido e o valor anterior volta depois dele, dentro do horizonte do estudo (NEWAVE) ou da restrição (DECOMP). Os limites calculados pela própria formação da base não recebem essa restauração: eles já declaram cada estágio.

Criar estruturas​

Em RI, IA, RE, HV, HQ, HE, SISTEMA, AGRINT e RESTRICAO_ELETRICA, a criação usa uma forma compacta: a chave da entrada é a identidade da estrutura e a composição fica direto no corpo.

FamíliaChave da entradaExemplo
decomp.RIRI <uhe>, com o código da usinaRI 66
decomp.IAIA <origem>-<destino>, com as siglasIA N-FC
decomp.RE, HV, HQ, HE<família> <número> ou um nome em kebab-caseRE 447, geracao-minima-tres-marias
newave.RERE <número> ou o nome da restriçãolimite-eletrico-norte-sudeste
newave.AGRINT, newave.RESTRICAO_ELETRICAo nome da formação, em kebab-caserecebimento-sul-sudeste

Em RE, HV, HQ e HE do DECOMP, o número da chave é o número físico escrito no DADGER; para uma restrição nova sem número fixo, use um nome em kebab-case como chave, e o Myria aloca o número. nome no corpo é opcional e, quando presente, confere o alvo. Os limites ficam em limites, por chave de tempo:

montar:
  decomp:
    RE:
      - geracao-minima-tres-marias:
          comentarios: ["Geração mínima de Três Marias."]
          uhe: 156
          limites:
            primeiro_estagio: [100, _]

Uma restrição com valores fixos numa faixa de estágios usa periodo de estágios, e limites passa a ser o par fixo (em HE, periodo com volume_minimo, penalidade e tratamento):

montar:
  decomp:
    HQ:
      - vazao-turbinada-exemplo:
          vazao: [7, QTUR]
          periodo: estagio_1..estagio_7
          limites: {limite_inferior: _, limite_superior: 500}

Uma entrada sem composição altera a restrição que já existe com aquela chave:

montar:
  decomp:
    HQ:
      - HQ 87:
          nome: vazao-defluente-p-primavera   # confere o alvo
          campo: limite_inferior
          periodo: 2026-10..2026-12
          patamar: todos
          definir: 1900

Nas famílias DECOMP RE, HV e HQ, uma alteração só é aplicada quando a restrição existe como registro ativo no deck. Se o número estiver ausente ou já comentado/removido, o comando não altera o arquivo nem cria a restrição, e a rodada mostra um aviso de entrada ignorada com o motivo. Isso permite herdar o mesmo Card nas RVs seguintes. Nomes precisam continuar resolvidos no plano, e identidades ambíguas ou inconsistentes são erros. O seletor restricao: não existe no v5: a chave da entrada é sempre o alvo.

- criar: nas famílias sem chave​

As famílias de registro sem número próprio, como newave.MODIF, newave.CLAST, newave.EXPT, newave.RE (restrição nova sem número), decomp.DP ou decomp.PQ, identificam a linha alterada pelos seletores (uhe, ute, submercado, campo...). Nelas, criar uma linha que não existe usa uma entrada - criar: com o registro final completo, sem definir, somar nem multiplicar dentro:

montar:
  decomp:
    DP:
      - criar:
          submercado: SE
          periodo: estagio_1..estagio_7
          patamares:
            pesada: {carga: 50000, duracao: 0.30}
            media: {carga: 52000, duracao: 0.40}
            leve: {carga: 51000, duracao: 0.30}

O CT do DECOMP não aceita UTE nova: o DECOMP só conhece as UTEs do próprio bloco CT, então altere a UTE existente.

Em RE, HV, HQ e HE do DECOMP, - criar: é recusado: a chave da entrada já identifica a restrição, e a composição no corpo indica a criação, formada ou com valores fixos (periodo + limites).

Em RI, IA, AGRINT e RESTRICAO_ELETRICA há duas formas, conforme a origem dos valores:

  • a criação formada, com valores calculados a partir dos arquivos da rodada, usa a chave (RI 66:, IA SE-NE: ou o nome da formação), como faz a Base Myria (veja Restrições da base e Formação sistêmica do NEWAVE);
  • a criação com valores fixos num periodo, por patamar, usa - criar: com nome, a identidade (uhe e submercado, rota, membros ou termos), periodo e patamares ou limites.

Os exemplos das famílias trazem um exemplo de criação válido para cada família que permite criação.

Limites ausentes​

Pares de limites usam [inferior, superior], e _ indica limite ausente. As chaves de tempo de limites são primeiro_estagio, ultimo_estagio, todos_estagios, por_mes_decomp e estagio_N. Um limite declarado vale até a próxima chave de tempo. Veja Restrições da base para limites calculados.

Como o DADGER não aceita um par vazio, o Myria escreve os limites ausentes assim:

  • em LU (RE), o inferior ausente vira -1e21 e o superior ausente vira 1e21;
  • em LQ e LV, o inferior ausente fica em branco; se os dois lados estiverem ausentes, o superior é escrito como 1e21.

Ao reler o deck, esses valores voltam a ser tratados como ausentes. Um par com um limite finito mantém o outro lado vazio.

Comentários de RE, HV, HQ e HE​

Ao criar uma restrição nessas famílias, você pode declarar de um a quatro comentários. Eles são escritos na ordem declarada, logo antes do primeiro registro da restrição no DADGER:

montar:
  decomp:
    HQ:
      - vazao-minima-exemplo:
          comentarios:
            - "Vazão defluente mínima da UHE de exemplo."
            - "Fonte: premissa operativa fixada da rodada."
          vazao: [7, QDEF]
          limites:
            primeiro_estagio: [100, _]

Não inclua o prefixo &: o Myria o acrescenta. Cada comentário é uma linha sem espaços nas pontas, com caracteres Latin-1 e até 240 bytes. No DADGER, os acentos são convertidos para ASCII (Vazão vira Vazao) sem mexer nos campos posicionais. Comentários não mudam identidade, composição nem limites, mas mudam o conteúdo do arquivo.

Quando a base reconstrói RE, HV, HQ e HE, os comentários que vieram no DADGER de entrada saem junto com os registros antigos; ficam só os do YAML. O mesmo vale para MP: o bloco é refeito por inteiro, sem os comentários anteriores.

Restrições da base​

Esta seção mostra como escrever, numa base própria, as criações de RI, IA, RE, HV e HQ cujos limites são calculados a partir dos arquivos da rodada. Os mesmos recursos valem num Card que crie uma restrição.

Criação de RI e IA​

RI <uhe> cria a restrição de Itaipu (ou de outra usina binacional) a partir de dados e expressões. O corpo exige uhe (igual ao da chave), submercado, dados e os cinco campos minimo_60, maximo_60, minimo_50, maximo_50 e carga_adicional; nome é opcional. Cada campo é um número ou uma expressão, avaliada em cada estágio e patamar. carga_adicional é calculado primeiro e pode ser usado pelos outros campos:

montar:
  decomp:
    RI:
      - RI 66:
          nome: intercambio-itaipu-ande
          uhe: 66
          submercado: SE
          dados:
            ugs_50: 5
            ugs_60: 4
            pmin_ug: 500
            conversores_minimos: 4
            pmin_conversora: 78.3
          minimo_60: dados.ugs_60 * dados.pmin_ug
          maximo_60: 7000
          minimo_50: max(dados.ugs_50 * dados.pmin_ug, carga_adicional + dados.conversores_minimos * dados.pmin_conversora)
          maximo_50: 7000
          carga_adicional: patamarizar(c_adic(ANDE) + c_adic(ITAIPU), SE)

IA <origem>-<destino> cria o limite de intercâmbio entre dois submercados. A chave define a rota; rota no corpo é opcional e, se aparecer, tem de ser a mesma da chave. O corpo exige de_para (sentido origem → destino) e para_de (sentido contrário). Cada sentido aceita:

  • _, sem limite;
  • uma expressão, como sistema(SE, NE), avaliada em cada estágio e patamar;
  • um mapa por mês relativo com um valor ou um vetor por patamar ({mes_1: [8932, 5632, 9232], mes_2: [...]}); um mês do horizonte sem chave bloqueia a montagem;
  • {restricao_eletrica: {termos: ...}}, que lê o limite da restrição elétrica NEWAVE com esses termos no mês do estágio.
montar:
  decomp:
    IA:
      - IA SE-NE:
          de_para: sistema(SE, NE)
          para_de: sistema(NE, SE)
      - IA SE-IV:
          de_para:
            mes_1: [8932, 5632, 9232]
            mes_2: [8932, 5632, 9232]
          para_de:
            restricao_eletrica:
              termos:
                intercambio: [S, SE]
                uhe: [66, 0.5]

Num Card, RI 66: ou IA SE-NE: sem os campos de criação altera a estrutura formada (por exemplo, campo: carga_adicional com somar), e estado: desligado a desativa.

Limites de RE, HV e HQ​

Na criação de RE, HV e HQ, a composição usa:

  • RE: uhe/uhes, ute/utes, intercambio/intercambios e contrato/contratos. Um termo pode levar coeficiente ([251, -1], [SE, NE, -1]); em ute e contrato, [codigo, submercado, coeficiente?] com o submercado pela sigla ([21, N]); em uhe, [66, 1, 50] indica a frequência de Itaipu.
  • HV: volume ou volumes; HQ: vazao ou vazoes, com termos [uhe, variavel, coeficiente?]. As variáveis são QDEF, QTUR, QVER, QDES, QBOM, VARM, VDEF, VDES e VBOM; o coeficiente omitido vale 1.

Em limites, cada chave de tempo recebe um par, uma matriz de pares por patamar ([[360, _], [180, _], [180, _]]) ou uma expressão:

  • primeiro_estagio, ultimo_estagio e estagio_N marcam um estágio; todos_estagios vale para todos;
  • por_mes_decomp: {mes_1: [...], mes_2: [...]} começa no primeiro estágio de cada mês relativo;
  • um valor vale até a próxima chave, e os limites precisam cobrir todo o horizonte da rodada.

O corpo também aceita:

  • dados: constantes, mapas e séries locais, consultados por dados.campo, dados[chave] ou dados[mes_1]. Uma série de 12 números é indexada pelo mês civil; um mapa, por mes_N relativo, pela competência (2026-10) ou pelo mês civil.
  • proporcionalizar: true: um limite que resulta numa série civil de 12 números é ponderado pelos dias de cada mês que o estágio cobre.
  • Fontes ligadas à restrição: agrint: [[SE, NE], [11, NE]] (grupo do AGRINT.DAT), restricao_eletrica: {termos: ...} (restrição elétrica NEWAVE) ou ia: [NE, SE] (o IA formado nessa rota). A fonte é lida na expressão pelo mesmo nome, por mês e patamar (agrint[mes_1][patamar]), ou, no caso de ia, por ia(), que devolve o par [_, limite]. Uma restrição com ia e sem limites usa todos_estagios: ia().
  • calculo, um cálculo nomeado chamado por calculo() nos limites: retorno: escalar com expressao, ou retorno: limite com limite_inferior e limite_superior. O cálculo fechado curva_de_volume é descrito em Curva de volume de Tucuruí.
montar:
  decomp:
    RE:
      - RE 461:
          nome: geracao-hidraulica-itaipu-50-hz
          uhe: [66, 1, 50]
          dados:
            max_ffzin: {mes_1: 3132, mes_2: 3132}
          calculo:
            retorno: limite
            limite_inferior: ri(66, 50).minimo
            limite_superior: ri(66).carga_adicional + dados.max_ffzin[mes_do_estagio]
          limites:
            primeiro_estagio: calculo()
            ultimo_estagio: calculo()
      - RE 457:
          uhes: [204, 277]
          intercambios: [[SE, N], [N, SE, -1]]
          dados:
            fixo: {mes_1: [5000, 5000, 5000], mes_2: [5000, 5000, 5000]}
            carga_area: 700
          calculo:
            retorno: escalar
            expressao: carga_liquida(N) - dados.carga_area - pq(N) + patamar(dados.fixo[mes_do_estagio])
          limites:
            todos_estagios: [_, calculo()]
      - RE 409:
          intercambio: [NE, SE]
          ia: [NE, SE]
          limites:
            todos_estagios: ia()
    HV:
      - HV 73:
          volume: [124, VARM]
          dados: [372.69, 372.69, 407.78, 448.67, 448.67, 430.55, 414.53, 400.05, 386.08, 372.69, 372.69, 372.69]
          proporcionalizar: true
          limites:
            primeiro_estagio: [81.49, 'dados[mes_1]']
            ultimo_estagio: [200, 'dados[mes_2]']

Expressões de montar no DECOMP​

As expressões das criações do DECOMP (RI, IA e limites de RE, HV e HQ) são avaliadas em cada estágio e patamar e aceitam somente:

NomeO que é
dados, dados.campo, dados[chave]Os dados declarados na própria entrada.
mes_1, mes_2O primeiro e o segundo mês da rodada; servem de índice em dados e nas fontes.
mes_do_estagioO mês do estágio avaliado.
patamarO patamar avaliado.
agrint, restricao_eletricaAs fontes declaradas na entrada, lidas por mês e patamar.
sistema(origem, destino)Intercâmbio mensal do SISTEMA.DAT multiplicado pelo fator do patamar no PATAMAR.DAT.
c_adic(nome)A carga adicional nome do C_ADIC.DAT no mês do estágio.
patamarizar(valor, submercado)Distribui um valor médio mensal no patamar, pelos fatores de carga do submercado.
carga_liquida(submercado)A carga final do DP no estágio e patamar, depois dos Cards.
pq(submercado)A geração final do PQ no estágio e patamar, depois dos Cards.
patamar(vetor)O elemento do vetor [pesada, media, leve] do patamar avaliado.
ri(uhe[, 50 | 60]).campoUm campo do RI formado na mesma base; .minimo é o mínimo de 50 Hz ou da frequência pedida.
ia()O limite do IA ligado por ia: [origem, destino].
calculo()O calculo declarado na entrada.
min(...), max(...)Mínimo e máximo.

São aceitos números, +, -, *, /, sinais, atributos e índices. Não há texto livre, comparação, chamada de outra função, acesso a arquivo nem valor padrão implícito. volume_inicial(...) e mes_pmo são recusados em montar com o erro state_in_build: o estado de partida só existe em antes_de_rodar. Uma dependência ausente (por exemplo, um RI ou IA não formado, ou um mês sem valor em dados) bloqueia a montagem.

As formações do NEWAVE (AGRINT e RESTRICAO_ELETRICA) têm um vocabulário próprio, descrito em Formação sistêmica do NEWAVE.

Desativar, comentar ou remover​

estado desliga, comenta ou remove uma estrutura existente. A entrada usa a mesma chave da estrutura:

montar:
  newave:
    RE:
      - limite-recebimento-sul:
          estado: desligado
    AGRINT:
      - fns-fnese-xingu-para-sudeste:
          estado: desligado
    RESTRICAO_ELETRICA:
      - recebimento-sul-sudeste:
          estado: removido
      - termos:
          intercambio: [11, SE]
          uhes: [261, 257]
        estado: removido

  decomp:
    RE:
      - RE 449:
          estado: comentado
    IA:
      - IA N-FC:
          estado: desligado
  • desligado desativa a estrutura nas famílias que aceitam desativação;
  • comentado mantém o registro no arquivo como comentário, com o cabeçalho e todas as linhas de continuação;
  • removido remove o mesmo grupo de linhas;
  • a entrada tem apenas a chave (ou o seletor) e o estado; não pode ter definir, somar, multiplicar nem campos de criação;
  • não há edição livre por linha, texto ou coluna.

Uma restrição elétrica NEWAVE é identificada pelos termos da fórmula ou pelo nome da formação que a criou. A única exceção é comentar ou remover um registro que já existe no deck: RESTRICAO_ELETRICA 10: {estado: comentado} (ou removido) usa o número do restricao-eletrica.csv; com outro estado ou com uma operação, essa chave é recusada (invalid_family_selector). AGRINT criado por nome também pode ser desligado pelo nome. comentado e removido estão disponíveis somente em decomp.RE e newave.RESTRICAO_ELETRICA. Para manter uma estrutura, não a desligue; em uma base própria, crie-a em montar.

Antes de rodar​

antes_de_rodar guarda as regras que dependem do estado de partida da rodada. Elas rodam depois de toda a montagem (base e Cards), imediatamente antes da execução. As condições leem mes_pmo (o mês civil do PMO, de 1 a 12) e volume_inicial(uhe), o V.INIC% de partida da usina. Além delas, só min(...) e max(...) são aceitas; funções de deck como sistema(...) ou agrint(...) não existem aqui. Uma condição que não lê nenhum dos dois é recusada: regra que não depende do estado de partida vai em montar.

MODIF.DAT por UHE​

No NEWAVE, antes_de_rodar.newave.MODIF escreve campos do MODIF.DAT com meses relativos ao PMO. Cada UHE tem uma entrada, e definir é uma cadeia se/senao_se/senao:

antes_de_rodar:
  newave:
    MODIF:
      - uhe: 24   # Tres Marias
        definir:
          - se: mes_pmo in [1, 2, 3, 4, 12]
            entao:
              - se: volume_inicial(24) < 50
                entao:
                  vazao_turbinada_maxima: {mes_1: 140, mes_2: 140, mes_3: _}
          - senao:
              - se: volume_inicial(24) < 20
                entao:
                  vazao_turbinada_maxima: {mes_1: 140, mes_2: 524, mes_3: 972}
              - senao_se: volume_inicial(24) < 50
                entao:
                  vazao_turbinada_maxima: {mes_1: 140, mes_2: 786, mes_3: 972}

Vale o primeiro ramo que casa, e sem ramo casado nada muda. entao recebe os campos ({campo: {mes_N: valor}}) ou outra cadeia. Os campos são os campos temporais de MODIF publicados na família newave.MODIF. mes_1, mes_2 e assim por diante são meses relativos. _ tira o limite do mês: grava 99999 nos máximos (vazao_turbinada_maxima, vazao_maxima_temporal) e 0 nos mínimos (vazao_minima_temporal, vazao_turbinada_minima, volume_minimo_com_penalidade). Cotas e volume_maximo_temporal não aceitam _; informe o valor. A cadeia é avaliada ramo a ramo, sem limite prático de tamanho.

Uma condição só com mes_pmo depende apenas do calendário. Com volume_inicial(...), ela lê o armazenamento antes do ajuste final de EARM: em uma rodada NEWAVE rolada a partir de um DECOMP, o armazenamento vem desse DECOMP; em uma cópia de deck, vem do CONFHD.DAT do próprio deck. Fixar a EARM da rodada não dispensa esse armazenamento, e uma fonte escolhida só para a EARM não muda a origem das condições.

Limites condicionais no DECOMP​

No DECOMP, antes_de_rodar aceita RE, HV e HQ e só muda limite_inferior e limite_superior. A chave é a mesma da restrição: uma entrada HQ 35 em antes_de_rodar se liga à HQ 35 criada em montar no mesmo documento. Sem ela, vale para a restrição criada antes, pela base ou por um Card anterior. Uma chave por nome (vazao-turbinada-mascarenhas) procura a restrição com esse nome. Se o alvo não existir no deck, nada é alterado e a rodada mostra um aviso de entrada ignorada; nome e número que apontam para restrições diferentes continuam sendo erro:

antes_de_rodar:
  decomp:
    HQ:
      - HQ 35:
          limite_superior:
            - se: volume_inicial(24) < 20
              entao: 140
            - senao: _
      - vazao-turbinada-mascarenhas:
          comentarios: ["Limite depende do volume inicial de M. de Moraes."]
          limite_superior:
            - {se: 'volume_inicial(7) < 70', entao: 500}

Cadeias usam se, senao_se e senao; entao recebe um número, _ (remove o limite) ou outra cadeia. Sem ramo casado, o valor atual é preservado.

Cada entrada aceita só limite_inferior, limite_superior, nome e comentarios:

  • comentarios descreve a condição e é preservado junto dela;
  • nome numa chave por nome tem de ser igual à chave; numa chave numerada, confere o nome da restrição alvo e, se ela foi criada no mesmo documento, tem de ser igual ao nome usado em montar;
  • a mesma chave não pode aparecer duas vezes, nem receber condições em dois lugares do mesmo documento;
  • antes_de_rodar.decomp ou antes_de_rodar.newave sem nenhuma família é recusado, assim como a chave alvo, que saiu do v5.

O interruptor Ajustes condicionais dos Cards liga ou desliga somente a seção antes_de_rodar dos Cards na rodada. O antes_de_rodar da base sempre roda.

Condições de formação ficam em montar​

periodo.se, mes_relativo e as cadeias de limite das formações NEWAVE não leem o estado de partida: elas descrevem como a base forma uma faixa ou um limite a partir dos arquivos da rodada. Por isso ficam em montar, com a mesma gramática se/senao_se/senao de antes_de_rodar. Veja Formação sistêmica do NEWAVE.

Uma regra de montar pode calcular limites a partir de outros dados da mesma montagem. Ajustes de carga DP já aparecem em carga_liquida(...), e ajustes de pequenas usinas PQ já aparecem em pq(...). O valor consultado é o total final da célula, depois dos Cards.

Volume inicial das UHEs​

Um Card pode fixar o volume inicial de usinas específicas, no DECOMP e no NEWAVE. O valor é o percentual final do volume útil da UHE (V.INIC%), entre 0 e 100, e não um delta:

montar:
  newave:
    CONFHD:
      volume_inicial: {66: 0}        # código do CONFHD.DAT
  decomp:
    UH:
      volume_inicial: {66: 0, 178: 42.5}   # código do bloco UH do DADGER

O código é o da usina no arquivo de cada modelo. O volume de partida vem do encadeamento com a rodada anterior; a aba EARM inicial aplica as metas por subsistema ou REE; os volumes fixados pelos Cards entram na mesma conta. Uma usina fixada não é reescalada, e a meta do grupo é atingida ajustando as demais usinas. Se a meta ficar impossível, por exemplo porque todas as usinas do grupo estão fixadas, a montagem é bloqueada com a mensagem "Corrija a meta ou as fixações dos cards". O Myria escreve o CONFHD.DAT ou o bloco UH uma única vez; nada sobrescreve o resultado depois.

A Base Myria não fixa Itaipu. Ela fixa no NEWAVE só as usinas que não têm correspondente no DECOMP para herdar o volume: Jordão (73) e Ernestina (110) em 100%, e P. Estrela (135), Aimorés (143), Barra Brauna (185) e Santo Antônio do Jari (286) em 0%. Uma base própria ou um Card pode mudar esses valores.

Blocos do DECOMP formados a partir do NEWAVE​

Quando o DECOMP da rodada é formado a partir do NEWAVE do estudo, parte do DADGER vem do NEWAVE já montado com os Cards:

No DECOMPVem do NEWAVE
DP (carga)carga do SISTEMA mais C_ADIC, distribuída pelos patamares do PATAMAR.DAT
CT (CVU)CVU do CLAST (conjuntural; sem ele, o estrutural)
PQgeração não simulada do SISTEMA

Por isso um Card de carga, CVU ou geração não simulada vai só no NEWAVE: a mudança chega ao DECOMP pela formação.

montar:
  newave:
    SISTEMA:
      carga:
        - submercado: S
          somar: {2026-06: 500, 2026-07: 500}

Escrever também no DP com somar ou multiplicar aplica a variação duas vezes. definir no DP com patamar: todos troca a carga formada por um valor igual nos três patamares. Use o bloco do DECOMP só quando o pedido for dele: um patamar, um estágio, ou uma rodada cujo DECOMP não é formado a partir do NEWAVE do estudo (DADGER copiado do ONS, NEWAVE externo). Ao adicionar um Card que mexe nas duas pontas, a tela da rodada mostra o aviso e pede confirmação.

Formação sistêmica do NEWAVE​

A base também comanda as formações recorrentes de SISTEMA.DAT, AGRINT.DAT e restricao-eletrica.csv. O Myria não reconhece restrições pelo número histórico: tudo o que é formado está declarado no YAML. A Base Myria declara, por exemplo:

montar:
  newave:
    SISTEMA:
      intercambio:
        - rota: [S, SE]
          definir:
            mes_12: {referencia: mes_11}
        - rota: [11, SE]
          definir:
            mes_12: {referencia: mes_11}
        - rota: [NE, SE]
          definir:
            mes_12: {referencia: mes_11}

    AGRINT:
      - horizonte-operacional-agrint:
          periodo:
            coordenada: destino
            se: fim >= mes_1
            inicio: max(inicio, mes_1)
            fim: fim
      - fns-fnese-xingu-para-sudeste:
          membros: [[11, SE], [NE, SE], [N, SE]]
          periodo:
            coordenada: destino
            se: fim >= mes_13
            inicio: max(inicio, mes_13)
            fim: fim

    RESTRICAO_ELETRICA:
      - recebimento-sul-sudeste:
          termos:
            intercambio: [S, SE]
            uhes: [{uhe: 66, coeficiente: 0.5}]
          periodo: {coordenada: origem, inicio: inicio, fim: fim}
          limite_inferior: restricao_eletrica(origem, 0)
          limite_superior:
            - se: mes_relativo == 12
              entao: primeiro_disponivel(restricao_eletrica(destino, 0), arredondar(sistema(S, SE, -1), 0))
            - senao: primeiro_disponivel(restricao_eletrica(destino, 0), arredondar(sistema(S, SE, 0), 0))
      - geracao-hidraulica-itaipu-50-hz:
          termos:
            uhes: [66]
          periodo: {coordenada: destino, inicio: mes_1, fim: mes_2}
          limite_inferior: restricao_eletrica(origem, intervalo(0, -60, -1))
          limite_superior: restricao_eletrica(origem, intervalo(0, -60, -1))
          se_ausente: ignorar

A Base Myria inclui somente fórmulas elétricas identificadas pelos termos e presentes de forma consistente nos decks operacionais. Se os termos de uma fórmula não existirem no deck NEWAVE da rodada, a formação é bloqueada; o Myria não inventa a regra nem ignora a ausência. A exceção é declarada: se_ausente: ignorar faz a ausência daquela fórmula, e só ela, não alterar nada.

SISTEMA​

mes_1 é o mês do PMO, mes_2 é o seguinte e mes_0 é o mês anterior ao PMO. Um alvo mes_N recebe um número ou uma referência ao valor do mesmo campo e seletor em outro mês. No exemplo acima, mes_12 recebe mes_11 nas três rotas, inclusive quando o valor é zero. Não há escolha automática de mês nem regra implícita de horizonte.

Os alvos começam em mes_1. mes_0 pode ser usado como fonte e é lido do SISTEMA.DAT antes da rolagem. As referências são resolvidas pela dependência declarada, não pela ordem do texto; ciclos são erro. Para nomear uma competência civil, use YYYY-MM.

AGRINT​

Um grupo é identificado pelo conjunto exato de membros, nunca pelo número. O período usa o mesmo objeto em todas as famílias: coordenada define a referência, se decide se a faixa permanece e inicio/fim calculam a nova faixa. origem usa os índices do arquivo de entrada; destino, os do PMO da rodada. inicio, fim e mes_N são índices mensais, então max(inicio, mes_1) é uma regra completa. Em periodo, só min(...) e max(...) são aceitas.

RESTRICAO_ELETRICA​

A restrição é identificada pelos termos da fórmula ou pelo nome da formação, nunca pelo número. Cada limite é um número, uma expressão ou uma cadeia se/senao_se/senao, a mesma gramática de antes_de_rodar:

  • restricao_eletrica(origem|destino, deslocamento) lê o mesmo campo da fórmula;
  • sistema(origem, destino, deslocamento) e agrint(membros, deslocamento) consultam os valores efetivos desses arquivos, com as siglas dos submercados (agrint([[11, SE], [NE, SE]], 0));
  • o deslocamento é inteiro: 0 é o mês indicado e -1 é o anterior; uma lista ou intervalo(inicio, fim, passo) declara, em ordem, os meses candidatos;
  • primeiro_disponivel(a, b, ...) tenta somente as alternativas escritas;
  • mes_relativo, mes_civil e patamar descrevem o alvo avaliado;
  • são aceitos aritmética, comparações, and, or, not, in, min, max e arredondar(valor, casas).

Não há busca automática do último valor nem transformação implícita do horizonte.

Um Card aplicado depois da base prevalece sobre o valor formado. Assim, a base constrói a regra e um Card pode mudar um mês ou patamar usando o mesmo seletor. Se faltar DGER.DAT, uma rota, um grupo, uma fórmula ou uma vigência necessária, a montagem é bloqueada.

A importação de planilhas Excel de ajustes gera apenas alterações das células presentes na planilha, com MÊS 1/MÊS 2 convertidos em mes_1/mes_2. Ela não acrescenta regras de período, alternativas nem deslocamentos.

Volume mínimo por REE (HE)​

HE é formado depois do bloco térmico final. A forma compacta é:

montar:
  decomp:
    HE:
      - HE 100:
          nome: volume-minimo-ree-sudeste-semanas-operativas
          ree: sudeste
          horizonte: semanas_operativas
          volume_minimo: curva_newave
          penalidade:
            maior_cvu_termico: {fator: 1.005, arredondar_para_cima: 10, universo: todas_utes_estagios_patamares}
          tratamento: forcar
      - HE 101:
          nome: volume-minimo-ree-sudeste-mes-estocastico
          ree: sudeste
          horizonte: mes_estocastico
          volume_minimo: curva_newave
          penalidade:
            maior_cvu_termico: {fator: 1.005, arredondar_para_cima: 10, universo: todas_utes_estagios_patamares}
          tratamento: penalizar

O número da chave é o mesmo escrito no DADGER; nome é opcional. semanas_operativas cobre todos os estágios menos o último; mes_estocastico cobre só o último. Em cada estágio, curva_newave lê o percentual de energia armazenável da CURVA.DAT, já com os ajustes NEWAVE da rodada.

maior_cvu_termico é calculado depois dos ajustes de decomp.CT: a penalidade é fator × maior CVU final, arredondado para cima até o múltiplo de arredondar_para_cima. universo escolhe quais CVUs entram no máximo: todas_utes_estagios_patamares (todas as UTEs, estágios e patamares do CT final) ou primeiro_estagio (só o estágio 1). Na Base Myria, 1,005 × maior CVU de todas as UTEs, estágios e patamares, arredondado para cima até o múltiplo de 10. Depois da formação, um Card decomp.HE pode mudar volume, penalidade ou tratamento. Selecione pelo número e, se quiser, pelo nome:

montar:
  decomp:
    HE:
      - HE 101:
          nome: volume-minimo-ree-sudeste-mes-estocastico
          periodo: estagio_6
          definir:
            volume_minimo: 18
            penalidade: 10000
            tratamento: forcar

A Base Myria tem 14 criações desse tipo, duas para cada REE: sudeste, parana, prnpanema, sul, iguacu, nordeste e norte.

A identificação acompanha o DECOMP CCEE 202610 RV2, conferido pela composição CM e pelo horizonte de cada restrição:

REESemanas operativasMês estocástico
SudesteHE 100HE 101
ParanáHE 105HE 106
ParanapanemaHE 108HE 109
SulHE 112HE 113
IguaçuHE 114HE 115
NordesteHE 118HE 119
NorteHE 122HE 123

Um Card HE com periodo mensal altera somente os estágios existentes daquela restrição dentro do período pedido. Por exemplo, 2027-01..fim pode atingir somente o HE estocástico de uma rodada de dezembro. Estágios sem registro nessa seleção mensal produzem aviso period_outside_restriction; um número inexistente ou um estágio explícito sem registro continua sendo erro. A renumeração da Base preserva fórmulas, limites, penalidades e tratamentos. Rodadas com snapshots anteriores exigem uma nova revisão aplicada para adotar a Base atual; os snapshots históricos permanecem imutáveis.

O REE é escrito pelo nome do REE.DAT em minúsculas: sudeste, sul, nordeste, norte, itaipu, madeira, tpires, bmonte, man-ap, parana, iguacu e prnpanema. Vários REEs com coeficiente usam rees: [[sudeste], [parana, 0.5]]. Um número só é aceito num Card, para um REE que o próprio Card criou (código 13 ou maior); na base, o REE é sempre escrito pelo nome. Uma base própria pode mudar essa construção, desde que declare a lista decomp.HE completa. CURVA.DAT ausente, valor fora de 0 a 100 ou falta de CVU térmico final bloqueiam a montagem; o Myria não reaproveita o HE que veio no DADGER.

Curva de volume de Tucuruí (HV)​

A Base Myria calcula os limites de volume de Tucuruí (UHE 275) com o cálculo pré-definido curva_de_volume. Calendário, níveis, meses fixos, limites, os estágios em que a curva atua e a conversão de percentual para hm³ ficam declarados no YAML da HV 101, que usa limites: {todos_estagios: calculo()}:

dados: {6: 100, 7: 91, 8: 84.6, 9: 76.8, 10: 58.2, 11: 33.9, 12: 10}
calculo:
  curva_de_volume:
    uhe: 275
    modo: teorico_intramensal
    niveis: dados
    fixo:
      meses: [1, 2, 3, 4, 5, 6, 12]
      limites: [3898.2, 38365.22]
    conversao:
      intercepto_hm3: -33.3857366158554
      inclinacao_hm3_por_percentual: 390.141100790573
    estagios_finais: 2
  • Quando todos os estágios da rodada caem em fixo.meses, todos recebem fixo.limites.
  • Senão, os níveis de dados definem a temporada. O primeiro mês é a âncora (junho a 100%, na Base Myria); os seguintes são interpolados dia a dia.
  • A curva atua nos estagios_finais últimos estágios; os demais recebem fixo.limites.
  • O PMO precisa ser o mês da âncora ou um mês da temporada antes do último.

curva_de_volume é o único cálculo pré-definido. Campos extras, limites não numéricos e inclinação não positiva são recusados. O cálculo usa as datas do próprio DADGER e a conversão declarada, e não depende do número da HV: se o ONS renumerar a restrição, o resultado não muda.

Manutenção hidráulica (MP)​

O Myria monta o bloco MP a partir do cadastro de manutenção declarado pela base antes de aplicar os Cards. Cada UHE em operação precisa de um perfil sazonal ou constante nesse cadastro; se faltar cobertura, a rodada é bloqueada.

Depois disso, decomp.MP é a única forma de alterar o resultado. O valor é o fator final em p.u. nos estágios escolhidos, não uma quantidade de máquinas:

montar:
  decomp:
    MP:
      - uhe: 178
        periodo: estagio_1..estagio_3
        definir: 0.86
      - uhe: 66
        frequencia: 50
        periodo: estagio_1..estagio_3
        definir: 0.90

Para Itaipu (uhe: 66), informe também frequencia: 50 ou 60. A prévia do deck mostra se cada perfil é sazonal ou constante.

Cadastros oficiais​

Algumas formações usam cadastros em YAML no Gitea. Os oficiais ficam ao lado da Base Myria, em org-myria/arquivos/regras/cadastros/: decomp-ac-v1.yaml (bloco AC), ti-formation-v1.yaml (irrigação), hydraulic-maintenance-v1.yaml (manutenção hidráulica), volume-espera-v1.yaml (limites sazonais de armazenamento, bloco VE), prevs-hydrology-v1.yaml (hidrologia do NEWAVE a partir do PREVS) e calendario-v1.yaml (horas por patamar de carga e feriados). A base aponta para cada um na seção cadastros:

cadastros:
  decomp_ac: regras/cadastros/decomp-ac-v1.yaml
  ti_formacao: regras/cadastros/ti-formation-v1.yaml
  manutencao_hidraulica: regras/cadastros/hydraulic-maintenance-v1.yaml
  volume_espera: regras/cadastros/volume-espera-v1.yaml
  hidrologia_prevs: regras/cadastros/prevs-hydrology-v1.yaml
  calendario: regras/cadastros/calendario-v1.yaml

Cada caminho é relativo ao repositório arquivos da organização dona da base e termina em .yaml, .yml ou .json. A Base Myria lê os cadastros da org-myria; uma base própria enviada pela sua organização lê os cadastros do repositório arquivos da sua organização, no caminho que ela declarar. Por isso, antes de usar uma base própria, copie para o seu repositório os cadastros oficiais que você não for alterar. Uma organização pode manter um cadastro próprio (por exemplo, regras/cadastros/calendario-da-org.yaml) apontando a sua base para ele. As seis chaves são obrigatórias.

Você pode abri-los para conferir os valores, mas não os escolhe pelo Card. A versão de cada cadastro é fixada quando a rodada é preparada para execução; novas tentativas usam a mesma versão, e uma atualização do cadastro só vale para rodadas preparadas depois. Cadastro ausente no caminho declarado ou divergente bloqueia a montagem, com o endereço esperado na mensagem; o Myria não completa valores por conta própria.

  • DECOMP, bloco AC: os registros de Belo Monte, Madeira, suspensões, configuração de máquinas de Tucuruí e os registros AC fixos vêm do cadastro e são conferidos contra os arquivos da rodada. CFUGA, CMONT e o JUSMED de Tucuruí usam a última vigência do MODIF.DAT anterior ou igual à competência. Quando o CMONT de Madeira não está no MODIF.DAT, o cadastro o completa; CFUGA ou JUSMED ausente bloqueia a montagem.
  • DECOMP, blocos MP e TI: manutenção hidráulica e irrigação vêm dos cadastros correspondentes. No TI, uma UHE repetida no DSVAGUA sem modo próprio usa o default_duplicate_mode do cadastro (first, last ou sum).
  • DECOMP, bloco VE: o cadastro volume_espera contém o perfil diário de 27 usinas recuperado do cadastro histórico. Os valores são o armazenamento máximo em % do volume útil: 100 significa ausência de reserva para cheias, e 94,4 deixa 5,6% de espera. Cada estágio semanal usa a média dos dias; o estágio mensal final usa o valor do último dia. O calendário inclui 29/02, usado apenas em anos bissextos. O VE é reconstruído para as usinas operacionais do cadastro mesmo se o deck de entrada não tiver esse bloco. Cards podem ajustar os valores depois dessa formação. Não há consulta automática ao ONS; atualizar o perfil exige publicar uma nova versão do cadastro.
  • Calendário (NEWAVE e DECOMP): o cadastro calendario define as horas de cada patamar de carga por dia (patamares.perfis, um perfil por mês em patamares.perfil_do_mes e patamares.dia_nao_util para sábados, domingos e feriados, cada perfil somando 24 h) e os feriados nacionais usados no ADTERM, DP, PQ e DADGNL. Os feriados fixos aceitam vigência (desde, ate); a Consciência Negra conta a partir de 2024. Os móveis são contados a partir do domingo de Páscoa; segunda e terça de Carnaval entram como dias não úteis.
  • NEWAVE, hidrologia: quando a montagem atualiza o VAZPAST.DAT a partir de um PREVS, postos derivados, fórmulas, coeficientes e hidrogramas vêm do cadastro hidrológico. O modo de cada hidrograma é o default_mode do cadastro. Toda rodada NEWAVE fixa esse cadastro, mesmo que não chegue a usá-lo. Vazão inválida no PREVS, semana ausente no mês ou posto de entrada de um cálculo ausente bloqueiam a montagem.

Ordem e reprodutibilidade​

Quando a rodada é preparada para execução, o Myria fixa:

  • a base efetiva, oficial ou própria;
  • os Cards na ordem declarada;
  • o conteúdo e o SHA-256 de cada documento;
  • o commit da Base Myria, quando ela é usada;
  • a versão de cada cadastro declarado pela base.

A base e os Cards são validados juntos nesse momento, então uma base incompleta ou um Card incompatível aparece antes da montagem do deck.

Novas tentativas da mesma revisão usam exatamente essa composição. Quando você muda os Cards, o Myria cria uma nova revisão para cada rodada afetada; as revisões anteriores continuam no histórico. Um commit novo no Gitea não altera uma revisão já preparada.

Erros que bloqueiam a rodada​

A rodada é recusada antes da montagem quando:

  • deck_rules ou ajustes está ausente;
  • uma referência não usa tipo: upload;
  • id está vazio;
  • sha256 está ausente, em maiúsculas ou não tem 64 caracteres;
  • o hash não corresponde ao conteúdo recebido;
  • a base não declara versao: 5 e tipo: base;
  • a base omite politicas.newave.gerenciador_pls;
  • a base não declara em montar as seis listas decomp.RI, decomp.IA, decomp.RE, decomp.HV, decomp.HQ e decomp.HE, ou coloca nelas algo além de criações completas;
  • um Card não declara versao: 5 e tipo: card, ou declara politicas ou cadastros;
  • o documento ainda está no formato antigo (version: 4, meta): ele é recusado com legacy_lexicon_v4 e precisa ser reescrito com versao: 5;
  • uma condição de partida aparece em montar (state_in_build), ou uma entrada de antes_de_rodar cria estrutura ou não lê volume_inicial(uhe) nem mes_pmo;
  • o documento usa uma grafia que saiu do v5 (legacy_spelling), como restricao:, ativo, estagios, alvo, patamar_1 ou um REE pelo número na base;
  • um submercado não é uma sigla válida (invalid_submarket), ou a rota da chave IA diverge de rota (ia_route_mismatch);
  • uma cadeia não abre com se, repete se em vez de senao_se ou tem senao fora do fim (invalid_condition_chain);
  • a base e os Cards não formam juntos uma composição válida;
  • deck_rules tem um campo desconhecido.

Os erros de validação apontam o caminho como você escreveu no YAML, por exemplo montar.decomp.DP.0.periodo ou antes_de_rodar.decomp.HQ.0.HQ 35.

Durante a montagem, uma política ausente na base, um cadastro ausente no caminho declarado ou uma fonte obrigatória que falta bloqueiam a rodada com código e mensagem; o Myria não usa zero nem valor padrão no lugar.

Quando uma formação lê AGRINT.DAT ou restricao-eletrica.csv, o diagnóstico separa erro do YAML de erro do arquivo:

CódigoCausa
SRC001Seletor ou termo inválido no YAML.
SRC002Mais de um grupo AGRINT candidato, sem que um contenha o outro.
SRC003Vigências AGRINT sobrepostas no mesmo período.
SRC004Fórmulas elétricas diferentes com os mesmos termos.
SRC005Arquivo malformado ou com termo não suportado.

O número não identifica uma fórmula elétrica. Dois números com a mesma composição geram SRC004; número duplicado, sintaxe inválida ou termo desconhecido geram SRC005. Todos esses casos bloqueiam a tentativa antes de qualquer publicação.

Entradas aplicadas, ignoradas ou com erro​

Uma incompatibilidade de cadastro ou período em um Card preserva a montagem da rodada. A entrada incompatível é ignorada, as demais entradas válidas continuam e a rodada mostra a decisão com título do Card, caminho da entrada e motivo. Consulte também avisos_cards na API e os relatórios da prévia.

DesfechoO que acontece
aplicadavalores compatíveis são aplicados e aparecem no diff/recibo
ignoradaentrada incompatível não altera os valores da rodada; o aviso explica por quê
adaptadaidentificador de restrição muda somente com correspondência única e exata de composição entre deck e Base; o aviso mostra os dois números
parcialapenas células dentro do período/estágios reais são aplicadas; o aviso identifica o trecho descartado
sobrescritauma definição posterior da pilha substitui uma célula definida por outro Card; o aviso mostra a decisão

Usina, UTE, REE, submercado, rota ou contrato inexistente não são criados como fallback. Um código descasado ou ambíguo é ignorado; nomes semelhantes não comprovam identidade. Se o mesmo número de restrição representa outra composição na Base, o Card é ignorado. Se uma criação for ignorada, ajustes posteriores que dependam dela também são ignorados, para não atingir outra restrição.

Meses passados, fora do horizonte, de outro ano ou estágios/RVs ausentes nunca são transferidos para outra célula. Intervalos parcialmente compatíveis aplicam a interseção real. Condições sem ramo verdadeiro e seções destinadas a outro modelo também têm decisão visível. A retirada/correção do Card recalcula os avisos.

Exemplos de códigos: unknown_uhe, unknown_hydraulic_plant, unknown_ute, unknown_ree, unknown_submarket, unknown_contract, restriction_absent, restriction_removed_by_base, restriction_identity_mismatch, restriction_identity_ambiguous, restriction_identifier_reconciled, card_creation_ignored, period_before_pmo, period_beyond_horizon, period_outside_horizon, round_not_applicable, condition_not_matched e model_not_applicable. O campo desfecho em avisos_cards distingue a decisão.

A identificação usa o deck pinado da rodada: atualizações do catálogo não reinterpretam fontes já admitidas. Valores e hashes originais das fontes não são reescritos para adaptar um identificador.

YAML inválido é recusado ao cadastrar o Card, antes de afetar a rodada. Uma Base inválida, fonte obrigatória ausente/corrompida, hash divergente ou falha interna continua sendo erro explícito; não é seguro certificar um deck nesses casos.

Exemplos das 33 famílias​

Escolha o modelo e a família de parâmetros para abrir um exemplo YAML. A coluna Pode fazer indica as alterações disponíveis no editor. Revise os valores do exemplo para o seu estudo antes de aplicar o Card.

NEWAVE​

FamíliaPode fazerExemplo
newave.AGRINTalterar valores, criar estruturas, desativarAbrir exemplo
newave.CLASTalterar valores, criar estruturasAbrir exemplo
newave.CONFHDalterar valoresAbrir exemplo
newave.CURVAalterar valores, criar estruturasAbrir exemplo
newave.CVARalterar valoresAbrir exemplo
newave.C_ADICalterar valores, criar estruturasAbrir exemplo
newave.DGERalterar valoresAbrir exemplo
newave.DSVAGUAalterar valores, criar estruturasAbrir exemplo
newave.EXPTalterar valores, criar estruturasAbrir exemplo
newave.MODIFalterar valores, criar estruturas, usar condiçãoAbrir exemplo
newave.PATAMARalterar valores, criar estruturasAbrir exemplo
newave.PENALIDalterar valores, criar estruturasAbrir exemplo
newave.REalterar valores, criar estruturas, desativarAbrir exemplo
newave.RESTRICAO_ELETRICAalterar valores, criar estruturas, desativarAbrir exemplo
newave.SISTEMAalterar valores, criar estruturasAbrir exemplo
newave.TERMalterar valoresAbrir exemplo

DECOMP​

FamíliaPode fazerExemplo
decomp.ACalterar valores, criar estruturasAbrir exemplo
decomp.CDalterar valores, criar estruturasAbrir exemplo
decomp.CTalterar valores, criar estruturasAbrir exemplo
decomp.DPalterar valores, criar estruturasAbrir exemplo
decomp.FDalterar valores, criar estruturasAbrir exemplo
decomp.HEalterar valores, criar estruturas, desativarAbrir exemplo
decomp.HQalterar valores, criar estruturas, desativarAbrir exemplo
decomp.HValterar valores, criar estruturas, desativarAbrir exemplo
decomp.IAalterar valores, criar estruturas, desativarAbrir exemplo
decomp.MPalterar valores, criar estruturasAbrir exemplo
decomp.PQalterar valores, criar estruturasAbrir exemplo
decomp.REalterar valores, criar estruturas, desativarAbrir exemplo
decomp.RENOVAVEISalterar valores, criar estruturasAbrir exemplo
decomp.RIalterar valores, criar estruturas, desativarAbrir exemplo
decomp.TIalterar valores, criar estruturasAbrir exemplo
decomp.UHalterar valoresAbrir exemplo
decomp.VEalterar valores, criar estruturasAbrir exemplo

Cada link abre um documento tipo: card independente, pronto para copiar e validar. Para criar uma estrutura nova, escolha Criar nova estrutura no editor; essa opção só aparece nas famílias marcadas com “criar estruturas” na tabela.

Perfis de conversão ONS para CCEE​

As regras também podem ser cadastradas como um Card comum e selecionadas manualmente na sequência de uma rodada DECOMP, inclusive importada de ZIP. Nesse caso, a aplicação segue a montagem normal dos Cards: o usuário escolhe quando aplicar, sem depender do botão de conversão ou de detecção de origem ONS. Confira as restrições e a competência cobertas pelo Card na prévia.

Na configuração de uma rodada NEWAVE ou DECOMP, use Converter ONS para CCEE. A rodada precisa declarar uma entrada ONS em org-myria/decks_ons; o nome da rodada, sozinho, não comprova essa origem. DESSEM não oferece essa conversão.

O perfil Oficial Myria é exibido para consulta. Criar minha versão abre uma cópia editável. Também é possível enviar um .yaml/.yml ou escolher um arquivo no Git da sua organização. Salve o perfil para validar o YAML v5 e o modelo. Cada salvamento cria uma versão privada; o arquivo oficial e o arquivo Git escolhido permanecem preservados. O limite do YAML é 2 MiB.

Um arquivo Git é capturado em um commit fixo. Verificar nova versão no Git mostra o novo conteúdo para comparação; Adotar nova versão cria outra versão sem alterar conversões anteriores. Autor e SHA-256 aparecem nos detalhes.

Informe o nome da nova rodada e use Gerar prévia para conferir as alterações reais. Converter e criar rodada cria uma entrada convertida e uma rodada no mesmo estudo, preservando a origem. Mudanças no deck exigem outra prévia. A nova rodada passa pela validação normal e pode ser executada pelo botão de execução habitual. Salvar o perfil ou converter não dispara o modelo.

O perfil de conversão transforma a entrada uma vez. Ele não entra na sequência de Cards da nova rodada. As demais entradas herdadas são validadas de novo; a rodada só pode executar quando estiver pronta. O resultado é uma conversão feita com o perfil escolhido, não uma publicação oficial da CCEE.