Pular para o conteúdo

Arquivos de estágios

Um caso do Novo Modelo descreve seu eixo temporal em dois arquivos na raiz do caso. stages.json é obrigatório: contém o grafo da política (policy graph), os estágios do estudo com seus patamares de carga, o mapa opcional de períodos sazonais e os estágios pré-estudo opcionais. post_study_stages.json é opcional: contém os calendários pós-horizonte das entregas das térmicas e da água em trânsito, e os limites de custo e de entrega por térmica para compromissos de despacho decididos dentro do estudo e entregues após o horizonte. O Resumo dos arquivos associa cada arquivo do caso à sua página, e Convenções apresenta as regras comuns a todos eles.


Metodologia: Grafos da política · Variantes de formulação dos patamares · Formulação da taxa de desconto

Define a estrutura temporal do estudo: sequência de estágios, decomposição em patamares e tipo de horizonte do grafo da política.

Campos de nível superior:

NomeTipoObrigatórioPadrãoUnidadesDescrição
policy_graphobjectSim——Tipo de horizonte, taxa de desconto anual e transições/nós entre estágios (veja abaixo)
stagesarraySim——Array com as definições dos estágios do estudo
season_definitionsobject | nullNão——Rotulagem de períodos sazonais para alinhamento com o modelo sazonal
pre_study_stagesarrayNão——Estágios pré-estudo para aquecimento (warm-up) do modelo AR (IDs negativos)

Subobjeto policy_graph:

NomeTipoObrigatórioPadrãoUnidadesDescrição
policy_graph.typestringSim——Um entre "finite_horizon", "cyclic". Tipo de horizonte. Apenas "finite_horizon" é suportado; "cyclic" é reservado e rejeitado na carga
policy_graph.annual_discount_ratenumberSim——Taxa de desconto anual global (>= 0.0)
policy_graph.nodesarrayNão——Nós do grafo da política (veja abaixo). Ausente ⇒ o grafo é uma cadeia de estágios e as extremidades de transitions[] são lidas diretamente como ids de estágio
policy_graph.transitionsarrayNão——Transições entre estágios (veja abaixo). Padrão: array vazio

Campos das entradas de policy_graph.nodes[]:

NomeTipoObrigatórioPadrãoUnidadesDescrição
policy_graph.nodes[].idintegerSim——Id único do nó, referenciado pelas extremidades de transitions[] quando nodes[] é declarado
policy_graph.nodes[].stage_idintegerSim——Id declarado do estágio do estudo em que este nó se situa; resolvido em relação aos estágios do estudo, nunca um índice de array
policy_graph.nodes[].scenario_idinteger | nullNãonull—Coluna de realização, por estágio, da biblioteca externa associada a este nó. Obrigatório em um estágio com uma classe externa que ocupa posição, omitido onde não houver. scenario_id: k equivale exatamente ao conjunto degenerado de aberturas ponderadas com um elemento [{ "scenario_id": k, "probability": 1.0 }]
policy_graph.nodes[].labelstring | nullNãonull—Rótulo opcional legível

Campos das entradas de policy_graph.transitions[]:

NomeTipoObrigatórioPadrãoUnidadesDescrição
policy_graph.transitions[].source_idintegerSim——Extremidade de origem: um id de nó quando policy_graph.nodes[] não é vazio; caso contrário, um id de estágio
policy_graph.transitions[].target_idintegerSim——Extremidade de destino: um id de nó quando policy_graph.nodes[] não é vazio; caso contrário, um id de estágio
policy_graph.transitions[].probabilitynumberSim——Probabilidade de transição; as probabilidades de saída de uma origem devem somar 1 com tolerância de 1e-6 (uma soma mais distante é rejeitada), e o carregador então as reescala para que somem 1
policy_graph.transitions[].annual_discount_rate_overridenumber | nullNãonull—Somente no dialeto de cadeia de estágios (sem policy_graph.nodes[]): incorporado ao estágio de origem da transição, e o annual_discount_rate_override do próprio estágio prevalece quando ambos são definidos; rejeitado sob policy_graph.nodes[] — declare a taxa no estágio.

Campos das entradas de stages[]:

NomeTipoObrigatórioPadrãoUnidadesDescrição
stages[].idintegerSim——Identificador do estágio (inteiro não negativo, único). Um id negativo não é rejeitado; o estágio é lido como estágio pré-estudo, e não como estágio do estudo
stages[].start_datestringSim——Data ISO 8601 (ex.: "2024-01-01")
stages[].end_datestringSim——Data ISO 8601; deve ser posterior a start_date
stages[].blocksarraySim——Array de patamares de carga (id, name, hours): não vazio, ids de patamar 0..n-1 (cada um uma vez, em qualquer ordem), todo hours finito e > 0
stages[].blocks[].idintegerSim——Índice do patamar no estágio; os ids de um estágio são 0..n-1, cada um uma vez, em qualquer ordem.
stages[].blocks[].namestringSim——Rótulo legível do patamar.
stages[].blocks[].hoursnumberSim—hDuração do patamar em horas; deve ser > 0.
stages[].num_openingsinteger | nullCondicionalnull—Número de aberturas dentro do nó para este estágio (>= 1); obrigatório no dialeto simples de cadeia de estágios (sem policy_graph.nodes[]) e em um estágio com aberturas geradas sob nodes[]; rejeitado em um estágio que tenha apenas aberturas externas; em um estágio de um grupo de ruído, no máximo o número de aberturas do primeiro estágio do grupo (Número de aberturas do grupo de ruído)
stages[].season_idinteger | nullNãonull—Referência a um período sazonal em season_definitions
stages[].block_modestringNão"parallel"—Um entre "parallel", "chronological". Modo de execução dos patamares: "parallel" (padrão) ou "chronological"
stages[].state_variablesobject | nullNão——Projeção dos cortes deste estágio. Para seus campos e valor padrão, veja stages[].state_variables — Projeção dos Cortes.
stages[].state_variables.storagebooleanNãotrue—Indicador de armazenamento da projeção dos cortes do estágio. Veja stages[].state_variables — Projeção dos Cortes.
stages[].state_variables.inflow_lagsbooleanNãofalse—Indicador de defasagens de afluência da projeção dos cortes do estágio. Veja stages[].state_variables — Projeção dos Cortes.
stages[].risk_measurestring | objectNão——Medida de risco por estágio: "expectation" (o padrão) ou {"cvar": {"alpha": …, "lambda": …}} com alpha em (0, 1] (a fração da cauda) e lambda em [0, 1]; valores fora desses intervalos são rejeitados; veja Medidas de risco
stages[].risk_measure.cvarobjectCondicional——Parâmetros do CVaR, contendo alpha e lambda; obrigatório quando stages[].risk_measure é um objeto.
stages[].risk_measure.cvar.alphanumberSim——Fração da cauda, em (0, 1]; um valor fora do intervalo é rejeitado.
stages[].risk_measure.cvar.lambdanumberSim——Peso de aversão ao risco, em [0, 1]; um valor fora do intervalo é rejeitado.
stages[].sampling_methodstringNão"saa"—Um entre "saa", "lhs", "qmc_sobol", "qmc_halton", "selective", "historical_residuals". Método de geração de ruídos do estágio: "saa" (padrão), "lhs", "qmc_sobol", "qmc_halton", "selective" ou "historical_residuals". "selective" exige uma árvore de aberturas fornecida (training.scenario_source.openings {"source": "file"}, scenarios/noise_openings.parquet); "historical_residuals" exige scenarios/inflow_history.parquet e um season_id em todo estágio do estudo quando a árvore de aberturas é gerada. Para uma classe em out_of_sample, "selective" e "historical_residuals" sorteiam ruído Monte Carlo simples na simulação forward, com um aviso. Veja Geração de cenários
stages[].annual_discount_rate_overridenumber | nullNãonull—Taxa de desconto anual própria do estágio; se ausente, usa policy_graph.annual_discount_rate. Veja Formulação da taxa de desconto.

Campos das entradas de pre_study_stages[]:

NomeTipoObrigatórioPadrãoUnidadesDescrição
pre_study_stages[].idintegerSim——Id de estágio negativo; único e distinto de todos os ids de estágio do estudo. Um id não negativo é lido como estágio do estudo, e a carga falha porque esse estágio não declara patamares.
pre_study_stages[].start_datestringSim——Data ISO 8601 (YYYY-MM-DD).
pre_study_stages[].end_datestringSim——Data ISO 8601, posterior a start_date.
pre_study_stages[].season_idinteger | nullNãonull—Um período sazonal de season_definitions, adotado conforme declarado (nunca derivada das datas).

Os estágios pré-estudo são períodos datados anteriores ao primeiro estágio do estudo, usados pelo modelo autorregressivo (AR) de afluências para suas defasagens. Os estágios pré-estudo não têm patamares e nunca são resolvidos.

Subobjeto season_definitions:

O objeto opcional season_definitions associa IDs de período sazonal a períodos do calendário para o modelo PAR; ele associa os valores de season_id dos estágios aos parâmetros do PAR. Quando ausente, não há mapa de períodos sazonais, de modo que um estágio sem season_id não tem período sazonal. Quando presente como mapa de resolução única, um estágio sem season_id assume o período sazonal de sua data de início; um mapa de múltiplas resoluções (um mapa custom cujos períodos sazonais de resoluções diferentes se sobrepõem; períodos sazonais cujas durações diferem em no máximo 7 dias formam uma resolução, e dois períodos sazonais de uma mesma resolução não podem compartilhar um dia do calendário) exige season_id em todos os estágios. A estimação a partir de inflow_history.parquet exige season_definitions, e um estudo cuja classe de afluências usa o esquema historical, ou que gera sua árvore de aberturas para um estágio historical_residuals, exige um período sazonal em todos os estágios do estudo.

NomeTipoObrigatórioPadrãoUnidadesDescrição
season_definitions.cycle_typestringSim——Um entre "monthly", "weekly", "custom".
season_definitions.seasonsarraySim——Array de entradas de período sazonal (veja abaixo)

Campos das entradas de season_definitions.seasons[]:

NomeTipoObrigatórioPadrãoUnidadesDescrição
season_definitions.seasons[].idintegerSim——Identificador do período sazonal (inteiro com base 0, único no mapa de períodos sazonais)
season_definitions.seasons[].labelstringSim——Rótulo legível (ex.: "January", "Q1", "Wet Season")
season_definitions.seasons[].month_startintegerSim——Mês do calendário em que o período sazonal começa (1–12)
season_definitions.seasons[].day_startinteger | nullNãonull—Dia do calendário em que o período sazonal começa (1–31). Lido apenas no tipo de ciclo custom; um valor omitido é lido como 1.
season_definitions.seasons[].month_endinteger | nullNãonull—Mês do calendário em que o período sazonal termina (1–12). Lido apenas no tipo de ciclo custom; um valor omitido é lido como month_start.
season_definitions.seasons[].day_endinteger | nullNãonull—Dia do calendário em que o período sazonal termina, inclusive (1–31). Lido apenas no tipo de ciclo custom; um valor omitido é lido como 31.

Tipos de ciclo:

  • "monthly" — os períodos sazonais correspondem aos meses do calendário (12 períodos sazonais); o month_start de cada entrada indica seu mês (1 = janeiro, …, 12 = dezembro), independentemente de seu id. Apenas id, label e month_start são necessários em cada entrada.
  • "weekly" — os períodos sazonais correspondem às semanas ISO do calendário (52 períodos sazonais). Apenas id, label e month_start são necessários em cada entrada.
  • "custom" — intervalos de datas definidos pelo usuário, com month_start/day_start/month_end/day_end explícitos. Os campos de limite day_start, month_end e day_end são lidos apenas neste tipo de ciclo; quando omitidos, são lidos como 1, month_start e 31, respectivamente. Use este tipo de ciclo em estudos com resoluções mistas, em que alguns estágios são mensais (IDs 0–11) e outros trimestrais (IDs 12–15).

Exemplo — Tipo de ciclo personalizado com períodos sazonais mensais e trimestrais:

{
"season_definitions": {
"cycle_type": "custom",
"seasons": [
{
"id": 0,
"label": "January",
"month_start": 1,
"day_start": 1,
"month_end": 1,
"day_end": 31
},
{
"id": 1,
"label": "February",
"month_start": 2,
"day_start": 1,
"month_end": 2,
"day_end": 29
},
{
"id": 11,
"label": "December",
"month_start": 12,
"day_start": 1,
"month_end": 12,
"day_end": 31
},
{
"id": 12,
"label": "Q1",
"month_start": 1,
"day_start": 1,
"month_end": 3,
"day_end": 31
},
{
"id": 13,
"label": "Q2",
"month_start": 4,
"day_start": 1,
"month_end": 6,
"day_end": 30
},
{
"id": 14,
"label": "Q3",
"month_start": 7,
"day_start": 1,
"month_end": 9,
"day_end": 30
},
{
"id": 15,
"label": "Q4",
"month_start": 10,
"day_start": 1,
"month_end": 12,
"day_end": 31
}
]
}
}

Neste exemplo, os períodos sazonais 0–11 cobrem os modelos PAR mensais da fase de curto prazo e os períodos sazonais 12–15 cobrem os modelos PAR trimestrais da fase de longo prazo. Cada estágio mensal recebe um season_id entre 0 e 11; cada estágio trimestral recebe um season_id entre 12 e 15. Quando estágios que compartilham um season_id diferem em duração por mais de 7 dias, cada um deve interceptar uma ocorrência do período sazonal e abranger a janela desse período, com tolerância de 7 dias, ou ser pelo menos 7 dias mais curto, como estágios semanais que informam o seu mês. Em um mapa que sobrepõe resoluções, como este, um estágio mais curto desses não pode ter, com tolerância de 7 dias, a duração de um período sazonal de um nível mais fino; por isso, estágios mensais e trimestrais usam valores distintos de season_id. Um estágio que viola a regra é um erro BusinessRuleViolation.


Metodologia: Fronteira pós-estudo e estudos encadeados

O arquivo da fronteira pós-estudo. Ele declara dois calendários pós-horizonte, um para cada tipo de compromisso, mais uma tabela de custo e de limites de entrega por (thermal, post-study stage): thermal_stages[] data as entregas das térmicas, water_bucket_stages[] data as posições das parcelas de água em trânsito (in-transit buckets), e thermal_bounds[] é o único meio de declarar o limite e o custo de um compromisso de despacho que uma térmica com antecipação de despacho decide dentro do estudo, mas entrega após o horizonte (sua coluna de decisão é cobrada ao custo da célula, descontado até o estágio de decisão, e a fronteira carregada valora o compromisso que ela contém). O arquivo é opcional. Quando ele está ausente, não há estágios pós-estudo, e um caso em que alguma usina hidrelétrica declara um tempo de viagem é carregado com um aviso e data suas parcelas de água em trânsito como o formato obsoleto faz. O arquivo é obrigatório sempre que a antecedência de alguma térmica com antecipação de despacho alcança um estágio pós-estudo — a falta de uma célula para um estágio alcançado é rejeitada na carga, com indicação da usina e do índice do estágio pós-estudo. Veja Fronteira pós-estudo e estudos encadeados para a formulação da fronteira alimentada por este arquivo.

thermal_stages[] — o calendário pós-horizonte das térmicas:

NomeTipoObrigatórioPadrãoUnidadesDescrição
thermal_stages[].start_datestringSim——Data de início do estágio (inclusive), ISO 8601 YYYY-MM-DD
thermal_stages[].duration_hoursnumberSim—hDuração do estágio em horas; finita e > 0.0. end_date é derivada de start_date + duration_hours, nunca declarada

Os estágios são contíguos em datas (o end_date implícito de cada estágio é igual ao start_date do estágio seguinte) e o primeiro start_date deve ser igual ao fim do horizonte do estudo — a data imediatamente posterior ao último estágio do estudo. Os estágios pós-estudo servem apenas como fronteira: nunca são despachados, nunca são estágios do estudo e nunca contêm cortes de Benders — existem unicamente para dar a uma entrega posterior ao horizonte uma posição no calendário em relação à qual ela é valorada. Dois estágios não podem compartilhar o mesmo start_date. thermal_stages[] e thermal_bounds[] são declarados juntos: um arquivo que tem um sem o outro é rejeitado na carga. Em um caso sem térmica com antecipação de despacho, thermal_stages[] não tem efeito, e a carga emite um aviso. Os estágios pós-estudo não declaram taxa de desconto: o desconto acumulado continua sobre eles à taxa policy_graph.annual_discount_rate.

water_bucket_stages[] — o calendário pós-horizonte das parcelas de água em trânsito:

NomeTipoObrigatórioPadrãoUnidadesDescrição
water_bucket_stages[].start_datestringSim——Data de início do estágio (inclusive), ISO 8601 YYYY-MM-DD
water_bucket_stages[].duration_hoursnumberSim—hDuração do estágio em horas; finita e > 0.0. end_date é derivada de start_date + duration_hours, nunca declarada

O calendário é obrigatório quando alguma usina hidrelétrica declara um tempo de viagem (um travel_time_hours acima de zero no seu arco de jusante): um arquivo sem ele em um caso assim é rejeitado na carga, com indicação da usina. Ele segue as mesmas regras de contiguidade e de start_date não compartilhado de thermal_stages[]: o primeiro start_date é igual ao fim do horizonte do estudo, e cada estágio começa onde o anterior termina. Sua duração total deve cobrir o maior tempo de viagem entre as usinas hidrelétricas; um calendário mais curto é rejeitado na carga, com indicação da usina e das duas durações. O calendário é usado exatamente como declarado: nunca é estendido com estágios adicionais e nunca é incorporado ao calendário das térmicas, então declare todos os estágios que os tempos de viagem alcançam. Em um caso em que nenhuma usina hidrelétrica declara tempo de viagem, o calendário não tem efeito, e a carga emite um aviso.

thermal_bounds[] — custo e capacidade de entrega por (thermal, post-study stage):

NomeTipoObrigatórioPadrãoUnidadesDescrição
thermal_bounds[].thermal_idintegerSim——Identificador da usina termelétrica; deve referenciar uma térmica que declare anticipated_config
thermal_bounds[].post_study_stage_indexintegerSim——Índice, com base zero, em thermal_stages[]; deve ser < thermal_stages.len()
thermal_bounds[].cost_per_mwhnumberSim—R$/MWhCusto de combustível (R$/MWh) nesta célula; finito
thermal_bounds[].min_mwnumberSim—MWLimite inferior da potência entregue (MW) nesta célula; finito
thermal_bounds[].max_mwnumberSim—MWLimite superior da potência entregue (MW) nesta célula; finito, >= min_mw

Duas linhas não podem compartilhar o mesmo par (thermal_id, post_study_stage_index). Todo estágio pós-estudo alcançado pela antecedência de uma térmica com antecipação de despacho deve ter uma linha thermal_bounds correspondente: o compromisso entregue é limitado pelo intervalo [min_mw, max_mw] dessa célula e cobrado ao seu cost_per_mwh na coluna de decisão, descontado do estágio pós-estudo até o estágio de decisão.

{
"$schema": "https://docs.modelossetoreletrico.org.br/schemas/post_study_stages.schema.json",
"thermal_stages": [
{ "start_date": "2026-11-01", "duration_hours": 720.0 },
{ "start_date": "2026-12-01", "duration_hours": 744.0 }
],
"water_bucket_stages": [
{ "start_date": "2026-11-01", "duration_hours": 720.0 },
{ "start_date": "2026-12-01", "duration_hours": 744.0 }
],
"thermal_bounds": [
{
"thermal_id": 86,
"post_study_stage_index": 0,
"cost_per_mwh": 210.0,
"min_mw": 0.0,
"max_mw": 350.0
},
{
"thermal_id": 86,
"post_study_stage_index": 1,
"cost_per_mwh": 220.0,
"min_mw": 0.0,
"max_mw": 300.0
}
]
}

Um arquivo pode, em vez disso, declarar um único calendário stages[], com os mesmos campos de estágio, junto com thermal_bounds[]; ele é carregado com um aviso. Neste formato, stages[] data os dois tipos de compromisso: thermal_bounds[].post_study_stage_index indexa stages[], e as parcelas de água em trânsito são datadas sobre os estágios do estudo seguidos de stages[], estendidos com cópias da duração do último estágio até que o calendário cubra cada tempo de viagem. Um caso sem o arquivo data suas parcelas de água em trânsito da mesma forma, apenas a partir dos estágios do estudo. Um arquivo não pode misturar stages[] com thermal_stages[] ou water_bucket_stages[]; um arquivo que o faz é rejeitado na carga.

NomeTipoObrigatórioPadrãoUnidadesDescrição
stagesarrayNão——Grafia obsoleta de thermal_stages[]; não pode ser combinada com thermal_stages[] ou water_bucket_stages[]
stages[].start_datestringSim——Data de início do estágio (inclusive), ISO 8601 YYYY-MM-DD
stages[].duration_hoursnumberSim—hDuração do estágio em horas; finita e > 0.0. end_date é derivada de start_date + duration_hours, nunca declarada

python3 scripts/migrate/post_study_stages.py DECK_DIR [DECK_DIR ...], executado a partir do repositório do novomodelo, reescreve cada caso em thermal_stages[], thermal_bounds[] e water_bucket_stages[], com o mesmo calendário da água que este formato produz, de modo que os resultados do caso não mudam. Ele cria o arquivo para um caso que não o tem e declara um tempo de viagem, e não altera um arquivo sem stages[].