Pular para o conteúdo principal

Expandir estudos

Um estudo cresce de três formas: novas revisões (RV+), novos meses (M+) ou novos dias de DESSEM (D+) a partir de uma rodada de origem, e sensibilidades de PREVS sobre uma rodada existente. Criar rodadas não inicia a execução: depois que o pedido terminar, execute pela API de execução. Autenticação, Operation e erros comuns estão na visão geral; os campos, na referência interativa.

Para a mesma tarefa na tela Trilhas do Portal, veja Trilhas de estudos.

Topologia do estudo​

GET /studies/{study_key}/topology devolve o grafo de rodadas do estudo:

  • nodes: cada rodada ou fonte externa, com round_key (ou external_id para bases externas), name, type, period, rv, track, track_name, origin_round_key, previous_round_key, incremental_capable, status, readiness, tags (as tags da rodada; vazio em fontes externas) e facets (as facetas automáticas de PREVS da TOK e de cortes NEWAVE do Myria, cada uma com key, value e label; vazio nos demais nós);
  • edges: as dependências entre elas (from, to, role, state, blocking);
  • structure_revision: o identificador da estrutura atual.

Rodadas ainda em preparação por uma operação não aparecem no grafo. A topologia usa a mesma seleção de rodadas visíveis das demais leituras do estudo.

Use o round_key de um nó como origem (origin_round_key) ou o external_id de uma base externa (origin_external_id).

Para NEWAVE e DECOMP, period usa o formato AAAAMM, com meses de 01 a 12. Uma fonte externa sem período identificado usa o PMO declarado da rodada que a consome.

Prévia e confirmação​

Toda expansão tem dois passos: a prévia, que calcula o plano sem gravar nada, e a confirmação, que cria as rodadas.

1. Prévia. POST /studies/{study_key}/incremental-operations/preview (studies:read, sem Idempotency-Key):

curl -sS -X POST "$MYRIA_API/api/v1/studies/$STUDY_KEY/incremental-operations/preview" \
  -H "Authorization: Bearer $MYRIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "rv",
    "count": 2,
    "base_deck_version": "0123456789abcdef0123456789abcdef01234567",
    "origin_round_key": "minha-org-206"
  }'
CampoUso
moderv (revisões), m (meses) ou d (dias de DESSEM).
countQuantos períodos criar: de 1 a 24 em rv e m; de 1 a 6 em d.
base_deck_versionA deck_version atual do estudo.
origin_round_key ou origin_external_idA origem. Informe no máximo uma.
new_track_labelNome da nova trilha, até 80 caracteres. Só é aceito quando a origem é intermediária e a expansão abre uma nova trilha.
configuration_overridesConfiguração das rodadas novas, diferente da herdada da origem. Veja abaixo.
newave_by_pmoEm RV+ que atravesse o mês ou em M+, a base NEWAVE de cada PMO novo.

A resposta traz o plano (planned, com nome, modelo, PMO e RV de cada rodada), topology_effect (continuar a trilha ou abrir uma nova), warnings e três valores que a confirmação precisa repetir: plan_hash, origin_configuration_revision e expected_structure_revision. Traz também requires_confirmation e advanced_months, explicados abaixo.

2. Confirmação. POST /studies/{study_key}/incremental-operations (studies:write, com Idempotency-Key), com os mesmos campos da prévia mais os três valores devolvidos por ela:

curl -sS -X POST "$MYRIA_API/api/v1/studies/$STUDY_KEY/incremental-operations" \
  -H "Authorization: Bearer $MYRIA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rv-mais-191-001" \
  -d '{
    "mode": "rv",
    "count": 2,
    "base_deck_version": "0123456789abcdef0123456789abcdef01234567",
    "origin_round_key": "minha-org-206",
    "plan_hash": "<plan_hash da prévia>",
    "origin_configuration_revision": "<valor da prévia>",
    "expected_structure_revision": "<valor da prévia>"
  }'

Esses três valores garantem que o plano confirmado é o mesmo que você viu: se a estrutura do estudo, a configuração da origem ou o plano mudou depois da prévia, a confirmação é recusada com 409 (por exemplo, incremental_plan_conflict). Gere outra prévia. Envie sempre os valores devolvidos pela prévia; não os calcule no seu sistema. A resposta é 202 Operation; em succeeded, result traz study_key, a nova deck_version e round_keys das rodadas criadas.

Mais regras:

  • Uma origem no meio de uma trilha cria uma nova trilha e preserva a continuação existente. Na ponta de uma trilha, new_track_label é recusado: adicionar períodos não renomeia a trilha.
  • O estudo não pode ter execução ou outra alteração estrutural em andamento.
  • Uma rodada usada por outra trilha não pode ser excluída sozinha.

Revisões que atravessam o mês​

Em mode: "rv", count conta revisões DECOMP a partir da origem. Se o pedido passar da última revisão (RV) do mês, a prévia mostra a continuação nos meses seguintes, incluindo o NEWAVE de cada mês novo como apoio: nesse caso, requires_confirmation é true e advanced_months lista os PMOs novos. Para aceitar esse plano, envie na confirmação "month_advance_confirmed": true junto com o plan_hash. Sem essa confirmação, o pedido é recusado com 409 incremental_rv_exhausted, e details.remaining_revisions informa quantas revisões restam no mês. Nenhuma rodada é criada. Para avançar meses sem passar pelas revisões, use mode: "m".

month_advance_confirmed só vale em mode: "rv" e exige plan_hash; sem a prévia, a resposta é 409 preview_required.

Base NEWAVE por PMO​

Por padrão, o Myria escolhe a base NEWAVE de cada mês novo. Para fixar uma, envie newave_by_pmo na prévia, com o PMO no formato AAAAMM como chave:

{
  "newave_by_pmo": {
    "202610": {"gitea_org": "minha-org", "repo": "decks_ons", "path": "newave/202610"}
  }
}

A pasta precisa estar entre as fontes autorizadas para a organização e conter um DGER.DAT do mesmo PMO; caso contrário, a prévia responde 400 (newave_source_pmo_mismatch, newave_source_unavailable) ou 403. A prévia devolve o mapa com o commit fixado (ref). Repita esse mapa, exatamente como veio, na confirmação. O processamento preserva essa seleção e o commit fixado: o plano reutiliza a base indicada, sem criar um NEWAVE adicional para esse PMO.

Configuração das rodadas novas​

Um NEWAVE mensal novo usa, por padrão, os Prevs do DECOMP anterior para preparar o VAZPAST (base_plus_prevs, origem sumario_base) e a rolagem do ADTERM da base (roll_base). Esses modos ficam explícitos na configuração e podem ser alterados pelas opções da rodada ou por configuration_overrides. Um predecessor interno ainda pendente será consumido na preparação da execução; a ausência dos Prevs exigidos bloqueia a rodada, sem substituir a fonte por outro VAZPAST. Rodadas antigas com política automatic continuam exigindo uma escolha explícita antes da execução.

Na montagem de um novo NEWAVE mensal, os insumos permanecem vinculados às fontes e aos commits fixados. O novo deck não herda pld.dat, format.tmp nem mensag.tmp de execuções anteriores: essas saídas são produzidas pela execução do próprio NEWAVE. Os arquivos da origem não são apagados e a reutilização de uma rodada existente não modifica seus resultados.

Sem configuration_overrides, as rodadas novas herdam a configuração da origem, adaptada aos novos períodos. Para mudar algo já na criação, envie configuration_overrides com deck_rules e as configurações de entrada newave_hydrology, newave_adterm, newave_earm, decomp_cuts, decomp_hydrology, gevazp_history, decomp_dadgnl e decomp_earm. Cada uma tem o mesmo formato usado nas opções da rodada; deck_rules tem o formato de deck_rules no estudo.yaml. A prévia valida tudo sem gravar; a confirmação aplica às rodadas criadas. Qualquer outro campo é recusado com configuration_overrides_unavailable.

Primeira expansão de um estudo vazio​

Um estudo criado por POST /studies ainda não tem versão. Na primeira expansão, envie "base_deck_version": "" junto com origin_external_id. Depois disso, base_deck_version volta a ser obrigatório.

Dias de DESSEM (D+)​

mode: "d" cria uma sequência de rodadas DESSEM de preço. count vai de 1 até o número de dias que faltam para sexta-feira, no máximo 6: a semana operativa vai de sábado a sexta, e sexta-feira não pode originar sábado. A origem é obrigatória: origin_external_id de uma base CCEE do estudo, ou origin_round_key de uma rodada elegível para continuar a trilha.

{
  "mode": "d",
  "count": 1,
  "base_deck_version": "0123456789abcdef0123456789abcdef01234567",
  "origin_round_key": "minha-org-1234"
}

Partindo da base CCEE, o servidor resolve e fixa o último deck de preço DESSEM compatível com a semana e com a referência DECOMP, o estado de saída desse deck e a FCF que ele usou. Essa entrada não exige executar um DECOMP local. Em D+ sucessivos, cada dia usa o deck DESSEM da origem e herda a mesma FCF; na execução, o estado inicial vem do resultado válido do dia anterior da mesma trilha.

mode: "d" não aceita configuration_overrides nem month_advance_confirmed. A resposta é 409 quando falta FCF, deck de entrada do dia anterior ou um dia seguinte elegível. A operação D+ monta e valida o deck, mas não inicia a execução: quando a rodada ficar ready, execute-a pelo endpoint de execuções. Um dia seguinte só executa depois que o dia anterior da trilha tiver resultados válidos.

Para trocar a FCF de uma rodada DESSEM, use o campo dessem_fcf na configuração da rodada.

Sensibilidades​

Uma sensibilidade é uma rodada irmã de uma rodada DECOMP principal, com outro PREVS. GET /studies/{study_key}/rodadas/{round_key}/sensitivities lista as sensibilidades da rodada (paginação por cursor); cada item traz round_key, name, label, prevs_source, sensibilidade_base, trilha, status e readiness.

Para criar, use POST na mesma rota, com Idempotency-Key. Há dois formatos. A rodada base não pode estar em execução (409 active_rodada).

Lote de sensibilidades de PREVS. Só sobre uma rodada DECOMP principal. Até 24 itens por pedido; cada item cria uma rodada que herda a configuração e as dependências da rodada base:

{
  "base_deck_version": "0123456789abcdef0123456789abcdef01234567",
  "sensitivities": [
    {"label": "chuva baixa", "prevs_source": {"source": "external", "org": "minha-org",
      "repo": "terceiros", "path": "tok/prevs/setembro", "file": "cenario-seco.rv0"}},
    {"label": "chuva alta", "prevs_source": {"source": "external", "org": "minha-org",
      "repo": "terceiros", "path": "tok/prevs/setembro", "file": "cenario-umido.rv0"}}
  ]
}

Mais de 24 itens retorna 400 too_many_sensitivities. Informe a origem do PREVS com source: "external", org, repo, path e file, sem commit: ao aceitar o pedido, o Myria fixa o último commit de main que alterou o arquivo. Um ref no pedido é recusado com 400 invalid_prevs_source. A pasta precisa estar entre as fontes de PREVS autorizadas; caso contrário, a resposta é 403 forbidden_prevs_source. O nome do arquivo dentro do deck é definido pelo Myria.

Nova trilha (fork). Com "fork": true, o pedido cria uma única rodada em uma nova trilha a partir de uma rodada NEWAVE ou DECOMP, com nome em label (de 1 a 80 caracteres). Sobre uma rodada DECOMP, aceita também um PREVS em prevs_source e um ajuste de carga; sem PREVS, a nova rodada herda o da base:

{
  "base_deck_version": "0123456789abcdef0123456789abcdef01234567",
  "fork": true,
  "label": "Carga +5% SE",
  "load_adjustment": {"percent": 5, "submarket": "SE", "stages": [1, 2, 3]}
}

load_adjustment multiplica a carga do submercado (SE, S, NE ou N) nos estágios indicados (de 1 a 12, sem repetir), em todos os patamares. percent vai de mais de -100 até 100. Sem fork: true, load_adjustment é recusado.

Para usar um PREVS que ainda não está no estudo, envie-o antes por POST /studies/{study_key}/inputs, espere o pedido terminar e use a nova deck_version como base_deck_version.

A resposta é 202 Operation. Acompanhe até succeeded antes de executar as novas rodadas.