Arquitetura do idessem¶
Esta página descreve a estrutura interna do idessem, explicando como o módulo é organizado, como os arquivos do modelo DESSEM são mapeados para classes Python e qual é o fluxo típico de leitura e escrita de dados.
Visão Geral da Arquitetura¶
O idessem é uma biblioteca Python que fornece uma interface de alto nível para leitura e escrita dos arquivos do modelo DESSEM, utilizado pelo Operador Nacional do Sistema Elétrico (ONS) para o planejamento da operação de curtíssimo prazo do Sistema Interligado Nacional (SIN). O modelo DESSEM processa dezenas de arquivos de entrada e produz dezenas de arquivos de saída, todos com formatos textuais proprietários e bem definidos.
A responsabilidade central do idessem é abstrair o formato textual de cada
arquivo em uma classe Python, expondo os dados como propriedades tipadas —
principalmente como DataFrame para dados tabulares — e permitindo
que o usuário leia, inspecione, modifique e reescreva esses arquivos sem precisar
conhecer a sintaxe interna de cada formato.
O idessem é construído sobre o framework cfinterface, que
fornece as abstrações de nível mais baixo para leitura e escrita de arquivos
estruturados. A relação entre os dois módulos está descrita em detalhes na seção
Como contribuir?.
Framework cfinterface¶
O framework cfinterface classifica os arquivos processados em três categorias, de acordo com a sua estrutura interna:
BlockFile: arquivos compostos por blocos com padrão de início bem definido, que podem aparecer múltiplas vezes e em qualquer ordem.SectionFile: arquivos compostos por seções fixas que aparecem sempre na mesma ordem.RegisterFile: arquivos compostos por registros de linha única e formato constante.
Nota
No idessem, não são utilizados arquivos do tipo
SectionFile. Todos os arquivos do modelo
DESSEM suportados são implementados como
BlockFile ou
RegisterFile.
Ver também
A seção Como contribuir? contém uma explicação detalhada das três classes de arquivos do cfinterface, com exemplos concretos de arquivos do idessem que seguem cada abordagem.
Estrutura de Módulos¶
O idessem expõe duas subpacotes públicas:
idessem.dessem
Contém as classes que modelam os arquivos de entrada e de saída do modelo DESSEM. É o módulo principal da biblioteca, com 46 classes no total.
Arquivos de entrada (suportam leitura e escrita):
Arquivos de saída — avaliação de FPHA (somente leitura):
Arquivos de saída — pdo_ (somente leitura):
Arquivos de log — saída de diagnóstico (somente leitura):
idessem.libs
Contém entidades compartilhadas que podem ser referenciadas por múltiplos arquivos do modelo. Atualmente possui uma única classe:
UsinasHidreletricas: representação consolidada dos dados de usinas hidrelétricas do SIN.
Convenções de Nomeação¶
Cada arquivo do modelo DESSEM é mapeado para uma classe Python com nome em
PascalCase, derivado do nome de arquivo mais comum encontrado nos decks de
PMO publicados pelo ONS ou nos casos de exemplo distribuídos pelo desenvolvedor
do modelo. A regra geral é:
Remover a extensão do arquivo (
*.dat,*.DAT).Separar as partes do nome pelo delimitador
_(sublinhado).Converter cada parte para
PascalCase, ignorando a capitalização original.
Nota
Abreviações presentes nos nomes dos arquivos são ignoradas na mudança de
capitalização. Por exemplo, PDO se torna Pdo e não PDO.
Exemplos de mapeamento:
Nome do arquivo |
Classe Python |
|---|---|
|
|
|
|
|
|
|
Fluxo de Dados¶
O idessem fornece uma interface uniforme para todos os arquivos. O padrão
de uso é sempre o mesmo: o método de classe read() recebe o caminho do
arquivo e retorna uma instância da classe correspondente, com os dados
já parseados e disponíveis como propriedades.
Arquivos de entrada — leitura, modificação e escrita
Os arquivos de entrada do modelo DESSEM (como entdados.dat) suportam tanto
leitura quanto escrita. O fluxo típico é: ler o arquivo original, modificar os
dados desejados através das propriedades da instância e gravar o resultado de
volta com o método write().
from idessem.dessem.entdados import Entdados
# Leitura do arquivo de entrada
arq = Entdados.read("./entdados.dat")
# Acesso e modificação de uma propriedade
arq.uh(codigo_usina=6).volume_inicial
# 69.51
arq.uh(codigo_usina=6).volume_inicial *= 1.1
arq.uh(codigo_usina=6).volume_inicial
# 76.461
# Escrita do arquivo modificado
arq.write("./entdados.dat")
Ver também
O Tutorial contém exemplos adicionais do ciclo de leitura e escrita,
incluindo o tratamento de versões de arquivo com set_version().
Arquivos de saída — somente leitura
Os arquivos de saída do modelo DESSEM (com prefixo pdo_, avl_, log_
ou des_log_) não implementam o método write(). O fluxo de uso é apenas
de leitura e análise dos resultados:
from idessem.dessem.pdo_sist import PdoSist
# Leitura do arquivo de saída
arq = PdoSist.read("./PDO_SIST.DAT")
# Acesso à tabela de resultados como DataFrame
arq.tabela
# estagio patamar submercado cmo demanda ...
# 0 1 LEVE SE 71.48 36935.91 ...
# ...
Importante
Tentar chamar write() em um arquivo de saída levanta NotImplementedError.
Arquivos de saída são identificados pelo prefixo do nome da classe:
Pdo*, Avl*, DesLogRelato, LogInviab e LogMatriz.
Importações Diretas¶
O submódulo idessem.dessem utiliza importações diretas (não lazy) em seu
__init__.py. Isso significa que ao executar import idessem.dessem,
todas as 46 classes são carregadas imediatamente na memória, incluindo suas
dependências.
Aviso
Evite importar o submódulo inteiro em código de produção ou em scripts que exigem tempo de inicialização reduzido. Prefira importar diretamente a classe que será utilizada:
# Recomendado: importa apenas a classe necessária
from idessem.dessem.entdados import Entdados
# Evitar em contextos sensíveis a desempenho: carrega todas as 46 classes
import idessem.dessem
O carregamento completo do módulo pode ser aceitável em sessões interativas (Jupyter, IPython) ou em aplicações de longa duração onde o custo de inicialização é pago uma única vez.