Pular para o conteúdo

Guia rápido

Esta página leva você do zero a um estudo de PDDE (SDDP) concluído em três comandos, usando o modelo embutido 1dtoy. O modelo representa um sistema hidrotérmico com um único barramento, uma usina hidrelétrica e duas unidades termelétricas, ao longo de um horizonte de planejamento finito de 4 estágios — pequeno o bastante para rodar em segundos e completo o bastante para demonstrar cada etapa do fluxo de trabalho.

Se você ainda não instalou o Novo Modelo, comece pela Instalação.

Demonstração do guia rápido


Terminal window
novomodelo init --template 1dtoy my_first_study

O Novo Modelo grava 11 arquivos de entrada em um novo diretório my_first_study/ e imprime um resumo no stderr:

╺━━━━━━━━━╻●
╺━━━━━━━━━╻●⚡ NOVOMODELO v0.21.0
╺━━━━━━━━━╻● Power systems in Rust
Created my_first_study case directory from template '1dtoy':
✔ config.json Algorithm configuration: training (forward passes, stopping rules) and simulation settings
✔ initial_conditions.json Initial reservoir storage volumes for each hydro plant at the start of the planning horizon
✔ penalties.json Global penalty costs for constraint violations (deficit, excess, spillage, storage bounds, etc.)
✔ stages.json Planning horizon definition: policy graph type, discount rate, stage dates, time blocks, and scenario counts
✔ system/buses.json Electrical bus definitions with deficit cost segments
✔ system/hydros.json Hydro plant definitions: reservoir bounds, outflow limits, turbine model, and generation limits
✔ system/hydro_production_models.json Per-(hydro, stage) production-model configuration carrying the productivity coefficient
✔ system/lines.json Transmission line definitions (empty in this single-bus example)
✔ system/thermals.json Thermal plant definitions with piecewise cost segments and generation bounds
✔ scenarios/inflow_seasonal_stats.parquet Seasonal PAR(p) statistics for hydro inflow scenario generation (mean, std, lag correlations)
✔ scenarios/load_seasonal_stats.parquet Seasonal PAR(p) statistics for electrical load scenario generation (mean, std, lag correlations)
Next steps:
-> novomodelo validate my_first_study
-> novomodelo run my_first_study --output my_first_study/results

A estrutura do diretório é:

my_first_study/
config.json
initial_conditions.json
penalties.json
stages.json
system/
buses.json
hydros.json
hydro_production_models.json
lines.json
thermals.json
scenarios/
inflow_seasonal_stats.parquet
load_seasonal_stats.parquet

Terminal window
novomodelo validate my_first_study

O processo de validação verifica todas as camadas — esquema, referências, viabilidade física e consistência estocástica — e então monta o estudo como novomodelo run faz e verifica qualquer política que a execução carregaria, sem resolver nenhum PL, e imprime, em caso de sucesso, uma única linha com a contagem de entidades:

Valid case: 1 buses, 1 hydros, 2 thermals, 0 lines

Essa é toda a saída para um caso sem avisos; um caso que gera avisos acrescenta um resumo Validation: 0 errors, N warnings in <dir> e uma linha warning: por ocorrência. Se alguma camada falhar, o Novo Modelo imprime um resumo Validation: N errors, 0 warnings in <dir> seguido de cada erro prefixado com error:, e termina com código diferente de zero: 1 para um caso recusado, 2 para um arquivo de árvore de aberturas declarado mas ausente (veja Referência da CLI — Códigos de saída). O modelo 1dtoy sempre passa na validação.


Terminal window
novomodelo run my_first_study --output my_first_study/results

O Novo Modelo executa o laço de treinamento (training) da PDDE (128 iterações, 1 simulação forward em cada) seguido de uma simulação final (100 cenários). A saída é gravada em my_first_study/results/. O banner, um cabeçalho de execução/preparação, o progresso e o resumo pós-execução são impressos no stdout; avisos e erros vão para o stderr. Em um terminal, as barras de progresso são desenhadas no stderr. O resumo de cada fase segue seu progresso; este trecho começa no resumo do treinamento e omite as linhas de progresso da simulação:

Training complete in 0.5s (128 iterations, iteration_limit)
Lower bound: 2.06161e7 $/stage
Upper bound: 5.79592e5 +/- 0.00000e0 $/stage
Gap: -97.18865% (started at 72.91002%)
Policy rows: 384 active / 384 generated
LP solves: 5632 (5632 first-try, 0 retried, 0 failed)
Avg iter: 4ms
Time split: Forward 2ms (<1%) solve 2ms · wait 0ms (0% of phase)
Backward 237ms (44%) solve 237ms · wait 0ms (0% of phase)
Serial 298ms (55%) bound 85ms · selection 0ms · other 213ms
Writing training outputs...
Output written to my_first_study/results/ (0.0s)
Simulation starting... (100 scenarios across 1 ranks × 1 threads)
Simulation complete in 0.5s (100 scenarios)
Completed: 100 Failed: 0
Expected cost: 1.28652e7 +/- 5.74102e6 (std: 2.92909e7)
LP solves: 400 (400 first-try, 0 retried, 0 failed)
Avg/scenario: 0.006s
Time split: Solver 328ms (59%)
Other 231ms (41%)
Writing simulation outputs...
Output written to my_first_study/results/ (0.0s)

O diretório de resultados contém os dados de convergência do treinamento, um checkpoint da política em FlatBuffers e arquivos Parquet particionados no estilo Hive com os resultados de despacho da simulação. Isto é o que o modelo 1dtoy produz:

my_first_study/results/
training/
_SUCCESS
metadata.json
convergence.parquet
hydro_models.json
model_provenance.json
scaling_report.json
dictionaries/
solver/
timing/
policy/
manifest.bin
cuts/
000.bin ... 003.bin
basis/
000.bin ... 003.bin
simulation/
_SUCCESS
metadata.json
paths.parquet
scenario_summary.parquet
buses/
costs/
hydro_bus_generation/
hydros/
inflow_lags/
solver/
thermals/

A árvore depende do modelo de caso. policy/basis/ contém um arquivo por estágio somente quando o treinamento produziu uma base para aproveitamento (warm-start da base) naquele estágio (o próprio diretório é sempre criado), e casos com outras entidades acrescentam outras partições da simulação — por exemplo pumping_stations/, contracts/, in_transit/ e violations/ de restrições genéricas. Consulte Formato de saída para o esquema oficial e condicional de cada arquivo.


O caso 1dtoy tem um barramento cuja demanda não atendida (déficit) custa 7500 $/MWh. A usina hidrelétrica UHE1 tem um reservatório de 1000 hm³ que começa com 83,222 hm³ e turbina até 50 m³/s com 1 MW por m³/s. As usinas termelétricas UTE1 e UTE2 fornecem 15 MW cada, a 5 e 10 $/MWh. A demanda é constante, de 75 MW.

O horizonte tem quatro estágios mensais, do estágio 1 (janeiro de 2024) ao estágio 4 (abril de 2024), com um patamar de carga cada. Cada estágio sorteia dez aberturas de afluência (num_openings) a partir das estatísticas sazonais em scenarios/ (média de 40 m³/s), sem defasagens autorregressivas. A taxa de desconto anual é 0,12.

Os arquivos de configuração e as saídas identificam os mesmos estágios pelo stage_id declarado, de 0 a 3 aqui; os arquivos da política 000.bin … 003.bin são numerados a partir de 0 na ordem dos estágios. Veja Indexação dos estágios.

Para uma iteração da PDDE resolvida à mão em um sistema com um reservatório, veja o Exemplo didático de PDDE com um reservatório; o Exemplo didático de PDDE com quatro reservatórios o estende a quatro reservatórios.

  • Unidades. O limite inferior, o limite superior e o custo esperado são, cada um, um total esperado para todo o horizonte: os custos dos quatro estágios, descontados para o início do estágio 1, na moeda dos custos do caso. Apesar do rótulo $/stage, nenhum deles é um valor por estágio.
  • Faixa. O número após +/- na linha Upper bound é o desvio-padrão dos custos das simulações forward daquela iteração. Com forward_passes: 1 há um custo por iteração, de modo que a dispersão é zero e a linha imprime +/- 0.00000e0. Na linha Expected cost, +/- é a semiamplitude do intervalo de confiança de 95 % para a média e std é o desvio-padrão dos custos dos cenários.
  • Gap negativo. O limite superior é o custo da única trajetória amostrada na iteração. O gap de otimalidade é esse custo menos o limite inferior, relativo ao limite inferior, de modo que uma trajetória mais barata que o limite inferior produz um gap negativo. A maioria das trajetórias deste caso custa cerca de 6e5; as que ficam sem água pagam o custo de déficit, chegando a cerca de 2e8 ao longo das 128 iterações. A última iteração sorteou uma barata. Com simulações forward amostradas, o gap é uma estimativa, não uma garantia.
  • Limite inferior acima da média simulada. O limite inferior é o valor esperado do primeiro estágio sobre suas dez aberturas, com os cortes treinados. O custo esperado é a média de 100 cenários sorteados das mesmas dez aberturas por estágio. O desvio-padrão deles (2,92909e7) é mais que o dobro da média: a maioria dos cenários é barata e alguns são muito caros, de modo que uma média de 100 cenários frequentemente fica abaixo do custo esperado que estima, e o limite inferior nunca excede esse custo esperado. Um valor maior de simulation.selection.num_scenarios estreita o intervalo.
  • Reprodutibilidade. Os limites, o gap, o custo esperado e as contagens de linhas da política e de resoluções de PL são os mesmos em toda execução; apenas os tempos variam conforme a máquina. As dez aberturas de afluência e os sorteios dentro da amostra (in-sample) usam a semente training.tree_seed (não definida no modelo, de modo que se aplica o padrão 42). training.scenario_source.seed define a semente apenas dos sorteios fora da amostra (out-of-sample), que este caso não usa; Resolução das sementes descreve ambas as sementes. Alterar training.tree_seed, o critério de parada ou forward_passes altera os limites. O formato completo do resumo, incluindo o bloco Time split, está documentado em Referência da CLI — Formato da saída.

O histórico de convergência e os custos da simulação são arquivos Parquet comuns. Instale polars e matplotlib com pip install polars matplotlib e execute os trechos a partir do diretório que contém my_first_study/. O primeiro imprime as três últimas iterações de training/convergence.parquet e resume os custos por cenário em simulation/costs/:

import polars as pl
conv = pl.read_parquet("my_first_study/results/training/convergence.parquet")
print(conv.select("iteration", "lower_bound", "upper_bound", "gap_percent").tail(3))
costs = pl.read_parquet("my_first_study/results/simulation/costs/")
per_scenario = costs.group_by("scenario_id").agg(
(pl.col("discount_factor") * pl.col("immediate_cost")).sum().alias("cost")
)
print(per_scenario.select(
pl.col("cost").mean().alias("mean"),
pl.col("cost").median().alias("median"),
pl.col("cost").max().alias("max"),
))
shape: (3, 4)
┌───────────┬─────────────┬───────────────┬─────────────┐
│ iteration ┆ lower_bound ┆ upper_bound ┆ gap_percent │
│ --- ┆ --- ┆ --- ┆ --- │
│ i32 ┆ f64 ┆ f64 ┆ f64 │
╞═══════════╪═════════════╪═══════════════╪═════════════╡
│ 126 ┆ 2.0616e7 ┆ 615923.497494 ┆ -97.012421 │
│ 127 ┆ 2.0616e7 ┆ 615923.497494 ┆ -97.012421 │
│ 128 ┆ 2.0616e7 ┆ 579592.198622 ┆ -97.188649 │
└───────────┴─────────────┴───────────────┴─────────────┘
shape: (1, 3)
┌──────────┬───────────────┬──────────┐
│ mean ┆ median ┆ max │
│ --- ┆ --- ┆ --- │
│ f64 ┆ f64 ┆ f64 │
╞══════════╪═══════════════╪══════════╡
│ 1.2865e7 ┆ 615923.497494 ┆ 1.4053e8 │
└──────────┴───────────────┴──────────┘

A última linha repete os limites e o gap do resumo, e a média é o custo esperado do resumo; a mediana mostra que a maioria dos cenários é barata e o máximo, que alguns são muito caros — a cauda longa descrita em Como ler o resumo. O custo de um cenário neste caso é a soma, ao longo dos estágios, de discount_factor * immediate_cost; total_cost também inclui a estimativa de custo futuro, de modo que somá-lo não reproduz o custo esperado.

O segundo trecho traça os dois limites em função do número da iteração. Ele grava convergence.png no diretório de trabalho, portanto roda sem tela:

import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
import polars as pl
conv = pl.read_parquet("my_first_study/results/training/convergence.parquet")
fig, ax = plt.subplots()
ax.plot(conv["iteration"], conv["lower_bound"], label="lower bound")
ax.plot(conv["iteration"], conv["upper_bound"], label="upper bound (one forward pass)")
ax.set_yscale("log")
ax.set_xlabel("iteration")
ax.set_ylabel("expected cost")
ax.legend()
fig.savefig("convergence.png")
print("saved convergence.png")
saved convergence.png

Em convergence.png, no eixo logarítmico, o limite inferior sobe a partir de 1,23e7 e se estabiliza perto de 2,06e7, enquanto o limite superior de uma única simulação forward fica perto de 6e5 na maioria das iterações, com picos de até 1,99e8.

Convergência e diagnóstico descreve cada arquivo de saída, e o Guia rápido em Python executa e lê o mesmo estudo a partir do Python.


O limite superior no Passo 3 vem de uma simulação forward por iteração e o custo esperado, de 100 cenários; portanto, ambos são estimativas ruidosas. Duas chaves de config.json controlam esse ruído: training.selection.forward_passes, o número de trajetórias amostradas em cada iteração, e simulation.selection.num_scenarios, o número de cenários simulados. Defina esses dois valores em my_first_study/config.json e mantenha todas as demais chaves; este trecho mostra os dois objetos:

{
"training": { "selection": { "method": "sampled", "forward_passes": 10 } },
"simulation": { "selection": { "method": "sampled", "num_scenarios": 2000 } }
}

Execute o estudo novamente em um segundo diretório de saída, para que os resultados do Passo 3 continuem disponíveis para comparação. A simulação de 2000 cenários grava cerca de 10.000 arquivos, aproximadamente 70 MB:

Terminal window
novomodelo run my_first_study --output my_first_study/results-more

O resumo pós-execução, em trecho (os tempos variam conforme a máquina):

Training complete in 10.9s (128 iterations, iteration_limit)
Lower bound: 2.06178e7 $/stage
Upper bound: 1.73930e7 +/- 2.30248e7 $/stage
Gap: -15.64066% (started at -13.72705%)
Policy rows: 3840 active / 3840 generated
Simulation complete in 31.2s (2000 scenarios)
Completed: 2000 Failed: 0
Expected cost: 2.16935e7 +/- 1.92862e6 (std: 4.40053e7)

Com esses valores, o limite superior de cada iteração é a média de dez custos de trajetória, impressa com seu desvio-padrão, e o gap (-15,64066 % na última iteração) continua sendo uma estimativa que varia de iteração para iteração. O custo esperado dos 2000 cenários é um intervalo de confiança de 95 %, 2.16935e7 +/- 1.92862e6, que contém o limite inferior; assim, os dois concordam dentro do ruído de amostragem. O limite inferior termina ligeiramente acima do Passo 3, em 2.06178e7, com dez cortes adicionados por estágio em cada iteração (3840 linhas da política: 128 iterações, dez cortes para cada um dos três estágios que recebem cortes). Um gap exato, e o critério de parada gap, exigem seleção forward enumerada, que as dez aberturas por estágio deste caso não admitem; Convergir até um gap apresenta a configuração.


Você concluiu um estudo completo de PDDE, da preparação do caso aos resultados. As páginas a seguir aprofundam como o caso é estruturado e como interpretar a saída: