Pular para o conteúdo

API Python

O pacote novomodelo é o binding Python do solver Novo Modelo (import novomodelo). Esta página lista a assinatura, o comportamento, o formato de retorno e as classes de exceção levantadas de cada nome público do pacote novomodelo, de novomodelo.run, novomodelo.io, novomodelo.results, novomodelo.errors e novomodelo.schema, além dos campos das classes de dados em novomodelo.model e dos dicts de resultado tipados em novomodelo._types. Para instalar o pacote, veja Instalação; para uma primeira sessão guiada, veja o Guia rápido em Python.

Convenções usadas em todas as entradas:

  • Os caminhos aceitam str ou pathlib.Path.
  • O pacote é executado em um único processo. Ele nunca inicializa o MPI e libera o GIL (o global interpreter lock do Python) enquanto o solver calcula.
  • Os diagnósticos de aviso são gravados no descritor de arquivo 2. contextlib.redirect_stderr não os captura.
  • Cada cabeçalho é o nome qualificado de um símbolo e é a âncora dessa entrada (#novomodelostudytrain para novomodelo.Study.train).
__version__: str

A string de versão do pacote, por exemplo 0.21.0.

def version_info() -> dict[str, Any]: ...

Descreve a compilação em execução. O dict tem as chaves version (igual a novomodelo.__version__), solver (o backend de PL e sua versão), comm (sempre local, pois o pacote é de processo único), zstd (enabled), arch (arquitetura-alvo e sistema operacional) e build (debug ou release).

Retorna: o dict de descrição da compilação.

import novomodelo
print(novomodelo.version_info())
{'version': '0.21.0', 'solver': 'HiGHS 1.13.1', 'comm': 'local', 'zstd': 'enabled', 'arch': 'x86_64-linux', 'build': 'release'}
class Study:
def __init__(
self,
case_dir: str | Path,
output_dir: str | Path | None = None,
threads: int | None = None,
config_overrides: Mapping[str, Any] | None = None,
) -> None: ...

Um estudo carregado e reutilizável. A construção carrega o caso, resolve a configuração, executa o pré-processamento estocástico e dos modelos hidrelétricos e grava training/scaling_report.json, training/model_provenance.json e training/hydro_models.json (além das exportações estocásticas, quando habilitadas) em output_dir. A validação ocorre aqui: um caso ou uma configuração que falha na validação levanta exceção no construtor, de modo que um Study construído é válido.

Parâmetros

  • case_dir: o diretório do caso.
  • output_dir: onde os resultados são gravados. Padrão: <case_dir>/output.
  • threads: threads de trabalho para o treinamento (training) e a simulação, no mínimo 1. None executa em uma thread, e não em todos os núcleos. O valor é armazenado para train e simulate e não é usado durante a carga.
  • config_overrides: um mapeamento plano de chaves com pontos, mesclado em profundidade em config.json. {"training.enabled": False} define apenas essa chave e mantém as chaves irmãs. Um valor aninhado sob uma única chave substitui o objeto inteiro nessa chave; assim, {"training": {"enabled": False}} descarta todas as demais chaves de training e falha na validação. Uma chave desconhecida falha na validação. Para as chaves, veja Configuração.

Levanta

  • OSError (embutida) quando case_dir não existe, antes de qualquer processamento.
  • ValueError (embutida) quando threads é 0, ou quando config_overrides tem uma chave que não é str ou um tipo de valor não suportado.
  • novomodelo.errors.ValidationError para falha de sobrescrita, de interpretação ou de leitura da configuração; para arquivo do caso ausente ou ilegível; para falha de esquema, de interpretação ou de restrição nos dados do caso; para um policy.path recusado; e para falha de preparação por entrada inválida, como um modelo estocástico não suportado (no valid historical windows found).
  • novomodelo.errors.CaseIoError quando a gravação de um desses arquivos falha, por exemplo em um output_dir sem permissão de escrita.
  • novomodelo.errors.SolverError para falha do solver ou falha interna durante o pré-processamento ou a construção.
@property
def output_dir(self) -> str: ...

O diretório de saída resolvido, como string.

@property
def system(self) -> System: ...

O novomodelo.model.System carregado. A propriedade compartilha o sistema do estudo; não o copia.

@property
def stochastic(self) -> StochasticSummary: ...

O resumo estrutural da parte estocástica, um dict fixado na construção. Seu formato é novomodelo._types.StochasticSummary.

@property
def hydro_models(self) -> HydroModelsSummary: ...

O resumo estrutural dos modelos hidrelétricos, um dict fixado na construção. Seu formato é novomodelo._types.HydroModelsSummary; para o caso-modelo 1dtoy, ele vale {'n_constant': 1, 'n_fpha': 0, 'total_planes': 0, 'n_evaporation': 0, 'n_no_evaporation': 1}.

@property
def provenance(self) -> ProvenanceReport: ...

O relatório de procedência do modelo, um dict fixado na construção. Seu formato é novomodelo._types.ProvenanceReport.

def validate(self) -> dict[str, Any]: ...

Reporta os avisos capturados durante a construção e verifica a carga da política configurada em relação ao output_dir do estudo, sem reler o caso.

Retorna: {"valid": True, "errors": [], "warnings": [...]}. O resultado tem o mesmo formato de novomodelo.io.validate. valid é False, com o erro que novomodelo.io.validate reporta para esse diretório, quando a carga da política configurada falha; os avisos da carga da política são acrescentados a warnings.

def train(
self,
on_iteration: Callable[[dict[str, Any]], Any] | None = None,
) -> Policy: ...

Treina uma política PDDE (SDDP) sobre a preparação em memória do estudo e retorna um novomodelo.Policy. A chamada grava a política em <output_dir>/<policy.path> (padrão policy/) e os artefatos do treinamento em training/. O GIL é liberado enquanto o solver calcula; o callback é executado em uma thread separada, que só obtém o GIL nas fronteiras entre iterações.

Parâmetros

  • on_iteration: chamado uma vez em cada fronteira entre iterações com um dict contendo kind, iteration, lower_bound, upper_bound, gap e wall_time_ms. gap é o gap relativo bruto, não multiplicado por 100. Um retorno verdadeiro solicita uma parada cooperativa em uma fronteira de iteração posterior; a parada é assíncrona, de modo que a iteração em que a execução termina não é fixa. Uma exceção levantada pelo callback é relançada sem alteração depois que os artefatos são gravados.

Uma parada solicitada pelo callback, ou uma exceção levantada por ele, encerra a execução com convergence.termination_reason igual a "graceful_shutdown" e status igual a "partial" em training/metadata.json, a menos que os critérios de parada ou o limite de iterações também a tenham encerrado nessa iteração; veja training/metadata.json.

Retorna: um novomodelo.Policy. Com training.enabled igual a false, train retorna uma política com zero iterações e sem cortes; simulate a rejeita. Nesse caso, carregue uma política treinada com load_policy.

Uma segunda chamada a train no mesmo Study é executada sobre uma preparação que já contém os cortes da primeira chamada, portanto não é um treinamento do zero. No caso-modelo 1dtoy, a segunda chamada levanta SolverError (basis row count mismatch).

Levanta

  • novomodelo.errors.SolverError para falha de inicialização do solver ou falha de treinamento classificada pelo solver.
  • novomodelo.errors.ValidationError para diretório de política anterior ausente em partida a quente (warm-start) ou retomada (Policy directory not found: ...), e para entrada de fronteira ou de treinamento recusada.
  • novomodelo.errors.PolicyIncompatibleError quando o checkpoint de partida a quente ou de retomada em policy.path não atende ao Contrato de carga da política, quando um checkpoint de policy.boundary foi gravado por outro software ou outra versão, ou quando o manifest.bin de um checkpoint está ausente ou não pode ser decodificado.
  • novomodelo.errors.CaseIoError quando a gravação da política ou de um artefato do treinamento falha; uma falha na gravação de checkpoint periódico levanta FileNotFoundError, CaseIoError, novomodelo.errors.OutputError ou ValidationError, conforme a causa.
  • novomodelo.errors.InternalError quando a thread do callback entra em pânico (panic).
  • Qualquer exceção levantada pelo callback, e KeyboardInterrupt, relançadas depois que os artefatos são gravados.
def load_policy(
self,
output_dir: str | Path | None = None,
) -> Policy: ...

Lê um checkpoint da política de <output_dir>/<policy.path>/ e retorna um novomodelo.Policy que simulate aceita da mesma forma que uma política treinada. O checkpoint é sempre verificado em relação à dimensão do estado, ao número de estágios e ao manifesto de entidades terminais do estudo.

Parâmetros

  • output_dir: o diretório que contém a política. Padrão: o output_dir do estudo.

Retorna: o novomodelo.Policy carregado.

Levanta

  • novomodelo.errors.ValidationError quando o diretório da política está ausente (Policy directory not found: ...).
  • novomodelo.errors.PolicyIncompatibleError quando o checkpoint não pode ser lido, decodificado ou reconstruído, ou quando a validação da política o rejeita.
  • novomodelo.errors.CaseIoError quando um arquivo do checkpoint não pode ser aberto.
def simulate(
self,
policy: Policy,
output_dir: str | Path | None = None,
) -> dict[str, Any]: ...

Executa a fase de simulação com policy e grava os artefatos de simulation/. Cada chamada grava um conjunto novo de saídas, e uma mesma política pode alimentar chamadas repetidas.

Parâmetros

  • policy: um novomodelo.Policy obtido de train ou load_policy.
  • output_dir: onde o diretório simulation/ é gravado. Padrão: o output_dir do estudo.

Retorna: {"n_scenarios": int, "completed": int}, por exemplo {'n_scenarios': 10, 'completed': 10}.

Levanta

  • novomodelo.errors.SolverError quando a política não tem cortes (Policy has no cuts to simulate; when training is disabled, call Study.load_policy() to load a trained policy before simulate()), ou em falha de inicialização do espaço de trabalho da simulação.
  • novomodelo.errors.SimulationError para falha da simulação.
  • novomodelo.errors.CaseIoError para falha do gravador.
  • novomodelo.errors.InternalError quando a thread de trabalho entra em pânico (panic).
class Policy: ...

Uma política treinada ou carregada: os cortes de Benders que aproximam o custo futuro de cada estágio, juntamente com os dados de que novomodelo.Study.simulate precisa. A classe não tem construtor Python; novomodelo.Policy() levanta TypeError (cannot create 'builtins.Policy' instances). Obtenha uma instância a partir de novomodelo.Study.train ou novomodelo.Study.load_policy.

Todo argumento stage é numerado a partir de 0: o estágio t da numeração a partir de 1 usada na metodologia é stage = t - 1.

evaluate e cut_matrix leem o conjunto de cortes em memória, que armazena termos independentes e coeficientes na escala de custo do solver: unidades monetárias divididas pelo cost_scale_factor do conjunto (modeling.cost_scale_factor, 1000000.0 por padrão). O checkpoint armazena os mesmos valores escalonados, de modo que novomodelo.results.load_policy também os retorna. Multiplique por cost_scale_factor para obter unidades monetárias. final_lower_bound e final_upper_bound estão em unidades monetárias. Para a conversão, veja Canonicalização da escala de custo.

@property
def iterations(self) -> int: ...

O número de iterações de treinamento concluídas. Uma política obtida de load_policy reporta o completed_iterations do checkpoint; uma política com treinamento desabilitado reporta 0.

@property
def final_lower_bound(self) -> float: ...

O limite inferior final, em unidades monetárias. Uma política obtida de load_policy reporta o limite inferior final registrado no checkpoint; uma política com treinamento desabilitado reporta 0.0.

@property
def final_upper_bound(self) -> float: ...

O limite superior médio final, em unidades monetárias. Uma política obtida de load_policy reporta o limite superior registrado no checkpoint (o valor da última iteração do treinamento, e não o melhor valor acumulado), ou inf quando o checkpoint não registra nenhum; uma política com treinamento desabilitado reporta inf.

def evaluate(self, stage: int, state: Sequence[float]) -> float: ...

Avalia a função de custo futuro em state: o máximo, sobre os cortes ativos do estágio, de intercept + coeffs · state. O valor está na escala de custo do solver, e não em unidades monetárias (veja novomodelo.Policy). Um estágio sem corte ativo retorna float('-inf'); o último estágio do caso 1dtoy não tem nenhum.

Parâmetros

  • stage: o índice do estágio, a partir de 0.
  • state: o estado de entrada, um float por dimensão do estado da política (1 para o caso 1dtoy).

Retorna: o valor do custo futuro como float.

Levanta

  • IndexError (embutida) quando stage é maior ou igual ao número de estágios (stage 4 out of range (policy has 4 stages)).
  • ValueError (embutida) quando state tem comprimento errado (state has length 2, expected 1 (policy state dimension)).
  • OverflowError (embutida) quando stage é negativo.
def cut_matrix(self, stage: int) -> tuple[Any, Any]: ...

Retorna os cortes ativos de um estágio como dois arrays NumPy, em ordem crescente de slot. Leia o corte k como θ ≥ intercepts[k] + coeffs[k] · state. Os coeficientes são os valores armazenados, sem negação. Os valores estão na escala de custo do solver, e não em unidades monetárias (veja novomodelo.Policy).

Parâmetros

  • stage: o índice do estágio, a partir de 0.

Retorna: (intercepts, coeffs), dois arrays float64 com formatos (n_cuts,) e (n_cuts, dim), em que dim é a dimensão do estado da política. Um estágio sem corte ativo retorna os formatos (0,) e (0, dim).

Levanta

  • IndexError (embutida) quando stage é maior ou igual ao número de estágios.
  • OverflowError (embutida) quando stage é negativo.
  • ImportError (embutida) quando o NumPy não está instalado.
import novomodelo
import novomodelo.results
study = novomodelo.Study("case", output_dir="output")
policy = study.train()
intercepts, coeffs = policy.cut_matrix(0)
print(intercepts.shape, coeffs.shape)
print(policy.evaluate(0, [50.0]))
saved = novomodelo.results.load_policy("output")
stage0 = saved["stage_cuts"][0]
print(intercepts[0], stage0["cuts"][0]["intercept"])
print(stage0["cost_scale_factor"])
print(round(stage0["cuts"][0]["intercept"] / intercepts[0]))
(128,) (128, 1)
29.299602605817185
59.78879458073438 59.78879458073438
1000000.0
1

O termo independente salvo é igual ao que está em memória: ambos estão na escala de cost_scale_factor. O resultado de evaluate, de cerca de 29.30, corresponde portanto a cerca de 29299603 em unidades monetárias.

def write_policy_checkpoint(
path: str | Path,
stage_cuts: Sequence[Mapping[str, Any]],
metadata: Mapping[str, Any],
stage_bases: Sequence[Mapping[str, Any]] | None = None,
stage_states: Sequence[Mapping[str, Any]] | None = None,
inflow_lag_depth: int | None = None,
) -> None: ...

Grava um checkpoint da política em path a partir de dicts Python simples. stage_cuts, metadata, stage_bases e stage_states têm os formatos das chaves que novomodelo.results.load_policy retorna, de modo que um checkpoint carregado faz o percurso de ida e volta; as chaves de um resultado carregado que o gravador não lê são ignoradas. stage_bases e stage_states são vazios por padrão. Toda entrada de stage_cuts exige um cost_scale_factor, finito e positivo: os termos independentes e coeficientes da entrada estão nas unidades desse fator, de modo que uma política elaborada em unidades monetárias informa 1.0. O cost_scale_factor de metadata["producer"] serve apenas como procedência e nunca substitui um fator ausente do conjunto. O checkpoint sempre registra a versão do novomodelo em execução; as chaves software, software_version ou novomodelo_version em metadata são ignoradas. Para os formatos dos dicts, veja Gravar um checkpoint, Exemplo de ida e volta e Validação da entrada.

inflow_lag_depth = N com N > 0 reserva N slots de estado de tendência hidrológica por usina com reservatório em cada estágio e posiciona os inflow_lag_coefficients de cada corte em suas posições (hydro, depth). Use-o para elaborar uma política de fronteira para um caso convertido que não tenha modelo PAR(p) do qual inferir a profundidade. Ausente ou 0, o checkpoint é idêntico a um gravado sem o argumento.

Retorna: None.

Levanta

  • ValueError (embutida) quando um dict contém uma chave que não faz parte de um checkpoint da política: active_cut_indices em uma entrada de stage_cuts, cut_id em um corte, ou num_cut_rows, num_columns ou num_rows em uma entrada de stage_bases (stage_cuts[0]: key 'active_cut_indices' is not part of a policy checkpoint (format 4); remove it, indicando a posição). Essas chaves são verificadas antes da leitura de stage_cuts e stage_bases.
  • ValueError (embutida) quando o cost_scale_factor de uma entrada de stage_cuts está ausente, não é finito ou não é positivo (stage_cuts[{index}] (stage_id {id}): cost_scale_factor is required; the intercepts and coefficients are in the units of this factor (pass 1.0 for values in currency units), ou must be finite and positive, got {value} no lugar de is required).
  • ValueError (embutida) quando o comprimento de coefficients de um corte difere do state_dimension de seu estágio, quando um corte contém inflow_lag_coefficients sem um inflow_lag_depth positivo ou, com inflow_lag_depth definido, quando o manifesto de um estágio não tem um bloco inicial de armazenamento ou um coeficiente de tendência hidrológica não tem slot onde ser posicionado.
  • ValueError (embutida) quando metadata["producer"]["basis_store_complete"] é True e stage_bases não contém nenhuma base, ou quando o state_history do produtor é diferente de None, "whole" ou de um inteiro positivo (um bool é recusado).
  • ValueError (embutida), com a mensagem da regra, quando os dados violam uma regra do checkpoint antes que algo seja gravado: ordem dos slots, contagem de linhas (incluindo um comprimento dos dados de estado de um estágio diferente de count * state_dimension), presença de contadores, datas, id repetido ou limite de tamanho (Validação da entrada).
  • novomodelo.errors.ValidationError (uma ValueError) quando path (no caso de um link, seu destino) ou seu irmão .staging ou .previous contém uma entrada que nenhum gravador de checkpoint deixaria ali (refusing to write a checkpoint: ...); nada é alterado no disco.
  • Uma classe de novomodelo.errors mapeada a partir da falha de gravação subjacente, para qualquer outro erro, como novomodelo.errors.OutputError.
def run(
case_dir: str | Path,
output_dir: str | Path | None = None,
threads: int | None = None,
config_overrides: Mapping[str, Any] | None = None,
on_iteration: Callable[[dict[str, Any]], bool | None] | None = None,
) -> RunResult: ...

Carrega um caso, executa o treinamento, executa a simulação quando a configuração a habilita e grava os resultados. Um único novomodelo.Study conduz a chamada. As fases executadas seguem a configuração, em três ramos.

Parâmetros

Retorna: um dict com o formato novomodelo._types.RunResult. Todas as chaves estão presentes em todos os ramos; os valores abaixo diferem por ramo.

Ramoconvergediterationslower_boundupper_boundgap_percentsimulation
Treinamento habilitadoTrue quando os critérios de parada encerraram o treinamento e uma regra gap ou bound_stalling foi acionada nessa iteração; False para qualquer outro motivo de paradaiterações executadaslimite inferior finallimite superior finalgap vezes 100o dict de resumo, ou None se a simulação estiver desabilitada
Treinamento desabilitado, simulação habilitada (somente simulação)False0o limite inferior do checkpointo limite superior registrado no checkpoint (o valor da última iteração do treinamento), None se não for finitoNoneo dict de resumo
Ambos desabilitadosFalse00.0NoneNoneNone

gap_percent é o gap relativo vezes 100; veja Gap de otimalidade. Uma execução somente de simulação carrega a política de <output_dir>/<policy.path>/ (padrão policy/); veja Modo somente simulação. As chaves stochastic, hydro_models e provenance contêm os mesmos resumos que as propriedades de Study.

Um Ctrl-C durante a execução é entregue como KeyboardInterrupt depois que a chamada retorna ao interpretador, e não em uma fronteira entre iterações. Para encerrar uma execução antecipadamente, retorne um valor verdadeiro em on_iteration.

Uma parada solicitada por on_iteration registra convergence.termination_reason como "graceful_shutdown" em training/metadata.json, a menos que os critérios de parada ou o limite de iterações também a tenham encerrado nessa iteração; veja training/metadata.json.

Levanta

  • OSError (embutida) quando case_dir não existe.
  • ValueError (embutida) quando threads é 0, ou quando config_overrides está malformado.
  • As classes listadas para novomodelo.Study, novomodelo.Study.train e novomodelo.Study.simulate, conforme a fase que falhar.
  • Qualquer exceção levantada pelo callback, relançada sem alteração depois que os artefatos são gravados.
import novomodelo.run
def on_iteration(info):
print(info)
return info["iteration"] >= 3 # um retorno verdadeiro solicita a parada
novomodelo.run.run("case", output_dir="output", on_iteration=on_iteration)
{'kind': 'iteration', 'iteration': 1, 'lower_bound': 12282078.645359337, 'upper_bound': 21236944.064237654, 'gap': 0.7291001529502358, 'wall_time_ms': 5}
{'kind': 'iteration', 'iteration': 2, 'lower_bound': 14580933.839768976, 'upper_bound': 594119.1709722562, 'gap': -0.9592536954422071, 'wall_time_ms': 8}
{'kind': 'iteration', 'iteration': 3, 'lower_bound': 15245185.133569857, 'upper_bound': 18707186.646276567, 'gap': 0.22708819095173807, 'wall_time_ms': 12}

wall_time_ms varia entre execuções. A parada solicitada na iteração 3 só tem efeito em uma fronteira de iteração posterior, de modo que a execução pode terminar depois de mais de três iterações.

def load_case(path: str | Path) -> model.System: ...

Carrega e valida um diretório de caso por meio de todo o processo de validação e retorna um novomodelo.model.System. Um caminho relativo é resolvido a partir do diretório de trabalho do processo.

Parâmetros

  • path: o diretório do caso.

Retorna: o novomodelo.model.System validado.

Levanta

  • OSError (embutida) quando o diretório não existe.
  • novomodelo.errors.ValidationError para arquivo do caso ausente ou ilegível (reportado como violação de restrição [FileNotFound]) e para falha de interpretação, de esquema ou de restrição.
def validate(
path: str | Path,
config_overrides: Mapping[str, Any] | None = None,
*,
output_dir: str | Path | None = None,
) -> dict[str, Any]: ...

Executa todo o processo de validação (estrutura do caso, esquema, configuração, preparação estocástica, modelos hidrelétricos, restrições genéricas, montagem do estudo, reconciliação da fronteira quando configurada e a carga da política configurada — partida a quente, retomada ou somente simulação — a partir de <output_dir>/<policy.path>) e para na primeira falha. validate retorna as falhas como dados; não levanta exceção para um caso inválido.

Parâmetros

  • path: o diretório do caso. Um diretório ausente produz uma entrada de falha do tipo IoError.
  • config_overrides: como em novomodelo.Study.
  • output_dir: somente nomeado (keyword-only); o diretório de onde a carga da política lê. Padrão: <path>/output; um caminho relativo é resolvido a partir do diretório de trabalho. Nada é gravado, e um diretório ausente não é criado.

Retorna: um dict com valid (bool), errors (uma lista de dicts {"kind", "message"}; vazia quando valid é True) e warnings (uma lista de dicts {"kind", "message", "file", "entity"}). Os avisos não alteram valid.

Levanta

  • ValueError (embutida) apenas quando config_overrides está malformado.
import novomodelo.io
report = novomodelo.io.validate("case")
print(report)
{'valid': True, 'errors': [], 'warnings': []}

Funções de carga dos artefatos que uma execução grava em seu diretório de saída. Todas as funções recebem output_dir, o diretório que contém training/, simulation/, policy/ e stochastic/. Um caminho relativo é resolvido a partir do diretório de trabalho do processo, e um output_dir ausente levanta FileNotFoundError. NumPy e pyarrow são dependências opcionais, importadas apenas pelas funções que retornam seus tipos. Para interpretar os números, veja Convergência e diagnóstico.

def load_results(output_dir: str | Path) -> dict[str, Any]: ...

Lê os manifestos da execução.

Parâmetros

  • output_dir: o diretório de saída.

Retorna: um dict com dois sub-dicts.

  • "training": "metadata", o training/metadata.json interpretado; "manifest", um alias de "metadata" com o mesmo conteúdo; "convergence_path" e "timing_path", os caminhos absolutos de training/convergence.parquet e training/timing/iterations.parquet; e "complete".
  • "simulation": "manifest", o simulation/metadata.json interpretado, ou None quando esse arquivo está ausente (a simulação não foi executada); e "complete".

Os dois valores "complete" são indicadores do marcador _SUCCESS, e não um veredito sobre a execução. training["complete"] é sempre True em um dict retornado, porque a chamada levanta exceção quando o marcador training/_SUCCESS está ausente. simulation["complete"] é True quando simulation/_SUCCESS existe, e False caso contrário. Para saber como uma execução terminou, leia os dicts metadata; veja Arquivos de metadados.

Levanta

  • FileNotFoundError (embutida) quando output_dir ou training/_SUCCESS está ausente.
  • ValueError (embutida) quando um arquivo de metadados não é um JSON válido.
  • OSError (embutida) para outras falhas de leitura.
def load_convergence(output_dir: str | Path) -> Any: ...

Lê training/convergence.parquet; para as colunas, veja training/convergence.parquet.

Parâmetros

  • output_dir: o diretório de saída.

Retorna: uma list[dict] com um dict por linha (uma por iteração do treinamento), com as chaves correspondentes às colunas do próprio arquivo. A lista é vazia quando o arquivo não tem linhas.

Levanta

  • FileNotFoundError (embutida) quando output_dir ou training/convergence.parquet está ausente.
  • OSError (embutida) para outras falhas de E/S e falhas de decodificação do Parquet.
import novomodelo.results
import novomodelo.run
novomodelo.run.run("case", output_dir="output")
rows = novomodelo.results.load_convergence("output")
print(len(rows))
print(sorted(rows[0]))
128
['cuts_active', 'cuts_added', 'cuts_removed', 'forward_passes', 'gap_percent', 'iteration', 'lazy_round_cap_hits', 'lower_bound', 'lp_solves', 'mean_rows_in_lp', 'time_backward_ms', 'time_forward_ms', 'time_total_ms', 'upper_bound', 'upper_bound_kind', 'upper_bound_std']
def load_convergence_arrow(output_dir: str | Path) -> Any: ...

Lê o mesmo arquivo que novomodelo.results.load_convergence sem construir objetos Python para cada valor.

Parâmetros

  • output_dir: o diretório de saída.

Retorna: uma pyarrow.Table com o esquema de training/convergence.parquet.

Levanta

  • FileNotFoundError (embutida) quando output_dir ou training/convergence.parquet está ausente.
  • OSError (embutida) para falhas de decodificação do Parquet ou erros de serialização Arrow.
  • ImportError (embutida) quando o pyarrow não está instalado.
def load_simulation(
output_dir: str | Path,
entity_type: str | None = None,
) -> Any: ...

Lê os arquivos Parquet particionados no estilo Hive em simulation/; veja Saídas da simulação e Particionamento Hive. Cada dict de linha contém uma chave scenario_id, lida da coluna scenario_id do próprio arquivo ou, quando o arquivo não a tem, do caminho da partição, e as linhas são ordenadas por scenario_id.

Parâmetros

  • output_dir: o diretório de saída.
  • entity_type: o nome de um subdiretório de simulation/, como "costs", "hydros" ou "thermals". None carrega todos os diretórios de entidade existentes.

Retorna: com entity_type, uma list[dict] de dicts de linha. Sem ele, um dict[str, list[dict]] com chaves por tipo de entidade (para o caso 1dtoy: buses, costs, hydro_bus_generation, hydros, inflow_lags e thermals).

Levanta

  • FileNotFoundError (embutida) quando output_dir, simulation/ ou o diretório de entidade indicado está ausente.
  • OSError (embutida) para arquivos Parquet corrompidos e outras falhas de E/S.
def load_simulation_arrow(
output_dir: str | Path,
entity_type: str | None = None,
) -> Any: ...

Lê os mesmos arquivos que novomodelo.results.load_simulation como tabelas Arrow, com todos os cenários concatenados em ordem crescente de scenario_id.

Parâmetros

  • output_dir, entity_type: como em load_simulation.

Retorna: com entity_type, uma pyarrow.Table. Sem ele, um dict[str, pyarrow.Table] com chaves por tipo de entidade. A primeira coluna de cada tabela é scenario_id (as três primeiras colunas da tabela costs do 1dtoy são scenario_id, stage_id e node_id).

Levanta

  • FileNotFoundError (embutida) quando output_dir, simulation/ ou o diretório de entidade indicado está ausente.
  • OSError (embutida) para arquivos Parquet corrompidos ou erros de serialização Arrow.
  • ImportError (embutida) quando o pyarrow não está instalado.
def load_policy(
output_dir: str | Path,
policy_subdir: str = "policy",
) -> Any: ...

Lê o checkpoint da política de <output_dir>/<policy_subdir> para dicts simples; veja Checkpoint da política. A função não verifica a versão do novomodelo que gravou o checkpoint. Para as tabelas de chaves, veja Carregar uma política.

Parâmetros

  • output_dir: o diretório de saída.
  • policy_subdir: o diretório do checkpoint dentro de output_dir. Informe o policy.path configurado quando ele não for policy.

Retorna: um dict com as chaves metadata, stage_cuts, stage_bases e stage_states, os quatro argumentos de novomodelo.write_policy_checkpoint, de modo que regravá-los reproduz o checkpoint. stage_states contém uma entrada por conjunto que armazena estados visitados, e é uma lista vazia quando nenhum conjunto os armazena. stage_cuts contém uma entrada por conjunto de cortes, uma por estágio em uma cadeia de estágios (quatro no caso 1dtoy). Os termos independentes e coeficientes estão na escala do cost_scale_factor da entrada, os mesmos valores que novomodelo.Policy.cut_matrix retorna; multiplique por cost_scale_factor para obter unidades monetárias.

Levanta

  • FileNotFoundError (embutida) quando output_dir está ausente, ou quando o diretório da política (no caso de um link, seu destino) está ausente e nem <policy>.staging nem <policy>.previous contém um manifest.bin.
  • novomodelo.errors.OutputError (uma OSError) quando um buffer do checkpoint não pode ser lido.
def load_stochastic(output_dir: str | Path) -> Stochastic: ...

Lê o modelo estocástico ajustado de stochastic/inflow_ar_coefficients.parquet e stochastic/noise_openings.parquet; veja Artefatos estocásticos. Esses arquivos só existem quando a execução teve exports.stochastic habilitado. A construção do objeto não exige NumPy.

Parâmetros

  • output_dir: o diretório de saída.

Retorna: um objeto novomodelo.results.Stochastic.

Levanta

  • FileNotFoundError (embutida) quando output_dir ou um arquivo necessário está ausente. Sem as exportações, a mensagem é .../stochastic/inflow_ar_coefficients.parquet not found — stochastic artifacts are written only when exports.stochastic is enabled in config.json.
  • OSError (embutida) quando um arquivo Parquet não pode ser decodificado.
class Stochastic: ...

Uma visão somente leitura do modelo estocástico ajustado de uma execução. A classe não tem construtor Python; novomodelo.results.Stochastic() levanta TypeError. Obtenha um objeto a partir de novomodelo.results.load_stochastic.

def par_coefficients(self) -> Any: ...

Retorna os coeficientes ajustados do modelo PAR(p), na ordem das linhas de stochastic/inflow_ar_coefficients.parquet.

Retorna: um array NumPy float64 com formato (n_rows, 4) e colunas [hydro_id, stage_id, lag, coefficient]. As três colunas inteiras são convertidas para float64, e lag é numerado a partir de 1. O array não tem linhas em um caso com ordem do modelo AR igual a 0, como o caso 1dtoy.

Levanta

  • ImportError (embutida) quando o NumPy não está instalado.
def opening_tree(self, stage: int) -> Any: ...

Retorna as aberturas de ruído de um estágio a partir de stochastic/noise_openings.parquet. A linha k é o vetor de ruído da abertura k.

Parâmetros

  • stage: o índice do estágio, a partir de 0.

Retorna: um array NumPy float64 com formato (n_openings, dim), por exemplo (10, 1) em qualquer estágio do caso 1dtoy.

Levanta

  • IndexError (embutida) quando o estágio não está presente no arquivo (stage 9 not present in the opening tree (valid stages are 0..=3)).
  • OverflowError (embutida) quando stage é negativo.
  • ImportError (embutida) quando o NumPy não está instalado.

As classes de novomodelo.model são visões imutáveis, somente leitura, retornadas por novomodelo.io.load_case e novomodelo.Study.system; um System não pode ser construído a partir do Python, e atribuir um valor a um campo levanta AttributeError. Cada lista de entidades contém seus itens na ordem canônica (operational_start_date, id), e o significado dos campos segue os arquivos do caso, cujos JSON Schemas estão listados em Esquemas JSON.

Cada classe reporta __module__ como builtins; acesse-a como novomodelo.model.<Name>. Duas leituras da mesma lista podem retornar objetos Python diferentes para a mesma entidade; portanto, compare entidades pelos valores dos campos, e não pela identidade (is).

O sistema carregado: contagens de entidades e uma lista por classe de entidade.

CampoTipoDescrição
n_busesintO número de barramentos.
n_hydrosintO número de usinas hidrelétricas.
n_linesintO número de linhas de transmissão.
n_stagesintO número de estágios, do estudo e anteriores ao estudo.
n_thermalsintO número de usinas termelétricas.
buseslist[Bus]Os barramentos, na ordem canônica.
hydroslist[Hydro]As usinas hidrelétricas, na ordem canônica.
lineslist[Line]As linhas de transmissão, na ordem canônica. Vazia quando o caso não tem nenhuma.
thermalslist[Thermal]As usinas termelétricas, na ordem canônica.
contractslist[EnergyContract]Os contratos de energia, na ordem canônica. Vazia quando o caso não tem nenhum.
pumping_stationslist[PumpingStation]As usinas elevatórias, na ordem canônica. Vazia quando o caso não tem nenhuma.
non_controllable_sourceslist[NonControllableSource]As fontes não despacháveis, na ordem canônica. Vazia quando o caso não tem nenhuma.
import novomodelo.io
system = novomodelo.io.load_case("case")
print(system.n_hydros)
print([h.name for h in system.hydros])
print(system.hydros[0].max_storage_hm3)
1
['UHE1']
1000.0

Um nó da rede elétrica no qual se mantém o balanço de energia.

CampoTipoDescrição
idintO id da entidade no arquivo do caso.
namestrO nome da entidade no arquivo do caso.
deficit_segmentslist[dict]Os segmentos da curva de custo de déficit linear por partes, um dict por segmento com as chaves depth_mw (float, ou None para o último segmento, ilimitado) e cost_per_mwh (float, R$/MWh).
excess_costfloatO custo de absorver o excedente de geração, em R$/MWh.

Uma interligação de transmissão que transporta potência nos dois sentidos entre dois barramentos.

CampoTipoDescrição
idintO id da entidade no arquivo do caso.
namestrO nome da entidade no arquivo do caso.
source_bus_idintO id do barramento na extremidade de origem.
target_bus_idintO id do barramento na extremidade de destino.
direct_capacity_mwfloatO fluxo máximo da origem para o destino, em MW.
reverse_capacity_mwfloatO fluxo máximo do destino para a origem, em MW.
losses_percentfloatAs perdas de transmissão em percentual; 2.5 significa 2,5%.
exchange_costfloatO custo de regularização por MWh de intercâmbio, em R$/MWh.

Uma usina termelétrica com custo marginal escalar.

CampoTipoDescrição
idintO id da entidade no arquivo do caso.
namestrO nome da entidade no arquivo do caso.
bus_idintO id do barramento que a usina alimenta.
min_generation_mwfloatA geração elétrica mínima (inflexibilidade), em MW.
max_generation_mwfloatA geração elétrica máxima (potência instalada), em MW.
cost_per_mwhfloatO custo marginal de geração (CVU), em R$/MWh.

Uma usina hidrelétrica com reservatório. As usinas formam uma cascata por meio de downstream_id.

CampoTipoDescrição
idintO id da entidade no arquivo do caso.
namestrO nome da entidade no arquivo do caso.
downstream_idint | NoneO id da próxima usina da cascata. None para uma usina sem usina a jusante.
min_storage_hm3floatO armazenamento operativo mínimo (volume morto), em hm³.
max_storage_hm3floatO armazenamento operativo máximo (nível de controle de cheias), em hm³.
min_turbined_m3sfloatA vazão turbinada mínima, em m³/s.
max_turbined_m3sfloatA vazão turbinada máxima declarada, em m³/s; com max_generation_mw, decide se a usina tem capacidade de turbinamento.
productivity_mw_per_m3sfloat | NoneSempre None. A produtibilidade é resolvida por estágio a partir dos arquivos de modelos de produção.

Um contrato bilateral de energia com um sistema externo.

CampoTipoDescrição
idintO id da entidade no arquivo do caso.
namestrO nome da entidade no arquivo do caso.
operational_start_datestrA data em que a entidade entra em operação, como string ISO 8601 YYYY-MM-DD.
bus_idintO id do barramento ao qual o contrato se conecta.
contract_typestrO sentido do fluxo de energia: "import" ou "export".
entry_stage_idint | NoneO índice do estágio em que o contrato entra em vigor. None quando está ativo desde o primeiro estágio.
exit_stage_idint | NoneO índice do estágio em que o contrato expira. None quando nunca expira.
price_per_mwhfloatO preço do contrato, em R$/MWh. Um valor negativo representa receita de exportação.
min_mwfloatA potência contratada mínima, em MW.
max_mwfloatA potência contratada máxima, em MW.

Uma usina elevatória (estação de bombeamento) que transfere água entre reservatórios de usinas hidrelétricas.

CampoTipoDescrição
idintO id da entidade no arquivo do caso.
namestrO nome da entidade no arquivo do caso.
operational_start_datestrA data em que a entidade entra em operação, como string ISO 8601 YYYY-MM-DD.
bus_idintO id do barramento do qual a estação consome energia.
source_hydro_idintO id da usina hidrelétrica de onde a água bombeada é retirada.
destination_hydro_idintO id da usina hidrelétrica que recebe a água bombeada.
entry_stage_idint | NoneO índice do estágio em que a estação entra em operação. None quando está ativa desde o primeiro estágio.
exit_stage_idint | NoneO índice do estágio em que a estação é desativada. None quando nunca é desativada.
consumption_mw_per_m3sfloatO consumo de potência por unidade de vazão bombeada, em MW/(m³/s).
min_flow_m3sfloatA vazão bombeada mínima, em m³/s.
max_flow_m3sfloatA vazão bombeada máxima (capacidade instalada de bombeamento), em m³/s.

Uma fonte de geração intermitente que não é despachada.

CampoTipoDescrição
idintO id da entidade no arquivo do caso.
namestrO nome da entidade no arquivo do caso.
operational_start_datestrA data em que a entidade entra em operação, como string ISO 8601 YYYY-MM-DD.
bus_idintO id do barramento que a fonte alimenta.
entry_stage_idint | NoneO índice do estágio em que a fonte entra em operação. None quando está ativa desde o primeiro estágio.
exit_stage_idint | NoneO índice do estágio em que a fonte é desativada. None quando nunca é desativada.
max_generation_mwfloatA geração máxima (potência instalada), em MW.
allow_curtailmentboolSe o PL pode aplicar corte de geração (curtailment) à fonte. False corresponde ao regime de geração compulsória (must-run).
curtailment_costfloatO custo resolvido da geração cortada, em R$/MWh. Não é usado quando allow_curtailment é False.

Toda classe-folha é subclasse de novomodelo.errors.NovomodeloError e de uma exceção embutida, e seu __module__ é novomodelo.errors. A própria NovomodeloError é subclasse direta de Exception e reporta __module__ como errors. Para as mensagens e códigos de saída de cada tipo, veja Códigos de erro; para saber qual caminho de carga da política levanta qual classe, veja Erros de carga da política.

class NovomodeloError(Exception): ...

A classe base de todas as exceções do Novo Modelo. Capture a classe tipada para um tipo de falha, a base embutida (ValueError, OSError, RuntimeError) para manter o tratamento no estilo das exceções embutidas, ou NovomodeloError para todas elas.

class ValidationError(NovomodeloError, ValueError): ...

Os dados do caso ou a configuração falharam na validação. Levantada para um erro da classe de entrada inválida, qualquer que seja o prefixo da mensagem (inclusive um policy.path recusado, um diretório de política anterior ausente e uma gravação de checkpoint recusada por causa de seu manifesto ou de uma entrada estranha), para os prefixos de mensagem config override error, config parse error, config read error e setup validation error, e para falhas de interpretação, de esquema e de restrição nos dados do caso. Também abrange um arquivo do caso ausente ou ilegível.

class PolicyIncompatibleError(NovomodeloError, ValueError): ...

Uma política é incompatível com o sistema ou a compilação atual. Levantada para um erro da classe de política incompatível: um checkpoint de partida a quente, retomada ou somente simulação recusado por causa de seu software, de sua versão ou de uma verificação de contrato que falhou; um checkpoint de fronteira recusado por causa de seu software ou de sua versão; um arquivo de checkpoint de partida a quente, retomada ou somente simulação ausente ou que não pode ser decodificado; e uma falha na construção da FCF.

class CaseIoError(NovomodeloError, OSError): ...

Uma falha de leitura ou gravação no sistema de arquivos durante a carga ou a gravação de um caso. Levantada para os prefixos de mensagem output write error e policy checkpoint error. Também abrange uma leitura de checkpoint da política que o sistema operacional recusa.

class OutputError(NovomodeloError, OSError): ...

Uma falha de serialização ou de esquema de saída, levantada por novomodelo.write_policy_checkpoint, novomodelo.results.load_policy e por uma gravação de checkpoint periódico durante o treinamento. Um erro de E/S do tipo “não encontrado” levanta a exceção embutida FileNotFoundError, e os demais erros de E/S levantam CaseIoError. Uma falha de manifesto ou uma entrada estranha levanta ValidationError, e não OutputError.

class SolverError(NovomodeloError, RuntimeError):
stage: int | None
iteration: int | None
scenario: int | None

Uma falha de treinamento ou do solver. Um erro da classe do solver ou interna levanta SolverError, assim como uma mensagem cujo prefixo não é reivindicado por nenhuma outra classe; uma falha da simulação levanta SimulationError. Os três atributos estão sempre presentes. Em um subproblema inviável, eles contêm as coordenadas inteiras da inviabilidade; em qualquer outra falha, são None.

CampoTipoDescrição
stageint | NoneO estágio do subproblema inviável.
iterationint | NoneA iteração do treinamento do subproblema inviável.
scenarioint | NoneO cenário do subproblema inviável.
class SimulationError(NovomodeloError, RuntimeError): ...

Uma falha na fase de simulação. Levantada para o prefixo de mensagem simulation error.

class InternalError(NovomodeloError, RuntimeError): ...

Uma falha interna do software ou do ambiente, como o pânico (panic) de uma thread de trabalho. Levantada para o prefixo de mensagem internal error.

Algumas falhas levantam uma exceção embutida que não é uma NovomodeloError: diretório do caso ausente (OSError), threads=0 e mapeamento config_overrides malformado (ValueError), e a própria exceção de um callback.

import novomodelo
from novomodelo.errors import ValidationError
try:
novomodelo.Study("case", config_overrides={"trainning.enabled": False})
except ValidationError as err:
print(isinstance(err, ValueError))
print(err)
True
config override error: schema error in <config_overrides>, field trainning: unknown field `trainning`, expected one of `$schema`, `modeling`, `training`, `upper_bound_evaluation`, `policy`, `simulation`, `exports`, `estimation`
def export(output_dir: str | Path = ".") -> int: ...

Grava o arquivo JSON Schema de cada tipo de entrada do diretório do caso em output_dir, criando o diretório se necessário e sobrescrevendo arquivos existentes. Para os esquemas, veja Esquemas JSON.

Parâmetros

  • output_dir: o diretório que recebe os arquivos. Padrão: o diretório atual.

Retorna: o número de arquivos gravados, como int.

Levanta

  • ValueError (embutida) quando a geração ou a serialização do esquema falha.
  • OSError (embutida) quando o diretório não pode ser criado ou um arquivo não pode ser gravado.
import novomodelo.schema
print(novomodelo.schema.export("schemas"))
18

Os nomes em novomodelo._types são classes TypedDict usadas apenas para tipagem, correspondentes aos dicts que novomodelo.run.run e as propriedades de novomodelo.Study retornam; um verificador de tipos os lê a partir dos stubs do pacote. import novomodelo._types levanta ModuleNotFoundError em tempo de execução, e novomodelo.StochasticSummary, novomodelo.HydroModelsSummary, novomodelo.ProvenanceReport e novomodelo.System são, da mesma forma, reexportações existentes apenas nos stubs, ausentes em tempo de execução. Importe os nomes sob typing.TYPE_CHECKING e acesse a classe de sistema em tempo de execução como novomodelo.model.System.

from __future__ import annotations
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from novomodelo._types import RunResult
def final_lower_bound(result: RunResult) -> float:
return result["lower_bound"]

StochasticSummary, HydroModelsSummary e ProvenanceReport são declarados com total=False; os dicts que o pacote retorna contêm todas as chaves listadas.

O dict que novomodelo.run.run retorna.

ChaveTipoDescrição
convergedboolTrue quando os critérios de parada encerraram o treinamento e uma regra gap ou bound_stalling foi acionada nessa iteração. False para qualquer outro motivo de parada e para uma execução sem treinamento.
iterationsintO número de iterações de treinamento executadas. 0 quando o treinamento não foi executado.
lower_boundfloatO limite inferior final, em unidades monetárias.
upper_boundfloat | NoneO limite superior final, em unidades monetárias. None quando não está disponível.
gap_percentfloat | NoneO gap de otimalidade relativo vezes 100. None quando o treinamento não foi executado.
total_time_msintO tempo de treinamento em milissegundos. 0 quando o treinamento não foi executado.
output_dirstrO diretório de saída em que a execução gravou.
simulationSimulationSummary | NoneO resumo da simulação. None quando a simulação não foi executada.
stochasticStochasticSummary | NoneO mesmo resumo que novomodelo.Study.stochastic. novomodelo.run.run sempre o define.
hydro_modelsHydroModelsSummary | NoneO mesmo resumo que novomodelo.Study.hydro_models. novomodelo.run.run sempre o define.
provenanceProvenanceReport | NoneO mesmo resumo que novomodelo.Study.provenance. novomodelo.run.run sempre o define.

Todas as chaves estão presentes em todos os ramos. Após o treinamento, upper_bound e gap_percent estão definidos. Em uma execução somente de simulação (treinamento desabilitado, simulação habilitada), iterations é 0, gap_percent é None e upper_bound é o limite superior registrado no checkpoint carregado (o valor da última iteração do treinamento) quando é finito, ou None caso contrário. Com as duas fases desabilitadas, lower_bound é 0.0 e upper_bound, gap_percent e simulation são None.

As seis chaves principais do treinamento que RunResult contém em seu nível superior. Nenhuma função retorna um TrainingSummary; use-o para anotar essas chaves isoladamente.

ChaveTipoDescrição
convergedboolTrue quando os critérios de parada encerraram o treinamento e uma regra gap ou bound_stalling foi acionada nessa iteração. False para qualquer outro motivo de parada e para uma execução sem treinamento.
iterationsintO número de iterações de treinamento executadas. 0 quando o treinamento não foi executado.
lower_boundfloatO limite inferior final, em unidades monetárias.
upper_boundfloat | NoneO limite superior final, em unidades monetárias. None quando não está disponível.
gap_percentfloat | NoneO gap de otimalidade relativo vezes 100. None quando o treinamento não foi executado.
total_time_msintO tempo de treinamento em milissegundos. 0 quando o treinamento não foi executado.

O dict em RunResult["simulation"] e o valor de retorno de novomodelo.Study.simulate.

ChaveTipoDescrição
n_scenariosintO número de cenários da simulação.
completedintO número de cenários concluídos.

O dict que novomodelo.Study.stochastic retorna.

ChaveTipoDescrição
inflow_sourcestr | NoneA fonte das estatísticas sazonais de afluência: um de "estimated" (calculadas a partir do histórico de vazões), "loaded" (lidas dos arquivos do caso) ou None (o componente não é modelado).
n_hydrosintO número de usinas hidrelétricas.
n_seasonsintO número de períodos sazonais do modelo PAR(p).
ar_orderdict | NoneO resumo das ordens do modelo autorregressivo (AR); None quando o sistema não tem usinas hidrelétricas. O dict tem as chaves method (str, o método de seleção de ordem: "PACF" ou "PACF_ANNUAL" para o estimation.order_selection executado, ou "fixed" quando as ordens vêm dos arquivos do caso), min_order e max_order (int), n_hydros (int) e order_counts (list[int], o número de usinas em cada ordem, indexado pela ordem).
correlation_sourcestr | NoneA fonte dos dados de correlação: um de "estimated" (calculados a partir do histórico de vazões), "loaded" (lidos dos arquivos do caso) ou None (o componente não é modelado).
correlation_targetstr | NoneA série a partir da qual a correlação espacial foi estimada, o estimation.correlation_target da execução: "inflows" ou "residuals". None, a menos que correlation_source seja "estimated". O training/model_provenance.json a registra como inflow.correlation_target.
correlation_dimstr | NoneA dimensão da matriz de correlação como string, por exemplo "1x1". None quando não há matriz de correlação.
opening_tree_sourcestr | NoneA fonte da árvore de aberturas: um de "estimated" (calculada a partir do histórico de vazões), "loaded" (lida dos arquivos do caso) ou None (o componente não é modelado).
opening_tree_moment_matchingstr | NoneA correspondência de momentos (moment matching) da árvore de aberturas gerada, o training.scenario_source.openings.moment_matching da execução: "per_coordinate" (o padrão) ou "none", registrado quer algum estágio tenha passado pela correspondência de momentos, quer não. None, a menos que opening_tree_source seja "estimated". O training/model_provenance.json o registra como inflow.opening_tree_moment_matching.
openings_per_stagelist[int]O número de aberturas em cada estágio.
n_stagesintO número de estágios no contexto estocástico.
n_load_busesintO número de barramentos com ruído estocástico de carga.
seedintA semente aleatória usada na geração dos ruídos.

O dict que novomodelo.Study.hydro_models retorna.

ChaveTipoDescrição
n_constantintO número de usinas hidrelétricas que usam produtibilidade constante.
n_fphaintO número de usinas hidrelétricas que usam o modelo de produção FPHA.
total_planesintO número total de hiperplanos de todas as usinas com FPHA.
n_evaporationintO número de usinas hidrelétricas com evaporação linearizada.
n_no_evaporationintO número de usinas hidrelétricas sem modelo de evaporação.

O dict que novomodelo.Study.provenance retorna.

ChaveTipoDescrição
estimation_pathstrO caminho de estimação seguido, um de "deterministic", "user_stats_white_noise", "user_provided_no_history", "full_estimation", "user_ar_history_stats", "partial_estimation" ou "user_provided_all".
seasonal_stats_sourcestrA origem da média e do desvio-padrão sazonais: um de "estimated" (calculados a partir do histórico de vazões), "user_file" (lidos de um arquivo do caso) ou "n/a" (não se aplica).
ar_coefficients_sourcestrA origem dos coeficientes AR: um de "estimated" (calculados a partir do histórico de vazões), "user_file" (lidos de um arquivo do caso) ou "n/a" (não se aplica).
correlation_sourcestrA origem da correlação espacial: um de "estimated" (calculada a partir do histórico de vazões), "user_file" (lida de um arquivo do caso) ou "n/a" (não se aplica).
correlation_targetstr | NoneA série a partir da qual a correlação espacial foi estimada, o estimation.correlation_target da execução: "inflows" ou "residuals". None, a menos que correlation_source seja "estimated". O training/model_provenance.json a registra como inflow.correlation_target.
opening_tree_sourcestrA origem da árvore de aberturas de ruído: um de "estimated" (calculada a partir do histórico de vazões), "user_file" (lida de um arquivo do caso) ou "n/a" (não se aplica).
opening_tree_moment_matchingstr | NoneA correspondência de momentos (moment matching) da árvore de aberturas gerada, o training.scenario_source.openings.moment_matching da execução: "per_coordinate" (o padrão) ou "none", registrado quer algum estágio tenha passado pela correspondência de momentos, quer não. None, a menos que opening_tree_source seja "estimated". O training/model_provenance.json o registra como inflow.opening_tree_moment_matching.
n_hydrosintO número de usinas hidrelétricas.
ar_methodstr | NoneO método de seleção de ordem usado quando os coeficientes AR foram estimados: "PACF" ou "PACF_ANNUAL". None quando não foram estimados.
ar_max_orderint | NoneA ordem AR máxima entre todas as usinas hidrelétricas quando os coeficientes AR foram estimados. None caso contrário.
white_noise_fallbackslist[int]Os ids das usinas hidrelétricas que recorreram a ruído branco. Vazia, a menos que o caminho seja "partial_estimation".
hydro_productiondictAs contagens das fontes de produção hidrelétrica. O dict tem as chaves inteiras n_fpha_computed_from_geometry, n_fpha_precomputed_hyperplanes, n_evaporation_ref_user_supplied e n_evaporation_ref_default_midpoint.