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
stroupathlib.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_stderrnão os captura. - Cada cabeçalho é o nome qualificado de um símbolo e é a âncora dessa entrada (
#novomodelostudytrainparanovomodelo.Study.train).
novomodelo
Seção intitulada “novomodelo”novomodelo.__version__
Seção intitulada “novomodelo.__version__”__version__: strA string de versão do pacote, por exemplo 0.21.0.
novomodelo.version_info
Seção intitulada “novomodelo.version_info”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'}novomodelo.Study
Seção intitulada “novomodelo.Study”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.Noneexecuta em uma thread, e não em todos os núcleos. O valor é armazenado paratrainesimulatee não é usado durante a carga.config_overrides: um mapeamento plano de chaves com pontos, mesclado em profundidade emconfig.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 detraininge falha na validação. Uma chave desconhecida falha na validação. Para as chaves, veja Configuração.
Levanta
OSError(embutida) quandocase_dirnão existe, antes de qualquer processamento.ValueError(embutida) quandothreadsé0, ou quandoconfig_overridestem uma chave que não éstrou um tipo de valor não suportado.novomodelo.errors.ValidationErrorpara 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 umpolicy.pathrecusado; 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.CaseIoErrorquando a gravação de um desses arquivos falha, por exemplo em umoutput_dirsem permissão de escrita.novomodelo.errors.SolverErrorpara falha do solver ou falha interna durante o pré-processamento ou a construção.
novomodelo.Study.output_dir
Seção intitulada “novomodelo.Study.output_dir”@propertydef output_dir(self) -> str: ...O diretório de saída resolvido, como string.
novomodelo.Study.system
Seção intitulada “novomodelo.Study.system”@propertydef system(self) -> System: ...O novomodelo.model.System carregado. A propriedade compartilha o sistema do estudo; não o copia.
novomodelo.Study.stochastic
Seção intitulada “novomodelo.Study.stochastic”@propertydef stochastic(self) -> StochasticSummary: ...O resumo estrutural da parte estocástica, um dict fixado na construção. Seu formato é novomodelo._types.StochasticSummary.
novomodelo.Study.hydro_models
Seção intitulada “novomodelo.Study.hydro_models”@propertydef 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}.
novomodelo.Study.provenance
Seção intitulada “novomodelo.Study.provenance”@propertydef provenance(self) -> ProvenanceReport: ...O relatório de procedência do modelo, um dict fixado na construção. Seu formato é novomodelo._types.ProvenanceReport.
novomodelo.Study.validate
Seção intitulada “novomodelo.Study.validate”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.
novomodelo.Study.train
Seção intitulada “novomodelo.Study.train”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 contendokind,iteration,lower_bound,upper_bound,gapewall_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.SolverErrorpara falha de inicialização do solver ou falha de treinamento classificada pelo solver.novomodelo.errors.ValidationErrorpara 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.PolicyIncompatibleErrorquando o checkpoint de partida a quente ou de retomada empolicy.pathnão atende ao Contrato de carga da política, quando um checkpoint depolicy.boundaryfoi gravado por outro software ou outra versão, ou quando omanifest.binde um checkpoint está ausente ou não pode ser decodificado.novomodelo.errors.CaseIoErrorquando a gravação da política ou de um artefato do treinamento falha; uma falha na gravação de checkpoint periódico levantaFileNotFoundError,CaseIoError,novomodelo.errors.OutputErrorouValidationError, conforme a causa.novomodelo.errors.InternalErrorquando 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.
novomodelo.Study.load_policy
Seção intitulada “novomodelo.Study.load_policy”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: ooutput_dirdo estudo.
Retorna: o novomodelo.Policy carregado.
Levanta
novomodelo.errors.ValidationErrorquando o diretório da política está ausente (Policy directory not found: ...).novomodelo.errors.PolicyIncompatibleErrorquando o checkpoint não pode ser lido, decodificado ou reconstruído, ou quando a validação da política o rejeita.novomodelo.errors.CaseIoErrorquando um arquivo do checkpoint não pode ser aberto.
novomodelo.Study.simulate
Seção intitulada “novomodelo.Study.simulate”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: umnovomodelo.Policyobtido detrainouload_policy.output_dir: onde o diretóriosimulation/é gravado. Padrão: ooutput_dirdo estudo.
Retorna: {"n_scenarios": int, "completed": int}, por exemplo {'n_scenarios': 10, 'completed': 10}.
Levanta
novomodelo.errors.SolverErrorquando 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.SimulationErrorpara falha da simulação.novomodelo.errors.CaseIoErrorpara falha do gravador.novomodelo.errors.InternalErrorquando a thread de trabalho entra em pânico (panic).
novomodelo.Policy
Seção intitulada “novomodelo.Policy”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.
novomodelo.Policy.iterations
Seção intitulada “novomodelo.Policy.iterations”@propertydef 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.
novomodelo.Policy.final_lower_bound
Seção intitulada “novomodelo.Policy.final_lower_bound”@propertydef 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.
novomodelo.Policy.final_upper_bound
Seção intitulada “novomodelo.Policy.final_upper_bound”@propertydef 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.
novomodelo.Policy.evaluate
Seção intitulada “novomodelo.Policy.evaluate”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 (1para o caso 1dtoy).
Retorna: o valor do custo futuro como float.
Levanta
IndexError(embutida) quandostageé maior ou igual ao número de estágios (stage 4 out of range (policy has 4 stages)).ValueError(embutida) quandostatetem comprimento errado (state has length 2, expected 1 (policy state dimension)).OverflowError(embutida) quandostageé negativo.
novomodelo.Policy.cut_matrix
Seção intitulada “novomodelo.Policy.cut_matrix”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) quandostageé maior ou igual ao número de estágios.OverflowError(embutida) quandostageé negativo.ImportError(embutida) quando o NumPy não está instalado.
import novomodeloimport 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.29960260581718559.78879458073438 59.788794580734381000000.01O 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.
novomodelo.write_policy_checkpoint
Seção intitulada “novomodelo.write_policy_checkpoint”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_indicesem uma entrada destage_cuts,cut_idem um corte, ounum_cut_rows,num_columnsounum_rowsem uma entrada destage_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 destage_cutsestage_bases.ValueError(embutida) quando ocost_scale_factorde uma entrada destage_cutsestá 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), oumust be finite and positive, got {value}no lugar deis required).ValueError(embutida) quando o comprimento decoefficientsde um corte difere dostate_dimensionde seu estágio, quando um corte contéminflow_lag_coefficientssem uminflow_lag_depthpositivo ou, cominflow_lag_depthdefinido, 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) quandometadata["producer"]["basis_store_complete"]éTrueestage_basesnão contém nenhuma base, ou quando ostate_historydo produtor é diferente deNone,"whole"ou de um inteiro positivo (umboolé 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 decount * state_dimension), presença de contadores, datas, id repetido ou limite de tamanho (Validação da entrada).novomodelo.errors.ValidationError(umaValueError) quandopath(no caso de um link, seu destino) ou seu irmão.stagingou.previouscontém uma entrada que nenhum gravador de checkpoint deixaria ali (refusing to write a checkpoint: ...); nada é alterado no disco.- Uma classe de
novomodelo.errorsmapeada a partir da falha de gravação subjacente, para qualquer outro erro, comonovomodelo.errors.OutputError.
novomodelo.run
Seção intitulada “novomodelo.run”novomodelo.run.run
Seção intitulada “novomodelo.run.run”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
case_dir,output_dir,threads,config_overrides: como emnovomodelo.Study.on_iteration: como emnovomodelo.Study.train.
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.
| Ramo | converged | iterations | lower_bound | upper_bound | gap_percent | simulation |
|---|---|---|---|---|---|---|
| Treinamento habilitado | True 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 | iterações executadas | limite inferior final | limite superior final | gap vezes 100 | o dict de resumo, ou None se a simulação estiver desabilitada |
| Treinamento desabilitado, simulação habilitada (somente simulação) | False | 0 | o limite inferior do checkpoint | o limite superior registrado no checkpoint (o valor da última iteração do treinamento), None se não for finito | None | o dict de resumo |
| Ambos desabilitados | False | 0 | 0.0 | None | None | None |
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) quandocase_dirnão existe.ValueError(embutida) quandothreadsé0, ou quandoconfig_overridesestá malformado.- As classes listadas para
novomodelo.Study,novomodelo.Study.trainenovomodelo.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.
novomodelo.io
Seção intitulada “novomodelo.io”novomodelo.io.load_case
Seção intitulada “novomodelo.io.load_case”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.ValidationErrorpara 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.
novomodelo.io.validate
Seção intitulada “novomodelo.io.validate”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 tipoIoError.config_overrides: como emnovomodelo.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 quandoconfig_overridesestá malformado.
import novomodelo.io
report = novomodelo.io.validate("case")print(report){'valid': True, 'errors': [], 'warnings': []}novomodelo.results
Seção intitulada “novomodelo.results”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.
novomodelo.results.load_results
Seção intitulada “novomodelo.results.load_results”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", otraining/metadata.jsoninterpretado;"manifest", um alias de"metadata"com o mesmo conteúdo;"convergence_path"e"timing_path", os caminhos absolutos detraining/convergence.parquetetraining/timing/iterations.parquet; e"complete"."simulation":"manifest", osimulation/metadata.jsoninterpretado, ouNonequando 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) quandooutput_diroutraining/_SUCCESSestá ausente.ValueError(embutida) quando um arquivo de metadados não é um JSON válido.OSError(embutida) para outras falhas de leitura.
novomodelo.results.load_convergence
Seção intitulada “novomodelo.results.load_convergence”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) quandooutput_diroutraining/convergence.parquetestá ausente.OSError(embutida) para outras falhas de E/S e falhas de decodificação do Parquet.
import novomodelo.resultsimport 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']novomodelo.results.load_convergence_arrow
Seção intitulada “novomodelo.results.load_convergence_arrow”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) quandooutput_diroutraining/convergence.parquetestá 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.
novomodelo.results.load_simulation
Seção intitulada “novomodelo.results.load_simulation”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 desimulation/, como"costs","hydros"ou"thermals".Nonecarrega 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) quandooutput_dir,simulation/ou o diretório de entidade indicado está ausente.OSError(embutida) para arquivos Parquet corrompidos e outras falhas de E/S.
novomodelo.results.load_simulation_arrow
Seção intitulada “novomodelo.results.load_simulation_arrow”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 emload_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) quandooutput_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.
novomodelo.results.load_policy
Seção intitulada “novomodelo.results.load_policy”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 deoutput_dir. Informe opolicy.pathconfigurado quando ele não forpolicy.
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) quandooutput_direstá ausente, ou quando o diretório da política (no caso de um link, seu destino) está ausente e nem<policy>.stagingnem<policy>.previouscontém ummanifest.bin.novomodelo.errors.OutputError(umaOSError) quando um buffer do checkpoint não pode ser lido.
novomodelo.results.load_stochastic
Seção intitulada “novomodelo.results.load_stochastic”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) quandooutput_dirou 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.
novomodelo.results.Stochastic
Seção intitulada “novomodelo.results.Stochastic”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.
novomodelo.results.Stochastic.par_coefficients
Seção intitulada “novomodelo.results.Stochastic.par_coefficients”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.
novomodelo.results.Stochastic.opening_tree
Seção intitulada “novomodelo.results.Stochastic.opening_tree”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) quandostageé negativo.ImportError(embutida) quando o NumPy não está instalado.
novomodelo.model
Seção intitulada “novomodelo.model”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).
novomodelo.model.System
Seção intitulada “novomodelo.model.System”O sistema carregado: contagens de entidades e uma lista por classe de entidade.
| Campo | Tipo | Descrição |
|---|---|---|
n_buses | int | O número de barramentos. |
n_hydros | int | O número de usinas hidrelétricas. |
n_lines | int | O número de linhas de transmissão. |
n_stages | int | O número de estágios, do estudo e anteriores ao estudo. |
n_thermals | int | O número de usinas termelétricas. |
buses | list[Bus] | Os barramentos, na ordem canônica. |
hydros | list[Hydro] | As usinas hidrelétricas, na ordem canônica. |
lines | list[Line] | As linhas de transmissão, na ordem canônica. Vazia quando o caso não tem nenhuma. |
thermals | list[Thermal] | As usinas termelétricas, na ordem canônica. |
contracts | list[EnergyContract] | Os contratos de energia, na ordem canônica. Vazia quando o caso não tem nenhum. |
pumping_stations | list[PumpingStation] | As usinas elevatórias, na ordem canônica. Vazia quando o caso não tem nenhuma. |
non_controllable_sources | list[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.0novomodelo.model.Bus
Seção intitulada “novomodelo.model.Bus”Um nó da rede elétrica no qual se mantém o balanço de energia.
| Campo | Tipo | Descrição |
|---|---|---|
id | int | O id da entidade no arquivo do caso. |
name | str | O nome da entidade no arquivo do caso. |
deficit_segments | list[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_cost | float | O custo de absorver o excedente de geração, em R$/MWh. |
novomodelo.model.Line
Seção intitulada “novomodelo.model.Line”Uma interligação de transmissão que transporta potência nos dois sentidos entre dois barramentos.
| Campo | Tipo | Descrição |
|---|---|---|
id | int | O id da entidade no arquivo do caso. |
name | str | O nome da entidade no arquivo do caso. |
source_bus_id | int | O id do barramento na extremidade de origem. |
target_bus_id | int | O id do barramento na extremidade de destino. |
direct_capacity_mw | float | O fluxo máximo da origem para o destino, em MW. |
reverse_capacity_mw | float | O fluxo máximo do destino para a origem, em MW. |
losses_percent | float | As perdas de transmissão em percentual; 2.5 significa 2,5%. |
exchange_cost | float | O custo de regularização por MWh de intercâmbio, em R$/MWh. |
novomodelo.model.Thermal
Seção intitulada “novomodelo.model.Thermal”Uma usina termelétrica com custo marginal escalar.
| Campo | Tipo | Descrição |
|---|---|---|
id | int | O id da entidade no arquivo do caso. |
name | str | O nome da entidade no arquivo do caso. |
bus_id | int | O id do barramento que a usina alimenta. |
min_generation_mw | float | A geração elétrica mínima (inflexibilidade), em MW. |
max_generation_mw | float | A geração elétrica máxima (potência instalada), em MW. |
cost_per_mwh | float | O custo marginal de geração (CVU), em R$/MWh. |
novomodelo.model.Hydro
Seção intitulada “novomodelo.model.Hydro”Uma usina hidrelétrica com reservatório. As usinas formam uma cascata por meio de downstream_id.
| Campo | Tipo | Descrição |
|---|---|---|
id | int | O id da entidade no arquivo do caso. |
name | str | O nome da entidade no arquivo do caso. |
downstream_id | int | None | O id da próxima usina da cascata. None para uma usina sem usina a jusante. |
min_storage_hm3 | float | O armazenamento operativo mínimo (volume morto), em hm³. |
max_storage_hm3 | float | O armazenamento operativo máximo (nível de controle de cheias), em hm³. |
min_turbined_m3s | float | A vazão turbinada mínima, em m³/s. |
max_turbined_m3s | float | A vazão turbinada máxima declarada, em m³/s; com max_generation_mw, decide se a usina tem capacidade de turbinamento. |
productivity_mw_per_m3s | float | None | Sempre None. A produtibilidade é resolvida por estágio a partir dos arquivos de modelos de produção. |
novomodelo.model.EnergyContract
Seção intitulada “novomodelo.model.EnergyContract”Um contrato bilateral de energia com um sistema externo.
| Campo | Tipo | Descrição |
|---|---|---|
id | int | O id da entidade no arquivo do caso. |
name | str | O nome da entidade no arquivo do caso. |
operational_start_date | str | A data em que a entidade entra em operação, como string ISO 8601 YYYY-MM-DD. |
bus_id | int | O id do barramento ao qual o contrato se conecta. |
contract_type | str | O sentido do fluxo de energia: "import" ou "export". |
entry_stage_id | int | None | O índice do estágio em que o contrato entra em vigor. None quando está ativo desde o primeiro estágio. |
exit_stage_id | int | None | O índice do estágio em que o contrato expira. None quando nunca expira. |
price_per_mwh | float | O preço do contrato, em R$/MWh. Um valor negativo representa receita de exportação. |
min_mw | float | A potência contratada mínima, em MW. |
max_mw | float | A potência contratada máxima, em MW. |
novomodelo.model.PumpingStation
Seção intitulada “novomodelo.model.PumpingStation”Uma usina elevatória (estação de bombeamento) que transfere água entre reservatórios de usinas hidrelétricas.
| Campo | Tipo | Descrição |
|---|---|---|
id | int | O id da entidade no arquivo do caso. |
name | str | O nome da entidade no arquivo do caso. |
operational_start_date | str | A data em que a entidade entra em operação, como string ISO 8601 YYYY-MM-DD. |
bus_id | int | O id do barramento do qual a estação consome energia. |
source_hydro_id | int | O id da usina hidrelétrica de onde a água bombeada é retirada. |
destination_hydro_id | int | O id da usina hidrelétrica que recebe a água bombeada. |
entry_stage_id | int | None | O índice do estágio em que a estação entra em operação. None quando está ativa desde o primeiro estágio. |
exit_stage_id | int | None | O índice do estágio em que a estação é desativada. None quando nunca é desativada. |
consumption_mw_per_m3s | float | O consumo de potência por unidade de vazão bombeada, em MW/(m³/s). |
min_flow_m3s | float | A vazão bombeada mínima, em m³/s. |
max_flow_m3s | float | A vazão bombeada máxima (capacidade instalada de bombeamento), em m³/s. |
novomodelo.model.NonControllableSource
Seção intitulada “novomodelo.model.NonControllableSource”Uma fonte de geração intermitente que não é despachada.
| Campo | Tipo | Descrição |
|---|---|---|
id | int | O id da entidade no arquivo do caso. |
name | str | O nome da entidade no arquivo do caso. |
operational_start_date | str | A data em que a entidade entra em operação, como string ISO 8601 YYYY-MM-DD. |
bus_id | int | O id do barramento que a fonte alimenta. |
entry_stage_id | int | None | O índice do estágio em que a fonte entra em operação. None quando está ativa desde o primeiro estágio. |
exit_stage_id | int | None | O índice do estágio em que a fonte é desativada. None quando nunca é desativada. |
max_generation_mw | float | A geração máxima (potência instalada), em MW. |
allow_curtailment | bool | Se o PL pode aplicar corte de geração (curtailment) à fonte. False corresponde ao regime de geração compulsória (must-run). |
curtailment_cost | float | O custo resolvido da geração cortada, em R$/MWh. Não é usado quando allow_curtailment é False. |
novomodelo.errors
Seção intitulada “novomodelo.errors”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.
novomodelo.errors.NovomodeloError
Seção intitulada “novomodelo.errors.NovomodeloError”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.
novomodelo.errors.ValidationError
Seção intitulada “novomodelo.errors.ValidationError”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.
novomodelo.errors.PolicyIncompatibleError
Seção intitulada “novomodelo.errors.PolicyIncompatibleError”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.
novomodelo.errors.CaseIoError
Seção intitulada “novomodelo.errors.CaseIoError”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.
novomodelo.errors.OutputError
Seção intitulada “novomodelo.errors.OutputError”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.
novomodelo.errors.SolverError
Seção intitulada “novomodelo.errors.SolverError”class SolverError(NovomodeloError, RuntimeError): stage: int | None iteration: int | None scenario: int | NoneUma 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.
| Campo | Tipo | Descrição |
|---|---|---|
stage | int | None | O estágio do subproblema inviável. |
iteration | int | None | A iteração do treinamento do subproblema inviável. |
scenario | int | None | O cenário do subproblema inviável. |
novomodelo.errors.SimulationError
Seção intitulada “novomodelo.errors.SimulationError”class SimulationError(NovomodeloError, RuntimeError): ...Uma falha na fase de simulação. Levantada para o prefixo de mensagem simulation error.
novomodelo.errors.InternalError
Seção intitulada “novomodelo.errors.InternalError”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 novomodelofrom novomodelo.errors import ValidationError
try: novomodelo.Study("case", config_overrides={"trainning.enabled": False})except ValidationError as err: print(isinstance(err, ValueError)) print(err)Trueconfig 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`novomodelo.schema
Seção intitulada “novomodelo.schema”novomodelo.schema.export
Seção intitulada “novomodelo.schema.export”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"))18novomodelo._types
Seção intitulada “novomodelo._types”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.
novomodelo._types.RunResult
Seção intitulada “novomodelo._types.RunResult”O dict que novomodelo.run.run retorna.
| Chave | Tipo | Descrição |
|---|---|---|
converged | bool | True 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. |
iterations | int | O número de iterações de treinamento executadas. 0 quando o treinamento não foi executado. |
lower_bound | float | O limite inferior final, em unidades monetárias. |
upper_bound | float | None | O limite superior final, em unidades monetárias. None quando não está disponível. |
gap_percent | float | None | O gap de otimalidade relativo vezes 100. None quando o treinamento não foi executado. |
total_time_ms | int | O tempo de treinamento em milissegundos. 0 quando o treinamento não foi executado. |
output_dir | str | O diretório de saída em que a execução gravou. |
simulation | SimulationSummary | None | O resumo da simulação. None quando a simulação não foi executada. |
stochastic | StochasticSummary | None | O mesmo resumo que novomodelo.Study.stochastic. novomodelo.run.run sempre o define. |
hydro_models | HydroModelsSummary | None | O mesmo resumo que novomodelo.Study.hydro_models. novomodelo.run.run sempre o define. |
provenance | ProvenanceReport | None | O 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.
novomodelo._types.TrainingSummary
Seção intitulada “novomodelo._types.TrainingSummary”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.
| Chave | Tipo | Descrição |
|---|---|---|
converged | bool | True 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. |
iterations | int | O número de iterações de treinamento executadas. 0 quando o treinamento não foi executado. |
lower_bound | float | O limite inferior final, em unidades monetárias. |
upper_bound | float | None | O limite superior final, em unidades monetárias. None quando não está disponível. |
gap_percent | float | None | O gap de otimalidade relativo vezes 100. None quando o treinamento não foi executado. |
total_time_ms | int | O tempo de treinamento em milissegundos. 0 quando o treinamento não foi executado. |
novomodelo._types.SimulationSummary
Seção intitulada “novomodelo._types.SimulationSummary”O dict em RunResult["simulation"] e o valor de retorno de novomodelo.Study.simulate.
| Chave | Tipo | Descrição |
|---|---|---|
n_scenarios | int | O número de cenários da simulação. |
completed | int | O número de cenários concluídos. |
novomodelo._types.StochasticSummary
Seção intitulada “novomodelo._types.StochasticSummary”O dict que novomodelo.Study.stochastic retorna.
| Chave | Tipo | Descrição |
|---|---|---|
inflow_source | str | None | A 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_hydros | int | O número de usinas hidrelétricas. |
n_seasons | int | O número de períodos sazonais do modelo PAR(p). |
ar_order | dict | None | O 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_source | str | None | A 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_target | str | None | A 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_dim | str | None | A dimensão da matriz de correlação como string, por exemplo "1x1". None quando não há matriz de correlação. |
opening_tree_source | str | None | A 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_matching | str | None | A 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_stage | list[int] | O número de aberturas em cada estágio. |
n_stages | int | O número de estágios no contexto estocástico. |
n_load_buses | int | O número de barramentos com ruído estocástico de carga. |
seed | int | A semente aleatória usada na geração dos ruídos. |
novomodelo._types.HydroModelsSummary
Seção intitulada “novomodelo._types.HydroModelsSummary”O dict que novomodelo.Study.hydro_models retorna.
| Chave | Tipo | Descrição |
|---|---|---|
n_constant | int | O número de usinas hidrelétricas que usam produtibilidade constante. |
n_fpha | int | O número de usinas hidrelétricas que usam o modelo de produção FPHA. |
total_planes | int | O número total de hiperplanos de todas as usinas com FPHA. |
n_evaporation | int | O número de usinas hidrelétricas com evaporação linearizada. |
n_no_evaporation | int | O número de usinas hidrelétricas sem modelo de evaporação. |
novomodelo._types.ProvenanceReport
Seção intitulada “novomodelo._types.ProvenanceReport”O dict que novomodelo.Study.provenance retorna.
| Chave | Tipo | Descrição |
|---|---|---|
estimation_path | str | O 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_source | str | A 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_source | str | A 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_source | str | A 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_target | str | None | A 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_source | str | A 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_matching | str | None | A 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_hydros | int | O número de usinas hidrelétricas. |
ar_method | str | None | O 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_order | int | None | A ordem AR máxima entre todas as usinas hidrelétricas quando os coeficientes AR foram estimados. None caso contrário. |
white_noise_fallbacks | list[int] | Os ids das usinas hidrelétricas que recorreram a ruído branco. Vazia, a menos que o caminho seja "partial_estimation". |
hydro_production | dict | As 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. |