Metadata-Version: 2.5
Name: sintetizador-novomodelo
Version: 0.2.0
Summary: sintetizador-novomodelo
Project-URL: Documentation, https://rjmalves.github.io/sintetizador-novomodelo/
Project-URL: Repository, https://github.com/rjmalves/sintetizador-novomodelo/
Author-email: Rogerio Alves <rogerioalves.ee@gmail.com>, Miryam Gerk <miryam_gerk@poli.ufrj.br>
License: MIT License
        
        Copyright (c) 2026 Rogerio Alves
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: click>=8.1.7
Requires-Dist: numpy>=1.26
Requires-Dist: pandas
Requires-Dist: polars>=1.24.0
Requires-Dist: pyarrow>=18.0.0
Provides-Extra: dev
Requires-Dist: furo; extra == 'dev'
Requires-Dist: matplotlib; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: numpydoc; extra == 'dev'
Requires-Dist: plotly; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: sphinx; extra == 'dev'
Requires-Dist: sphinx-gallery; extra == 'dev'
Requires-Dist: types-python-dateutil; extra == 'dev'
Provides-Extra: politica
Requires-Dist: novomodelo-python; (python_version >= '3.12') and extra == 'politica'
Description-Content-Type: text/markdown

# sintetizador-novomodelo

Programa auxiliar para realizar a síntese de dados de saída do NOVOMODELO em arquivos de texto ou banco de dados.

<!-- TODO: descomentar os badges quando a CI (Codecov) e a publicação no PyPI estiverem ligadas
[![tests](https://github.com/rjmalves/sintetizador-novomodelo/actions/workflows/main.yml/badge.svg)](https://github.com/rjmalves/sintetizador-novomodelo/actions/workflows/main.yml)
[![codecov](https://codecov.io/gh/rjmalves/sintetizador-novomodelo/graph/badge.svg)](https://codecov.io/gh/rjmalves/sintetizador-novomodelo)
[![PyPI](https://img.shields.io/pypi/v/sintetizador-novomodelo)](https://pypi.org/project/sintetizador-novomodelo/)
[![Python](https://img.shields.io/pypi/pyversions/sintetizador-novomodelo)](https://pypi.org/project/sintetizador-novomodelo/)
[![docs](https://img.shields.io/badge/docs-online-blue)](https://rjmalves.github.io/sintetizador-novomodelo/)
[![license](https://img.shields.io/github/license/rjmalves/sintetizador-novomodelo)](https://github.com/rjmalves/sintetizador-novomodelo/blob/main/LICENSE)
-->

As sínteses seguem o mesmo modelo unificado de dados do [sintetizador-decomp](https://github.com/rjmalves/sintetizador-decomp): os arquivos e as colunas têm os mesmos nomes e tipos, de modo que as ferramentas que leem a síntese de um caso DECOMP leem também a de um caso NOVOMODELO.

## Instalação

A instalação pode ser feita diretamente via `uv`:

```
$ uv pip install .
```

A síntese da política (cortes de Benders) depende das bindings [novomodelo-python](https://github.com/ons-ccee-epe/novomodelo), que exigem Python >= 3.12. Elas são instaladas pelo extra `politica`:

```
$ uv pip install ".[politica]"
```

Sem o extra, os comandos `politica` e `completa` registram um aviso e não geram `CORTES_COEFICIENTES`, `CORTES_VARIAVEIS` nem `METADADOS_POLITICA`; as demais sínteses não são afetadas.

Para desenvolvimento local com todas as dependências:

```
$ git clone https://github.com/rjmalves/sintetizador-novomodelo
$ cd sintetizador-novomodelo
$ uv sync --all-extras --dev
```

## Modelo Unificado de Dados

As saídas são geradas em formato Parquet e podem ser lidas com [pandas](https://pandas.pydata.org/) ou [Polars](https://pola.rs/):

```python
import pandas as pd
df = pd.read_parquet("sintese/CMO_SBM.parquet")

import polars as pl
df = pl.read_parquet("sintese/CMO_SBM.parquet")
```

## Comandos

O `sintetizador-novomodelo` é uma aplicação CLI, executada no diretório do caso (ou fora dele, com `--caso`). Ele lê as saídas do NOVOMODELO em `./output/` e escreve a síntese em `./sintese/`:

```
$ cd meu-caso
$ sintetizador-novomodelo completa

> 2026-11-06 19:00:02,830 INFO: # Realizando síntese COMPLETA #
> 2026-11-06 19:00:02,831 INFO: Caso: /home/usuario/meu-caso
> 2026-11-06 19:00:02,831 INFO: Saídas do modelo: /home/usuario/meu-caso/output
> 2026-11-06 19:00:02,831 INFO: Diretório de síntese: /home/usuario/meu-caso/sintese
...
> 2026-11-06 19:00:22,815 INFO: # Fim da síntese (19.98 s) #
```

| Comando | Descrição |
|---|---|
| `completa` | sistema → execução → cenários → operação → política |
| `sistema [VARIAVEIS...]` | dados do sistema |
| `execucao [VARIAVEIS...]` | dados da execução |
| `cenarios [VARIAVEIS...]` | dados dos cenários |
| `operacao [VARIAVEIS...]` | dados da operação |
| `politica [VARIAVEIS...]` | cortes de Benders da política |
| `limpeza` | apaga o diretório de síntese |

Sem `VARIAVEIS`, cada comando sintetiza tudo o que suporta. As variáveis aceitam curingas (`sintetizador-novomodelo operacao "EARM*"`). No `completa`, as variáveis de cada categoria são passadas pelas opções `--sistema`, `--execucao`, `--cenarios`, `--operacao` e `--politica`, que podem ser repetidas.

Opções:

- `--formato`: `PARQUET` (padrão) ou `CSV`.
- `--caso`: diretório do caso, relativo ao diretório atual ou absoluto (padrão: o diretório atual). Permite rodar a síntese de fora do caso, por exemplo quando ele está numa subpasta: `sintetizador-novomodelo completa --caso meu-caso`. A síntese continua sendo escrita em `./sintese/`, relativo ao diretório atual. Todos os comandos, exceto `limpeza`.
- `--saida-modelo`: diretório com as saídas do NOVOMODELO, relativo ao caso (padrão `output`).
- `--codigos`: `sequencial` (padrão, código = `id + 1`) ou `originais` (código = `id`). Todos os comandos, exceto `limpeza`. Ver [Diferenças em relação ao sintetizador-decomp](#diferenças-em-relação-ao-sintetizador-decomp).
- `--processadores`: aceita por compatibilidade com o sintetizador-decomp (`operacao` e `completa`).

Variáveis de ambiente:

- `DIRETORIO_SINTESE`: diretório de escrita (padrão `sintese`, relativo ao diretório atual, que é o caso quando `--caso` não é usado; aceita caminho absoluto). É criado se não existir.
- `FORMATO_SINTESE`: sobrescrito por `--formato`.
- `CODIGOS_ENTIDADES`: `sequencial` (padrão) ou `originais`; sobrescrito por `--codigos`. Um valor inválido encerra o comando com erro, sem sintetizar.

## Arquivos produzidos

| Categoria | Arquivos |
|---|---|
| sistema | `EST`, `PAT`, `SBM`, `UTE`, `CVU`, `UHE`, `METADADOS_SISTEMA` |
| execução | `PROGRAMA`, `VERSAO`, `TITULO`, `CONVERGENCIA`, `TEMPO`, `CUSTOS`, `INVIABILIDADES`, `METADADOS_EXECUCAO` |
| cenários | `PROBABILIDADES`, `METADADOS_CENARIOS` |
| operação | sínteses abaixo, `ESTATISTICAS_OPERACAO_{SIN,SBM,UHE,UTE,SBP}`, `METADADOS_OPERACAO` |
| política | `CORTES_COEFICIENTES`, `CORTES_VARIAVEIS`, `METADADOS_POLITICA` |

Em `CORTES_COEFICIENTES`, o `lag` depende do `tipo_coeficiente`:

- tipo 4 (`GTER`, geração térmica antecipada): o estado é a geração comprometida em MW, sem patamar (`patamar` = 0); o `lag` é o deslocamento do estágio de entrega (`interval_start` do `entity_manifest`) em relação ao estágio do corte, no eixo formado pelos estágios de `stages.json` seguidos dos de `post_study_stages.json`. Sem esse calendário, ou com a data de entrega ausente, o `lag` é o posto da data de entrega por térmica (1..k).
- tipo 7 (`QINC`) e tipo 8 (`QDEF`): o `lag` é o subíndice do NOVOMODELO (tipo 8: 1..k).
- demais tipos: `lag` = 0.

Sínteses da operação:

- `CMO_SBM`
- custos: `CTER_UTE`, `CTER_SIN`, `COP_SIN`, `CFU_SIN`
- energia armazenada e percentual, inicial e final: `EARM{I,F}_{SBM,SIN}`, `EARP{I,F}_{SBM,SIN}`
- geração: `GTER_{SBM,SIN,UTE}`, `GHID_{UHE,SBM,SIN}`, `GUNS_{SBM,SIN}`
- energia natural afluente: `ENAA_{SBM,SIN}`
- mercado e déficit: `MER_{SBM,SIN}`, `MERL_{SBM,SIN}`, `DEF_{SBM,SIN}`
- volumes: `VARP{I,F}_UHE`, `VARM{I,F}_{UHE,SBM,SIN}`
- vazões: `Q{INC,AFL,DEF,TUR,VER,RET,EVP,DES}_UHE`
- energia vertida: `EVER{,T,NT}_{UHE,SBM,SIN}`
- intercâmbio: `INT_SBP`, `INTL_SBP`

`INVIABILIDADES` é omitido (com aviso) quando a simulação não tem violações. Um caso completo gera 82 arquivos: os 97 do sintetizador-decomp menos os 15 de REE e ENAC.

## Diferenças em relação ao sintetizador-decomp

- **Códigos de entidade:** `codigo_usina`, `codigo_submercado`, `codigo_submercado_de`, `codigo_submercado_para`, o `codigo` de `INVIABILIDADES` e o `indice_entidade` de `CORTES_COEFICIENTES` dependem de `--codigos` (ou `CODIGOS_ENTIDADES`):
  - `sequencial` (padrão): código = `id + 1` do NOVOMODELO. Os códigos originais do DECOMP não são recuperados.
  - `originais`: código = `id` do NOVOMODELO. Só faz sentido quando o caso convertido manteve os códigos do DECOMP como ids (ex.: FURNAS id 6, submercado FC id 11); então os Parquet podem ser cruzados por código com os do sintetizador-decomp. Em um caso com ids sequenciais a partir de 0, gera códigos começando em 0.

  Posições (`estagio`, `cenario`, `patamar`, `no`, `indice_corte`, `lag`, `iteracao`) não mudam. REE continua ausente em ambos os modos.
- **Sem REE:** o NOVOMODELO não tem reservatório equivalente. Não são gerados `REE`, `ESTATISTICAS_OPERACAO_REE` nem os arquivos `*_REE`. A coluna `codigo_ree` das tabelas de usinas hidrelétricas é mantida, toda nula (`Int64`), e `ree` em `UHE` é uma string nula.
- **Sem ENAC:** `ENAC_SBM` e `ENAC_SIN` não têm equivalente no NOVOMODELO.
- **Agregação por submercado:** cada usina é atribuída ao barramento principal dos seus grupos geradores (`unit_groups`). A exceção é `GHID_SBM`, que soma a geração por barramento (`simulation/hydro_bus_generation`). Como o DECOMP credita a energia armazenada a submercados a jusante via REE, `EARM*_SBM` pode diferir do DECOMP por submercado, embora os totais do SIN coincidam.
- **`INT_SBP.limite_inferior`** é `float64` (`int64` no DECOMP).
- **Sínteses calculadas** a partir dos dados de entrada (★):

| Arquivo | Dados de entrada usados | Cálculo |
|---|---|---|
| `VARM{I,F}_UHE`, `VARM*_SBM/SIN` | `hydros.json reservoir.min/max_storage_hm3`, barramento principal (`unit_groups`) | volume útil = armazenamento − mínimo físico; soma por barramento |
| `VARP{I,F}_UHE` | `reservoir.min/max_storage_hm3` | 100·útil/(max−min), exclui fio d'água |
| `EARM{I,F}_SBM/SIN` | `reservoir.*`, barramento principal | MWh ÷ 730 → MWmes; limite superior = EARMmax |
| `EARP{I,F}_SBM/SIN` | `reservoir.*` + produtividade acumulada integrada (saída) | 100·ΣEARM/ΣEARMmax |
| `ENAA_SBM/SIN` | barramento principal | soma por barramento |
| `QAFL_UHE` | `hydros.json downstream_id` | incremental + desviada + defluência média de montante |
| `QRET_UHE` | `constraints/hydro_bounds.water_withdrawal_m3s` | alvo + violação pos − neg |
| `QVER_UHE` (limites) | `constraints/hydro_bounds.min/max_spillage_m3s` | bloco > estágio > padrão |
| `EVERT/EVERNT/EVER_*` | limite superior de turbinamento (`dict/bounds` ou `hydros.json`) | divisão turbinável/não turbinável × produtividade |
| `GTER_SBM/SIN` | `thermals.json bus_id` | soma por barramento |
| `GUNS_SBM/SIN`, `MERL_SBM/SIN` | `non_controllable_sources.json bus_id` | soma por barramento; carga − NCS |
| `INT_SBP` | `lines.json` (origem/destino, capacidade), `constraints/line_bounds` | duas direções por linha; limites por direção |
| `CVU` | `thermals.json cost_per_mwh`, `constraints/thermal_bounds.cost_per_mwh` | CVU por estágio com sobrescrita |
| `PAT`, `EST`, patamar 0 de todas as sínteses por patamar | `stages.json` | média ponderada por horas |
| `PROBABILIDADES` e pesos das estatísticas | `stages.json policy_graph` | probabilidade de transição por nó |
| `GTER_UTE`, `QTUR/QDEF_UHE`, `VARM` (limites) | `hydros.json`/`thermals.json` (fallback de `dict/bounds`) | limites por estágio/bloco |

`dict/bounds` = `output/training/dictionaries/bounds.parquet`.

## Documentação e CI

A documentação (Sphinx, com galeria de exemplos) é publicada no GitHub Pages: <https://rjmalves.github.io/sintetizador-novomodelo/>. Para o primeiro deploy, ative o Pages em *Settings → Pages* com a origem "GitHub Actions". Para gerar localmente: `uv run sphinx-build -W -b html docs/source docs/build`.

Os workflows em `.github/workflows/` rodam lint, mypy, testes (Python 3.11 a 3.14) e a build da documentação. O envio de cobertura ao Codecov e a publicação no PyPI estão desativados (comentados nos workflows) até configurar o secret `CODECOV_TOKEN` e o environment `pypi` (trusted publishing). Os testes de integração são pulados no CI, pois dependem do caso real local.
