pynatem 2.0.0

Biblioteca Python para geração e manipulação de arquivos ANATEM (.stb)

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

Etapa	Foco	Status
0.4	MVP: blocos, parser, ensaios	✅ v0.4.7
0.5	DMAQ posicional	✅ v0.5.3
0.6	Integração FACTS/HVDC/CDU	✅ v0.6.4
0.7	Validações cruzadas	✅ v0.7.3
0.8	Cobertura CDU (46+ testes)	✅ v0.8.4
0.11	Polimento (type hints)	✅ v0.11.3
0.14	Robustez I/O (latin-1, reconciliação)	✅ v0.14.2
0.15	CI/CD, docs, exemplos, comunidade	✅ v0.15.0
1.0	API estável, +200 testes, docs teóricas	✅ v1.0.0 ⭐
1.1	Confiabilidade Máxima (Inventário B zerado)	✅ v1.1.5 (FACTS + HVDC + SAV + CURVA + DPLT)
1.2	Máquina Síncrona Completa (reguladores/PSS/modelos/CAG/CCT)	✅ v1.2.6 (DRGT+DRGV+DEST+DCST+CAG+CCT)
1.3	Cargas, Shunt, OLTC e Circuitos	✅ v1.3.4 (DCAR + shunt + OLTC + DFLA)
1.5	Geração Renovável (DMOT/DGSE/DDFM/DFNT)	✅ v1.5.5 (DMOT + DGSE + DDFM parser fix + DFNT)
1.6	HVDC & FACTS Completos (DMEL/DMCV/DCLI/CER/CSC/VSI/LCC)	✅ v1.6.4 (DMEL + DMCV + DCLI + SVC/TCSC + STATCOM/HVDC)
1.4	Pós-processamento (.plt binário, .out, .rel, .snap)	✅ (parser PLT binário por engenharia reversa)
1.7	CDU Avançado (inicialização, topologia, relés/SEP, mensagens)	✅ (cdu_v17: DEFVAL/DEFVDF/DEFPLT, DTDU/ACDU, DMSG, OTMx)
1.8	Modos de Análise (contingência N-1, multi-infeed, séries temporais)	✅ (analise_v18: EAMI/EAIF/DMIF, TIME/DSTO)
1.9	Algoritmos de Pós-Falta (critérios, sincronismo, frequência)	✅ (estabilidade_v19)
1.10	DSA — Avaliação de Segurança Dinâmica (RSEG, snapshots)	✅ (dsa_v110)
1.10.2	Conformidade char-a-char com o manual oficial (16 códigos)	✅ (test_conformidade_manual.py)

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):

Componente	Confiança	Base de Validação	Desde
DARQ (10 subtipos)	Alta	Índice manual ANATEM confirmado	v0.4.0
DSIM (parâmetros)	Alta	Índice manual confirmado	v0.4.0
DEVT (8 tipos evento)	Alta	Nomenclatura ANATEM consolidada	v0.4.0
DPLT — barras, máquinas, circuitos, cargas	Alta	Nomenclatura consolidada, amplamente documentada	v0.4.0
DMDG (MD01–MD03)	Alta	Serialização/parser/roundtrip validados	v0.4.1
DMAQ (posicional)	Alta	Roundtrip posicional, 206 testes	v0.5.0
DCER (associação CER/SVC)	Alta	Campos/ordem §46.18 (Lst. 46.16), roundtrip	v1.1.1
DCSC (associação CSC/TCSC)	Alta	Campos/ordem §46.22 (Lst. 46.20), roundtrip	v1.1.1
DVSI (conversores FACTS VSI)	Alta	15 campos/ordem §46.64 (Lst. 46.61), colunas fixas + roundtrip¹	v1.1.1
DPLT — OLTC, FACTS, HVDC, CDU	Alta	Mnemônicos/réguas validados §13.3.1/25.4/26.4/27.5/24.6.1/29.10	v1.1.5
DCNV (conversores CA-CC LCC)	Alta	Campos/ordem §46.21 (Lst. 46.19), colunas fixas + roundtrip¹	v1.1.2
DELO (associação de elos CC)	Alta	Campos/ordem §46.27 (Lst. 46.25), roundtrip	v1.1.2
Validação cruzada	Alta	DMAQ ↔ DMDG validado	v0.7.0
LeitorPLT (formato texto)	Alta	Estrutura validada contra manual, 206 testes	v0.4.0
LeitorRelatorio	Alta	Reconhecimento de palavras-chave validado, testado	v0.4.0
LeitorSAV (ANAREDE)	Alta	Colunas fixas DBAR/DLIN + tensão-base via DGBT, fallback tolerante²	v1.1.3
BlocoCDU — parâmetros/roundtrip	Alta	Desambiguação por tipo (Cap. 29), 206 testes	v0.4.4
CDU curvas de tempo inverso (CURVA)	Alta	Tipo CURVA + subtipos IEC/IEC2/IEEE/IEEE2 §29.3.13 (Lst. 29.97–29.100)	v1.1.4
DRGT (regulador de tensão)	Alta	Estrutura §16.3 + MD01 nomeado; MD01–MD24 genérico posicional + roundtrip	v1.2.1
DRGV (regulador de velocidade)	Alta	Estrutura §16.4 + MD01 nomeado; MD01–MD07 genérico posicional + roundtrip	v1.2.2
DEST (estabilizador/PSS)	Alta	Estrutura §16.5 + MD01 nomeado; MD01–MD12 genérico posicional + roundtrip	v1.2.3
DCST (curva de saturação)	Alta	Régua Nc/Tipo/P1–P3 §16.2 (4 tipos) + roundtrip	v1.2.5
DCAG/DCCT (CAG / Ctrl. Centralizado)	Alta	Associação a CDU §46.13/§46.15 (Nc Mc[U]) + roundtrip	v1.2.6
DCAR (cargas funcionais)	Média	Params ZIP §46.14 validados; seleção (Cap. 42) preservada bruta³	v1.3.1
DMTC/DLTC (OLTC)	Alta	Controle de tap §14.1 + associação §46.40 (colunas fixas) + roundtrip	v1.3.3
DFLA (fluxo agregado)	Alta	Áreas de intercâmbio §13.1 (aninhado, FIMFLA) + roundtrip	v1.3.4
Formato .plt binário	❌ Não implementado	Estrutura de bytes desconhecida	—

¹ 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)

Classe	Descrição	Desde	Status
CasoAnatem	Caso completo (.stb); API fluente, serialização, validação cruzada	v0.4.0	✅
CasoAnatem.ler()	Abre .stb existente, reconstrói árvore de blocos	v0.4.0	✅
CasoAnatem.exportar()	Serializa para .stb com garantia de encoding latin-1	v0.4.0	✅
CasoAnatem.validar()	Validação completa (eventos, DMAQ ↔ DMDG, encoding)	v0.4.0	✅
EnsaioAnatem	Automação de lotes (sequencial/paralelo), contingências	v0.4.0	✅
BlocoDARQ	Associação de arquivos (SAV, PLT, RELA, DCDU, DBLT)	v0.4.0	✅
BlocoDOPC	Opções globais de execução (FREQ, BASE)	v0.4.0	✅
BlocoDSIM	Parâmetros de simulação (Δt, t_fim, NPAS, MXIT)	v0.4.0	✅
BlocoDEVT	Eventos (curtos, aberturas, chaveamentos, steps) — 8 tipos	v0.4.0	✅
BlocoDPLT	Variáveis de plotagem (barras, máquinas, FACTS, HVDC, CDU)	v0.4.0	✅
BlocoDMDG	Modelos predefinidos de geradores (MD01–MD03)	v0.4.1	✅
BlocoDMAQ	Associação máquina ↔ modelo dinâmico (posicional, completo)	v0.5.0	✅
BlocoDRGT	Reguladores de tensão/excitatriz predefinidos §16.3 (MD01–MD24)	v1.2.1	✅
BlocoDRGV	Reguladores de velocidade/turbina predefinidos §16.4 (MD01–MD07)	v1.2.2	✅
BlocoDEST	Estabilizadores (PSS) predefinidos §16.5 (MD01–MD12)	v1.2.3	✅
BlocoDCST	Curvas de saturação de máquina síncrona §16.2 (4 tipos)	v1.2.5	✅
BlocoDCAG, BlocoDCCT	Associação CAG/Controle Centralizado a CDU §46.13/§46.15	v1.2.6	✅
BlocoDCAR	Cargas estáticas funcionais (modelo ZIP) §46.14	v1.3.1	✅
BlocoDMTC, BlocoDLTC	Transformadores OLTC: controle de tap + associação §14.1/§46.40	v1.3.3	✅
BlocoDFLA	Fluxo Agregado de Intercâmbio (áreas de circuitos) §13.1	v1.3.4	✅
BlocoSVC, TCSC, STATCOM (DCER/DCSC/DVSI)	FACTS — associação de controles (CER/CSC) e conversores VSI; validados §46 + roundtrip	v0.4.3 (Alta em v1.1.1)	✅
BlocoHVDC (DCNV)	Conversores CA-CC de elos LCC + associação; validado §46.21 + roundtrip	v0.4.3 (Alta em v1.1.2)	✅
BlocoDELO (DELO)	Associação de elos CC aos modelos de polo; validado §46.27 + roundtrip	v1.1.2	✅
BlocoCDU, ParametroCDU	Bloco de CDU (tipos aritméticos, dinâmicos, lógicos, interface)	v0.4.4	✅
ControladorCDU	Container fluente para construir controladores CDU	v0.4.4	✅
BlocoDCDU	Bloco DCDU completo (múltiplos controladores)	v0.4.5	✅
LeitorPLT / ResultadoPLT	Lê .plt texto, acesso tabular, dataframe (pandas)	v0.4.0	✅
LeitorRelatorio / ResultadoExecucao	Lê .rela/.log, status de convergência, erros/avisos	v0.4.0	✅
LeitorSAV / ResultadoSAV	Parser .sav (ANAREDE), validação cruzada de barras/circuitos	v0.4.7	✅
ParserSTB	Parser .stb, reconstrói árvore AST, roundtrip garantido	v0.4.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

Versão	Status	Destaques
v1.3.4	⭐ Atual (Estável)	DFLA: fluxo agregado de intercâmbio §13.1 — fecha a etapa v1.3, 243 testes
v1.3.3	Estável	Transformadores OLTC: controle DMTC (§14.1) + associação DLTC (§46.40)
v1.3.2	Estável	Bancos shunt: evento MDSH (§12.1) + plotagem QSHT/QBSH/NUBSH (§12.2)
v1.3.1	Estável	DCAR: cargas estáticas funcionais (modelo ZIP) §46.14
v1.2.6	Estável	CAG (DCAG) + Controle Centralizado (DCCT) §46.13/§46.15 — fecha a etapa v1.2
v1.2.5	Estável	DCST: curvas de saturação de máquina §16.2 (4 tipos) + roundtrip
v1.2.3	Estável	DEST: estabilizadores (PSS) §16.5 (MD01–MD12 genérico + MD01 nomeado)
v1.2.2	Estável	DRGV: reguladores de velocidade/turbina §16.4 (MD01–MD07 genérico + MD01 nomeado)
v1.2.1	Estável	DRGT: reguladores de tensão predefinidos §16.3 (MD01–MD24 genérico + MD01 nomeado)
v1.1.5	Estável	DPLT 4-letra (OLTC/FACTS/HVDC/CDU) validado — fecha a etapa v1.1 (Inventário B zerado)
v1.1.4	Estável	Curvas de tempo inverso: tipo CURVA + IEC/IEC2/IEEE/IEEE2 (§29.3.13), best-effort→Alta
v1.1.3	Estável	LeitorSAV robusto (colunas fixas DBAR/DLIN + DGBT), Média→Alta
v1.1.2	Estável	HVDC DCNV re-modelado + novo DELO, validados §46.21/§46.27 + roundtrip
v1.1.1	Estável	FACTS DCER/DCSC/DVSI validados contra o manual §46 (Média→Alta) + roundtrip
v1.0.0	Estável	API estável, 206 testes, 87%+ cobertura, docs teóricas
v0.15.0	Estável	CI/CD (GitHub Actions), Codecov, mkdocs, 7 exemplos, comunidade
v0.14.2	Estável	Encoding latin-1 garantido, CDU robusto, reconciliação completa
v0.13.x	Estável	Validação FACTS/HVDC/CDU contra manual
v0.11.3	Estável	Type hints, polimento final
v0.8.x	Estável	Cobertura CDU expandida (46+ testes)
v0.7.x	Estável	Validações cruzadas (DMAQ ↔ DMDG)
v0.6.0	Estável	FACTS, HVDC, CDU, pós-processamento, LeitorSAV
v0.4.x–0.5.x	Arquivada	MVP: blocos, parser, ensaios, DMAQ posicional

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: [e-mail]

---

Licença

MIT — veja LICENSE para detalhes.

---

Créditos

Autor: Matheus Antonio Vivas Rocha (@matheusvivasr) Email: [e-mail] Instituição: Universidade de São Paulo (USP)

---

Referências

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