ABGD / OPENDSS — EXTRAÇÃO SERIAL, GD TEMPORAL E FLUXO REVERSO
Entrega de 17/11/2026. Leia este manual antes de interpretar os resultados.

1. O QUE VOCÊ ESTÁ RECEBENDO

O arquivo modelos_completos.zip continua com o MESMO formato:

  modelos/
    INDICE_ALIMENTADORES.csv
    INDICE_ALIMENTADORES_FRONTEIRAS.csv
    INDICE_GD_DISTRIBUIDORAS.csv
    PONTOS_METEOROLOGIA.csv
    Ferramentas/
    Perfis_GD/D86/2025_12.csv e .json
    Dados_GD/D86.parquet e D86_proveniencia.json
    D86__001/
      Master.dss, Master_DU.dss, Master_SA.dss, Master_DO.dss
      Condutores.dss, Transformadores.dss, LinhasMT.dss, LinhasBT.dss, ...
      Cargas.dss, GD_desabilitada.dss, Regularizacao_numerica.dss
      apoio/energias/, apoio/curvas.parquet, apoio/dias_mes.json
      apoio/gd.parquet                  NOVO: informações das UGs deste caso
    D4950__MCLD201/ ...

São 27.910 alimentadores de 102 distribuidoras, cada qual independente.
O ZIP é ZIP64: use disco NTFS/exFAT/ext4; FAT32 não comporta este arquivo.
Não é necessário extrair o Brasil todo. O script copia UM alimentador,
executa o estudo, espera terminar e só então passa ao próximo. Índices,
ferramentas, dados de auditoria e perfis globais são extraídos uma vez.
Pico de RAM medido no extrator: aproximadamente 1,1 GiB, principalmente pela
leitura do diretório central do ZIP com mais de um milhão de entradas.
O motor pode precisar de mais RAM para alimentadores grandes.

As contagens de UG recuperadas são 3.986.271 registros brutos e 3.885.686
Generator existentes nos DSS. Todos estes Generator têm correspondência
conferida com a origem; 100.585 UGs brutas não estavam nos modelos elétricos
legados. Elas ficam em Dados_GD para auditoria, sem inserir topologia inventada.
Há 3.652.332 geradores com tecnologia identificada pelo CEG no cadastro ANEEL
e 233.354 sem identificação tecnológica. Tecnologia conhecida não significa
necessariamente FV; o diagnóstico distingue os tipos.

2. COMEÇAR NO WINDOWS, SEM EXTRAIR O ZIP GIGANTE

Instale Python 3.12 de 64 bits. Baixe modelos_completos.zip e o pacote menor
Ferramentas_estudo.zip na página de download. Coloque-os, por exemplo, em
D:\BDGD. No PowerShell, execute:

  cd D:\BDGD
  Expand-Archive -LiteralPath .\Ferramentas_estudo.zip -DestinationPath .\kit
  py -3.12 .\kit\Ferramentas\criar_ambiente.py --destino .\BABI_env

O kit contém os wheels das dependências para Windows x64/Python3.12, inclusive
o motor DSS. criar_ambiente.py os instala sem baixar pacotes quando executado
no Windows. Python em si deve estar instalado. Não copie o venv Linux.
Dependências/versões estão em Ferramentas/requirements.txt; os wheels e seus
SHA-256 estão em Ferramentas/SHA256_WHEELS_WINDOWS.txt.
Não é preciso instalar o OpenDSS GUI para executar o motor Python.

Somente listar os alimentadores da Eflul, sem extrair nem simular:

  .\BABI_env\Scripts\python.exe .\kit\Ferramentas\extrair_alimentadores.py --zip .\modelos_completos.zip --distribuidoras 86 --listar

Executar os alimentadores da Eflul, em série, no dia útil típico de dezembro:

  .\BABI_env\Scripts\python.exe .\kit\Ferramentas\rodar_distribuidoras.py --zip .\modelos_completos.zip --destino D:\Estudos\Eflul --distribuidoras 86 --mes 12 --tipo-dia DU

Outras seleções, no mesmo comando:
  --distribuidoras 4950                  Cemig
  --distribuidoras 4950 2866 63          Cemig, Copel e CPFL Paulista
  --distribuidoras todas                Brasil, UM alimentador por vez
  --distribuidoras 86 --alimentadores 001
  --distribuidoras 4950 --alimentadores MCLD201
  --distribuidoras 86 --limite 1         piloto com apenas um alimentador

Confira sempre os códigos no índice; nomes também são aceitos pelo extrator.
--limite precisa ser >=1: zero não significa Brasil inteiro.
--tipo-dia pode ser DU, SA ou DO. --mes pode ser1...12.
A natureza típica do perfil GD e as limitações dos feriados constam dos JSONs.

Para poupar espaço durante uma execução nacional, acrescente explicitamente:
  --remover-apos-executar
Isso apaga SOMENTE o alimentador criado naquela invocação e apenas se o estudo
terminar com exit0. Não apaga ZIP, resultados nem pastas anteriores.
Os Master_GD dos resultados dependem dos DSS extraídos: se usar a remoção,
reextraia o alimentador no mesmo destino para reabrir o cenário no GUI.
O script não mistura dados de ZIPs diferentes no mesmo destino.

Interrupção: repita o mesmo comando com o MESMO ZIP e destino. Arquivos
extraídos anteriormente são validados por CRC antes do reuso. Alimentadores
concluídos podem ser simulados de novo; o resultado da mesma pasta é atualizado.
Para preservar uma comparação anterior, escolha outro --destino ou use o runner
individual com outra pasta --saida. Resultados rejeitados não são eliminados.

3. EXTRAIR PARA AUDITAR OU USAR O OPENDSS GUI

Extrair uma distribuidora sem rodar qualquer estudo:

  .\BABI_env\Scripts\python.exe .\kit\Ferramentas\extrair_alimentadores.py --zip .\modelos_completos.zip --destino D:\Estudos\Base --distribuidoras 86

A pasta é D:\Estudos\Base\modelos\D86__001, e não um nível adicional
modelos/alimentadores/. Os arquivos nativos continuam sendo texto .dss.
Master.dss preserva o caso legado, com GD desabilitada. NÃO habilite todos os
Generator sem Daily: isso voltaria a injetar potência nominal constante.

Gerar o cenário com GD e seus CSVs, a partir da pasta já extraída:

  .\BABI_env\Scripts\python.exe .\kit\Ferramentas\executar_estudo_serial.py --master D:\Estudos\Base\modelos\D86__001\Master.dss --saida D:\Estudos\Cenario_Eflul_001 --mes 12 --tipo-dia DU

O adaptador seleciona automaticamente Perfis_GD/D86/2025_12.csv, a partir do
código e do ano do manifesto. Também aceita --perfil-gd CAMINHO para um perfil
local auditável e --perfis-raiz PASTA para uma outra coleção de perfis.
No GUI do OpenDSS, abra o Master_GD que o runner gerou:

  Compile "D:/Estudos/Cenario_Eflul_001/Master_GD.dss"

Esse Master já executa 24 passos; não acrescente outro Solve automaticamente.
Ele carrega os mesmos DSS locais do alimentador, mais Curva_GD.dss,
Edits_GD.dss e Edits_Cargas.dss. Os Redirect são relativos ao cenário gerado.
Mantenha a relação entre a pasta do cenário e a pasta extraída.

4. COMO A GD É MODELADA, E O QUE A ENERGIA SIGNIFICA

POT_INST é potência em kW; ENE_01...ENE_12 são energias mensais em kWh.
Na interpretação normativa do BDGD, ENE da UC é importação da rede, e ENE da UG
é exportação/injeção na rede. Não são a carga total atrás do medidor nem toda
a geração do inversor. Sem armazenamento, o balanço é:

  L = I - X + G

I=importação; X=exportação; G=geração bruta; L=carga total, no mesmo período
e fronteira. G e autoconsumo não são identificados só por I, X e POT_INST.
Por isso, não subtraímos geração bruta de uma carga já calibrada pela importação.

Convenção padrão --convencao exportacao-bdgd:
  O Generator representa a injeção X declarada, não G bruta.
  f_h é o coeficiente do perfil meteorológico, 0<=f_h<=1, h=0...23.
  N_m é o número de dias do mês na safra daquele alimentador.
  b_i = ENE_UG_i,m / (N_m * soma_h(f_h * 1h))                [kW]
  P_UG_i,h = b_i * f_h * fator_gd                            [kW]
  N_m * soma_h(P_UG_i,h * 1h) = ENE_UG_i,m * fator_gd        [kWh]

A energia fecha exatamente para o mês quando o registro é elegível; a forma
horária é uma hipótese modelada, não medição individual. DU/SA/DO usam a mesma
forma GD mensal; a carga usa sua respectiva curva CRVCRG e calibração mensal.
O número de UCs/GDs energizadas e a potência efetivamente resolvida no circuito
podem ser menores que os valores solicitados; isso é registrado separadamente.

Energia ausente/negativa não vira POT_INST*24h. Pico calibrado acima de POT_INST
gera diagnóstico e exclusão do cenário-base, sem clipping silencioso.
O limite físico adicional ENE<=POT_INST*24h*N_m é auditado em qualquer fonte.
Não multiplicamos UGMT por1000 automaticamente: a documentação consultada
define POT_INST em kW tanto na UGBT como na UGMT.
Exemplo real MCLD201: 3,7kW e 520.800kWh em dezembro são incompatíveis com
3,7*744=2.752,8kWh. Isso pode refletir problemas declaratórios/escala, mas
não autoriza escolher silenciosamente uma correção de unidade.

O padrão seleciona somente tecnologia FV identificada por CEG único no cadastro
ANEEL. Fontes distintas e desconhecidas são quantificadas em diagnostico_GD.csv.
Os dados de todas as UGs continuam no pacote. Esta versão NÃO inventa perfis
horários para hidrelétrica, eólica ou térmica; elas precisam de perfil próprio
e de uma extensão explícita do despacho antes de serem habilitadas.

Se o usuário decidir ASSUMIR que a fonte não informada é FV, acrescente:
  --assumir-fonte-desconhecida FV
A escolha e sua quantidade/potência aparecem no resumo. Outra fonte conhecida
não é reclassificada. Ausência de elegíveis não significa ausência de GD.

Sensibilidade de GD adicional:
  --convencao incremental --fator-gd 1.5 --fator-carga 1.0
Aqui b_i=POT_INST; é geração incremental sobre a referência de importação da
UC, NÃO reconstrução histórica de geração/carga bruta. Fator>1 é cenário que
pode exceder a capacidade instalada; isso fica sinalizado no resultado.
Use --fator-gd 0 para comparar sem injeção e a mesma configuração de carga.

5. IRRADIÂNCIA, TEMPERATURA, DATAS E HIPÓTESES

Perfis_GD contém os 12 meses de cada uma das 102 distribuidoras:1.224 CSVs.
Cada diretório guarda resposta NASA original, URL, SHA256 e metadados.
A consulta é horária em UTC; o código converte para o fuso civil IANA antes
de calcular as médias por hora de cada mês. LST solar não foi confundido com
hora civil. O fuso foi escolhido pela UF modal das UGs (Noronha tratado à parte),
portanto uma concessão que cruza fusos exige consulta/estudo locacional próprio.

É usado UM ponto meteorológico de referência por distribuidora. Sua localização
é a média de uma amostra de Buscoords, explicitada em PONTOS_METEOROLOGIA.csv.
Isso reduz volume e permite estudar offline, mas NÃO resolve diferenças entre
telhados/alimentadores numa grande concessão. A malha NASA também tem resolução
espacial própria. Para estudo local, refaça a consulta no ponto adequado:

  .\BABI_env\Scripts\python.exe .\kit\Ferramentas\preparar_perfil_solar.py --latitude -28.52317 --longitude -49.30769 --ano 2025 --mes 12 --fuso America/Sao_Paulo --saida D:\Estudos\ClimaLocal

Passe o novo CSV ao runner com --perfil-gd. Para medições locais, forneça CSV
com exatamente hora=0...23 e multiplicador finito0...1; pode incluir
irradiancia_W_m2 e temperatura_C. Forneça .json lateral com fonte/hipóteses.
Nenhum dado meteorológico ausente é preenchido com uma curva inventada.

A NASA fornece ALLSKY_SFC_SW_DWN em Wh/m² por intervalo de1h. Dividimos por1h
para obter irradiância média em W/m². T2M é temperatura do ar em°C, não da célula.
O modelo simplificado do perfil é:
  T_cel = T2M + (NOCT-20) * GHI/800                         [°C]
  f = clip((GHI/1000) * max(0,1+gamma*(T_cel-25)),0,1)       [adimensional]
  NOCT=45°C e gamma=-0,004/°C são HIPÓTESES controláveis:
  --noct 45 --gamma -0.004
Depois calcula-se a média de f por hora civil no mês.
GHI horizontal é aproximação da irradiância no plano do módulo. Não foram
inventados inclinação, orientação, sombra ou parâmetros individuais do inversor.
Os CSVs guardam GHI, T2M e T_cel modelada para auditar a transformação.

O despacho permanece Generator AC com perfil, não um PVSystem completo.
Para representar módulo/inversor em PVSystem, são necessários parâmetros DC/AC,
curvas de eficiência/P-T, plano do módulo e dados próprios; não basta renomear
Generator. Não se usa irradiância em W/m² num campo que espere kW/m².

As safras BDGD são99 de2025, duas de2023 e uma com BASE.DAT_FNL de2022
(Ceres, título2023). A meteorologia acompanha o ano interno de cada modelo.
Data do download/publicação2026 não foi usada como ano de energia.

6. O QUE O ESTUDO REALMENTE MEDE NA FRONTEIRA

P_cabeceira = -Circuit.TotalPower[0]                        [kW]
Positivo: a fonte equivalente alimenta o circuito. Negativo: o circuito exporta
para essa fonte. MW=kW/1000. Cada alimentador tem sua própria fonte MT.
Essa cabeceira NÃO é automaticamente um transformador da rede básica.

O índice novo conserva SUB, UNI_TR_AT e PAC_INI. Esses são vínculos cadastrais,
não uma prova de conectividade AT/transmissão ou da ordem física dos terminais.
É possível somar os casos por UNI_TR_AT para um indicador, mas não chamar essa
soma de medição no banco345/138kV. Não há interligação entre distribuidoras neste
pacote. Não foi criada transmissão fictícia para fazer o Brasil virar um circuito.

O runner exporta P/Q de TODOS os terminais dos transformadores realmente
existentes no circuito. Potência é positiva ENTRANDO no terminal.
Se o usuário possui/integra um transformador físico de fronteira no seu Master,
pode solicitar explicitamente, por exemplo:
  --fronteira-transformador Transformer.NOME_REAL:1 --confirmar-fronteira-fisica
O elemento precisa existir, o terminal precisa ser válido, ter tensão nominal
>=200kV e estar no lado de maior tensão. A confirmação física é responsabilidade
externa declarada; a flag não cria o transformador nem comprova a conexão ao SIN.

No terminal de suprimento efetivamente modelado:
  P_prim = soma_fases(P_entrando_terminal)                    [kW]
  P_prim<0 caracteriza exportação naquele terminal.
  E_reversa = soma_h(max(-P_prim_h,0)*1h)/1000                [MWh]
Um Monitor nativo pode usar Mode=1 PPolar=No para preservar P/Q e seu sinal.
Mode=33 grava magnitude; não serve para decidir o sentido de P.

Para os bancos de fronteira física, ainda é indispensável fornecer/validar o
caminho AT, os próprios bancos, parâmetros e conexões, estados operativos e
as demais cargas/GDs daquele caminho. Somar uma carga AT agregada já existente
aos seus alimentadores detalhados sem removê-la duplicaria consumo.

7. RESULTADOS, INTEGRIDADE E AGREGAR A SELEÇÃO

DESTINO/resultados/ID/ contém:
  resumo.json: parâmetros, safras, fontes, coberturas, hipóteses, hashes,
               passos aceitos, balanço e energias reversas.
  serie_horaria.csv: 24 intervalos [h,h+1), P/Q, kW/MW, perdas, tensão e aceitação.
  transformadores_horarios.csv: todos os terminais, kW/kvar/MW e sinal.
  diagnostico_GD.csv: todos os geradores do apoio e motivo de seleção/exclusão.
  perfil_GD_utilizado.csv: coeficientes e meteorologia usados.
  Master_GD.dss + Curva_GD.dss + Edits_GD.dss + Edits_Cargas.dss: caso GUI.

O balanço conferido é P_cabeceira+P_GD_real-P_cargas_real-P_perdas≈0.
Circuit.Losses sai em W/var e é dividido por1000 para kW/kvar.
Convergência sem balanço/valores finitos não libera o passo como válido.
Convergência não prova energização de todas as fases, proteção adequada,
completude do cadastro ou compatibilidade com uma condição operativa real.

Agregação cadastral dos casos concluídos, sem misturar fatores, meses ou fusos:

  .\BABI_env\Scripts\python.exe .\kit\Ferramentas\agregar_resultados.py --resultados D:\Estudos\Eflul\resultados --indice D:\Estudos\Eflul\modelos\INDICE_ALIMENTADORES_FRONTEIRAS.csv --saida D:\Estudos\Eflul\agregado

A soma compara o número de alimentadores simulados ao número cadastrado por
grupo. Energia inversa do grupo é calculada DEPOIS da soma dos fluxos; somar
exportações individuais daria outra grandeza. O CSV NÃO é fluxo físico no trafoAT.

Exemplos_resultados/Eflul_001 guarda resultados REAIS com o perfil NASA fornecido
para DU/SA/DO e um LEIA-ME. Não são gráficos ou cenários numéricos fictícios.
Arquivos de teste artificiais não integram esses resultados de referência.

8. LINUX E RECONSTRUÇÃO NA MÁQUINA DE ORIGEM

Na pasta onde o kit foi extraído:
  python3.12 Ferramentas/criar_ambiente.py --destino BABI_env
  BABI_env/bin/python Ferramentas/rodar_distribuidoras.py --zip modelos_completos.zip --destino estudo --distribuidoras 86 --mes 12 --tipo-dia DU
No Linux, a instalação pip pode usar internet. O pacote offline de wheels é
específico para Windows x64/Python3.12. Os testes elétricos foram feitos com
o motor dss-python no Linux; não houve execução nativa do Windows nesta máquina.

Construcao/ guarda os scripts que recuperaram metadados UG e prepararam esta
publicação, com caminhos originais/argumentos indicados no LEIA-ME próprio.
Para estudar os alimentadores já formatados, não é necessário ter os brutos,
QGIS, pyogrio ou executar novamente a conversão nacional.

9. FONTES E CONFERÊNCIAS

BDGD original: ZIPs ArcGIS ANEEL, preservados, com item/URL/hash nas proveniências.
Manual BDGD e PRODIST Módulo10:
  https://www2.aneel.gov.br/cedoc/aren2020888_prodist_modulo_10_v1.pdf
  UGBT/UGMT: POT_INST emkW, ENE mensal emkWh; CRVCRG não é telemedição individual.
Tecnologia da GD, apenas por CEG único:
  https://dadosabertos.aneel.gov.br/dataset/relacao-de-empreendimentos-de-geracao-distribuida
NASA POWER, parâmetros horários, UTC versus LST:
  https://power.larc.nasa.gov/docs/services/api/temporal/hourly/
Generator e perfis:
  https://opendss.epri.com/Generator.html
Monitor e potência com sinal:
  https://opendss.epri.com/Monitor.html
Condições de PVSystem e unidades:
  https://opendss.epri.com/Operatingconditionsproperties.html
Interface e convenção dos terminais:
  https://opendss.epri.com/PythontoOpenDSSInterface.html

O manifesto externo do ZIP fornece tamanho e SHA256; SHA256SUMS.txt pode ser
comparado com Get-FileHash -Algorithm SHA256 no PowerShell. CRC é verificado
durante a extração de cada arquivo. A configuração anterior é preservada pela
publicação atômica; não foram apagados os modelos legados nem os BDGD originais.
