EXTRAÇÃO SERIAL DE ALIMENTADORES — 17/11/2026

Programa: extrair_alimentadores.py. Python 3.10+ de 64 bits, Windows/Linux,
somente biblioteca padrão. Não precisa de pip para apenas extrair/listar.
O executor elétrico opcional precisa das dependências próprias do estudo.

1. O QUE ELE LÊ E O QUE ELE ESCREVE

Entrada: modelos_completos.zip, ZIP64 com a raiz interna modelos/ e o índice
INDICE_ALIMENTADORES.csv, delimitado por vírgula, UTF-8 com BOM.

Saídas em --destino:
  modelos/INDICE_ALIMENTADORES.csv e outros índices/arquivos globais;
  modelos/Ferramentas/ e outras pastas globais de apoio;
  modelos/D<distribuidora>__<alimentador>/, sem mudar nomes nem conteúdo DSS;
  resultados/ID/, quando um executor foi solicitado;
  .extracao_serial/, recibos e relatório de retomada;
  .extracao_serial.lock, arquivo normal de bloqueio do sistema operacional.

O ZIP original não é alterado. Primeiro são materializados os apoios globais.
Depois um alimentador é extraído completamente e, se solicitado, executado.
Só após o término do subprocesso começa o alimentador seguinte. Não há
simulações nem cópias de alimentadores em paralelo neste programa.

2. COMANDOS PRONTOS

Windows PowerShell, com o script e o ZIP na pasta atual:

  py -3 Ferramentas\extrair_alimentadores.py --zip modelos_completos.zip --distribuidoras 86 --listar
  py -3 Ferramentas\extrair_alimentadores.py --zip modelos_completos.zip --destino D:\Estudos\Eflul --distribuidoras 86

Linux:

  python3 Ferramentas/extrair_alimentadores.py --zip modelos_completos.zip --distribuidoras 86 --listar
  python3 Ferramentas/extrair_alimentadores.py --zip modelos_completos.zip --destino estudos/Eflul --distribuidoras 86

Uma distribuidora ou várias: --distribuidoras 86 4950
Nomes exatos também são aceitos, sem diferenciar acentos/maiúsculas:
  --distribuidoras Eflul Cemig-D
Todas: --distribuidoras todas (é o padrão).
Um alimentador: --alimentadores D4950__MCLD201
Também se pode usar o código original --alimentadores MCLD201. Se o código
ocorrer em várias distribuidoras selecionadas, use o id_pasta completo.
Piloto: --limite 1, que usa a ordem do índice e não cria outros alimentadores.
--listar não cria pastas nem extrai dados; informa seleção e tamanhos.

3. EXTRAIR, EXECUTAR E OPCIONALMENTE LIBERAR ESPAÇO

Use o Python do ambiente virtual que já possui o motor OpenDSS e as demais
dependências do executor. Este extrator chama o MESMO Python, sem shell:

  PYTHON SCRIPT --master DESTINO/modelos/ID/Master.dss --saida DESTINO/resultados/ID

Por exemplo, se o executor disponibilizado se chama simular_fluxo_reverso.py:

  BABI_env/bin/python Ferramentas/extrair_alimentadores.py --zip modelos_completos.zip --destino estudos/lote --distribuidoras 86 --executar Ferramentas/simular_fluxo_reverso.py

Windows (ajuste a letra de unidade e os caminhos):

  .\BABI_env\Scripts\python.exe Ferramentas\extrair_alimentadores.py --zip modelos_completos.zip --destino D:\Estudos\lote --distribuidoras 86 --executar Ferramentas\simular_fluxo_reverso.py

Argumentos adicionais do executor ficam APÓS --argumentos-execucao, que deve
ser a última opção do extrator. Exemplos: --argumentos-execucao --mes 12
(use somente opções realmente aceitas pelo executor escolhido).
--master e --saida já são definidos pelo extrator; não os repita.

Acrescente --remover-apos-executar para apagar a pasta do alimentador após
exit=0. Ela só será removida se tiver sido criada NESTA invocação do extrator.
Pastas de execução anterior, mesmo reconhecidas e íntegras, são preservadas.
Falhas do executor preservam a pasta para diagnóstico; os resultados globais,
os índices e o ZIP nunca são removidos. Exit=0 do executor é seu contrato de
sucesso, não uma certificação independente de validade física da simulação.

O caminho informado em --saida é uma PASTA de resultados por alimentador.
Um programa que espere um nome de arquivo JSON nessa opção precisa de um
adapter; não confunda esse contrato com o runner legado de saída JSON única.

4. INTEGRIDADE, RETOMADA E CUIDADOS COM O DESTINO

O extrator rejeita caminhos relativos/absolutos externos, drives Windows,
nomes Windows reservados, links simbólicos, junctions, arquivos especiais e
colisões de nomes (inclusive maiúsculas/minúsculas e normalização Unicode).
Cada arquivo é copiado em blocos de 1 MiB e tem seu CRC verificado ao final.
Uma pasta/arquivo só é publicada após terminar integralmente em staging.

Repita o mesmo comando, com o MESMO ZIP e destino, para retomar. Unidades já
concluídas são conferidas por inventário, tamanho e CRC antes da reutilização.
Edições manuais/arquivos extras não são sobrescritos silenciosamente. Uma
pasta de alimentador preexistente sem recibo próprio é preservada e recusada.
Ao mudar a versão do ZIP, use um novo --destino; não misture duas coleções.

A identidade rápida da versão é o SHA-256 do tamanho e diretório central do
ZIP; ela não é o SHA-256 integral do arquivo. Use também o SHA256SUMS.txt do
download para conferir o pacote completo. O CRC detecta corrupção acidental;
não é uma assinatura criptográfica do fornecedor.

O bloqueio do SO impede duas invocações simultâneas no mesmo destino e é
liberado quando o processo termina. Não remova o arquivo de lock enquanto
houver processo ativo. Quedas abruptas do SO podem deixar staging privado
stage-* em .extracao_serial/; esses diretórios não são modelos publicados e
não são reutilizados como se estivessem completos. A retomada recomeça a
unidade incompleta e preserva as unidades concluídas.

5. ESPAÇO, MEMÓRIA E LIMITES ELÉTRICOS

O ZIP nacional de outubro tem aproximadamente 32,71 GiB. A seleção de uma
distribuidora evita extrair a coleção inteira. Com remoção após execução, o
espaço dos modelos acompanha aproximadamente o maior alimentador selecionado,
mais apoios globais, staging e resultados. Sem essa flag, as pastas extraídas
se acumulam deliberadamente. Arquivos individuais são streaming, mas a
biblioteca zipfile carrega o diretório central: o piloto com ~1,2 milhão de
entradas teve pico de RAM de aproximadamente 1,06 GiB.

Este programa apenas seleciona, extrai e encadeia execuções. Não habilita GD,
não cria curvas de geração, não altera consumo, não conecta alimentadores e
não transforma a fonte equivalente MT em um transformador da rede básica.
Use o executor e os manuais elétricos da entrega para os cenários de GD e
para distinguir observações BDGD, hipóteses meteorológicas e vínculos AT.

6. TESTES REPRODUZÍVEIS

  python -m unittest discover -s Ferramentas -p test_extrair_alimentadores.py -v

As fixtures são ZIPs pequenos para testar segurança/contrato. Não são
circuitos elétricos usados como evidência de resultados do estudo.
