Pynatem

v2.0.0 — Primeiro Lançamento Público (PyPI) 🚀 | pip install pynatem

Biblioteca Python para geração, manipulação, parsing e execução automatizada de arquivos de caso do simulador de estabilidade eletromecânica transitória ANATEM (CEPEL).

O pynatem representa um arquivo .stb como um grafo de blocos serializáveis (padrão AST + Serializer): cada bloco é um objeto Python que sabe se serializar no texto posicional exato esperado pelo ANATEM, e o parser reconstrói a mesma árvore a partir de um .stb existente, garantindo roundtrip.

Versão: 2.0.0 — Primeiro Lançamento Público no PyPI Status: 280 testes (17 de conformidade externa); etapas v1.1–v1.10 concluídas ✅ Referência técnica: Manual ANATEM 12.10 (CEPEL) — validado contra o manual online oficial (https://see.cepel.br/manual/anatem/)

Estado Atual (v2.0.0)

✅ Estável: API testada e documentada; endurecendo a confiabilidade (etapa v1.1)

Marcos Concluídos

Destaques v2.0.0

• ✅ 280 testes — incluindo 17 testes de conformidade externa que comparam a saída char-a-char com os exemplos oficiais do manual do Cepel
• ✅ 16 serializadores auditados e corrigidos contra o manual online oficial: DEVT, DSIM, DMAQ, DCAR, DLTC, DFLA, DCST, DCAG/DCCT, DCLI, DMEL, DELO, DGER, DOPC, EXSI, DSTO, TIME
• ✅ Mnemônicos de evento 100% oficiais — ABCI/FECI, APCL/RMCL, TRGT/TRGV, MDSH (removidos os inexistentes ABLN/FCLN/ABSH/FCSH/RMCC/ALTG)
• ✅ Serialização posicional pelas réguas oficiais (campos opcionais em branco onde o manual omite)
• ✅ Referências corrigidas — 421 listagens de código dos markdowns reconstruídas a partir dos fontes oficiais
• ✅ CI/CD automático — GitHub Actions (Python 3.9–3.12), Codecov, black, mypy
• ✅ 32 blocos + módulos v1.7–v1.10 com type hints, API estável

Próximo: v2.0.1 — Réguas por variante MDxx (backlog de conformidade rumo à cobertura total, marco v3.0.0). Veja ROADMAP.md.

Sumário

• O que é o ANATEM
• Instalação
• Uso rápido
• Arquitetura
• Confiabilidade dos códigos
• 📖 Documentação Teórica

📖 Documentação Teórica

Para entender os conceitos fundamentais, consulte:

• TEORIA.md — Guia teórico completo:
  • Simulação de estabilidade transitória
  • Estrutura de arquivo .stb
  • Eventos e perturbações
  • Modelos dinâmicos de máquinas (MD01, MD02, MD03)
  • Controladores Definidos pelo Usuário (CDU)
  • FACTS e HVDC
  • Pipeline de simulação
  • Validação e pós-processamento
  • Exemplo prático completo

Para aprender na prática, veja:

• examples/ — 7 scripts runnable de básico a avançado
• docs/tutorial.md — Tutorial estruturado em 6 partes

O que é o ANATEM

O ANATEM é o programa do CEPEL para simulação de estabilidade eletromecânica transitória de sistemas de potência. Ele recebe arquivos de texto estruturado (.stb, .dat, .cdu, .blt) e produz arquivos de saída (.plt, .rela, .log).

Este projeto oferece uma biblioteca Python para:

• ✅ Criar casos de simulação do zero
• ✅ Editar casos existentes programaticamente
• ✅ Parsear arquivos .stb com garantia de roundtrip (ler → modificar → escrever sem perda)
• ✅ Executar lotes de simulações (sequencial ou paralelo)
• ✅ Validar consistência de casos
• ✅ Ler resultados (.plt texto, .rela)

Dependências: Python ≥ 3.9 (sem obrigatórias além da stdlib; pandas é opcional)

Instalação

# Instalação em modo editável (recomendado durante desenvolvimento)
pip install -e .

# Opcional: suporte a pandas para pós-processamento
pip install -e ".[plt]"

Uso rápido

Criar um novo caso

from pynatem import CasoAnatem

caso = CasoAnatem()
caso.titulo = "Curto em barra - exemplo"

# Arquivos associados
caso.darq.sav = "rede.sav"          # Caso de rede ANAREDE
caso.darq.plt = "resultado.plt"     # Saída de plotagem
caso.darq.rela = "resultado.rela"   # Relatório de execução

# Parâmetros de simulação
caso.dsim.tini = 0.0
caso.dsim.tfim = 10.0
caso.dsim.delt = 0.01

# Eventos
caso.curto_barra(barra=5, t_apl=1.0, t_rem=1.1)
caso.curto_circuito(de=10, para=20, circ=1, t_apl=2.0, t_rem=2.1)

# Múltiplos CDU (Controladores Definidos pelo Usuário)
caso.darq.adicionar_cdu("avr.cdu")
caso.darq.adicionar_cdu("pss.cdu")

# Variáveis de plotagem
caso.dplt.tensao_barra(5)
caso.dplt.angulo_maquina(5, unidade=1)
caso.dplt.velocidade_maquina(5, unidade=1)

# Validar e exportar
erros = caso.validar()
if erros:
    for e in erros:
        print("AVISO:", e)

caso.exportar("meu_caso.stb")

Editar um caso existente

from pynatem import CasoAnatem

caso = CasoAnatem.ler("REGER_3Q25.stb")
caso.dsim.tfim = 15.0  # Estender tempo de simulação
caso.dplt.tensao_barra(101)  # Adicionar variável
caso.exportar("REGER_3Q25_15s.stb")

Executar um lote de casos

from pynatem import EnsaioAnatem

ensaio = EnsaioAnatem.de_template("base.stb", anatem_exe="anatem.exe")

def variar(caso, i):
    """Modificar caso para cada iteração"""
    t = 0.5 + i * 0.1
    caso.devt._eventos.clear()
    caso.curto_barra(barra=10, t_apl=t, t_rem=t + 0.08)

# Gerar 20 casos com variações
paths = ensaio.gerar_variacoes(variar, n=20, diretorio="batch")

# Executar (sequencial)
resultados = ensaio.executar_lote(paths)

# Ou em paralelo (4 processos)
resultados = ensaio.executar_paralelo(paths, max_workers=4)

Ler resultados

from pynatem import LeitorPLT, LeitorRelatorio

# Leitura de arquivo de plotagem (formato texto)
plt = LeitorPLT.ler("batch/caso_0000/resultado.plt")
tensao = plt.valores("VBAR5")
df = plt.para_dataframe()  # requer pandas

# Leitura de relatório de execução
rel = LeitorRelatorio.ler("batch/caso_0000/resultado.rela")
print("Convergiu:", rel.convergiu)
print("Erros:", rel.erros)
print("Avisos:", rel.avisos)

Arquitetura

pynatem/
├── __init__.py           ← Exports públicos
├── caso.py               ← CasoAnatem (API fluente + validação)
├── blocos.py             ← Um dataclass por bloco STB, com serializar()
├── ensaio.py             ← EnsaioAnatem (lotes sequenciais e paralelos)
├── posprocessamento.py   ← LeitorPLT, LeitorRelatorio (leitura de saídas)
└── parser/
    └── stb.py            ← ParserSTB (leitura estruturada de .stb)

Padrão de Design

A biblioteca segue o padrão AST + Serializer:

1. Cada bloco é um dataclass Python independente que sabe se serializar (método serializar())
2. CasoAnatem é o nó raiz (contém DARQ, DSIM, DEVT, DPLT, etc.)
3. ParserSTB reconstrói a mesma árvore AST a partir de texto
4. Roundtrip garantido: ler → modificar → escrever produz o mesmo formato

Confiabilidade dos Códigos

Para transparência sobre validação (v1.0.0):

¹ DVSI e DCNV: conjunto e ordem dos campos validados contra o manual (§46.64 / §46.21); a serialização usa colunas fixas (necessário porque há campos opcionais — Pa/Rv/Vpt no DVSI, Gkb/Amn/Amx/Gmn/S1–S4 no DCNV) cujas larguras seguem a régua-guia do manual. O roundtrip é garantido pelo par serializar↔parser; a validação byte-a-byte contra um .stb real do CEPEL fica pendente de amostra.

² LeitorSAV: o formato .sav é do ANAREDE (externo ao manual ANATEM). O parser segue o layout de colunas fixas padrão do ANAREDE para os identificadores usados na validação cruzada (barra, nome, De/Para/circuito) e resolve a tensão-base via DGBT, com fallback por espaços. Validação byte-a-byte contra uma versão específica do ANAREDE fica pendente de amostra.

³ DCAR: os parâmetros do modelo de carga (A/B/C/D/Vmn) são estruturados e validados contra §46.14, mas a linguagem de seleção (Cap. 42) que escolhe as barras/cargas alvo é tratada como string opaca e preservada bruta no roundtrip. O parsing estruturado da seleção é um item próprio do roadmap (A43, v1.9.2).

Safeguards em v1.0.0:

• ✅ Encoding latin-1 garantido — sem corrupção silenciosa, ValueError descritivo se fora do intervalo
• ✅ Desambiguação CDU por tipo — IMPORT/EXPORT/INPUT/OUTPUT/SERIET/LOGIC/COMPAR reconhecidos corretamente (Cap. 29)
• ✅ Validação cruzada automática — DMAQ ↔ DMDG, caminhos de arquivo, campos vazios em IMPORT/EXPORT
• ✅ Parser CDU robusto — Roundtrip garantido para IMPORT/EXPORT com stip, LOGIC/COMPAR, blocos com <4 parâmetros
• ✅ 206 testes cobrindo roundtrip, encoding, blocos, parser, CDU, pós-processamento, validação
• ✅ Documentação consolidada — README.md, TEORIA.md, ROADMAP, CHANGELOG, docs/ e exemplos

Recomendação: Para famílias ainda marcadas como Média (ex.: DPLT 4-letra, OLTC), valide contra um .stb/.plt real ou o manual. O método linha_bruta() (em BlocoDEVT e BlocoDPLT) é a alternativa segura para confirmação verbatim.

Componentes Principais (v1.0.0)

Total: 20+ classes públicas | 206 testes | 87%+ cobertura | Encoding garantido | Type hints completos

Testes

# Rodar suite de testes (206 testes)
pytest tests/ -v

# Com cobertura de código
pytest tests/ --cov=pynatem --cov-report=html

# Verificação de qualidade completa
pip install -e ".[dev]"
black --check --target-version py311 pynatem/ tests/
mypy pynatem/ --ignore-missing-imports
pytest tests/ -v

Cobertura: 206 testes cobrindo roundtrip, encoding latin-1, blocos, parser, CDU, validação e pós-processamento.

Histórico de Versões

Recomendação: Use v1.3.4 para novos projetos. Todas as versões estão disponíveis no repositório como referência histórica.

Contribuir

Contribuições são bem-vindas! Leia CONTRIBUTING.md para começar.

Checklist rápido:

• Código segue o style guide (black, isort, flake8)
• Type hints completos (mypy compatible)
• Testes passam: pytest tests/
• Documentação atualizada
• Commit messages descritivas

Veja também o Código de Conduta.

Suporte & Comunidade

• 📚 Documentação: docs/ — guias, tutorial e referência de API
• 📖 Teoria: TEORIA.md — conceitos de estabilidade transitória
• 💡 Exemplos: examples/ — 7 scripts executáveis
• 🐛 Reportar bug: GitHub Issues
• 📧 Email: vivas.matheus@usp.br

Licença

MIT — veja LICENSE para detalhes.

Créditos

Autor: Matheus Antonio Vivas Rocha (@matheusvivasr) Email: vivas.matheus@usp.br Instituição: Universidade de São Paulo (USP)

Referências

• Manual ANATEM v12.10 (CEPEL)
• Simulador: https://www.cepel.br