FAQ e Troubleshooting¶

Esta página reúne as dúvidas e problemas mais frequentes relatados pelos usuários do sintetizador-newave, organizados por tema. Para uma introdução ao uso básico da ferramenta, consulte o Tutorial. Para instruções de instalação, consulte Instalação.

Instalação ¶

Qual é a versão mínima de Python necessária?¶

O sintetizador-newave requer Python >= 3.11. Versões anteriores não são suportadas e não recebem correções. O suporte a Python 3.8–3.10 foi descontinuado progressivamente até a versão v2.4.0 da aplicação.

Para verificar a versão do Python disponível no seu ambiente:

python --version

Qual versão do `inewave` é necessária?¶

A dependência inewave deve estar na versão >= 1.9.2. Versões anteriores do inewave são incompatíveis com a série v2.x do sintetizador-newave e causarão erros de importação ou de leitura de arquivos.

Ao instalar com pip, a versão correta é resolvida automaticamente:

pip install git+https://github.com/rjmalves/sintetizador-newave

Se você mantém o inewave instalado separadamente, atualize-o antes de atualizar o sintetizador-newave:

pip install --upgrade inewave

Posso instalar com `uv` em vez de `pip`?¶

Sim. O projeto usa uv como gerenciador de ambiente recomendado para desenvolvimento. Para instalar dependências e executar comandos em um ambiente gerenciado pelo uv:

uv run sintetizador-newave --help

Consulte Instalação para o procedimento completo de instalação via pip e via repositório Git.

Uso Básico ¶

Quais são os comandos disponíveis?¶

O sintetizador-newave é uma ferramenta de linha de comando com os seguintes subcomandos:

Usage: sintetizador-newave [OPTIONS] COMMAND [ARGS]...

  Aplicação para realizar a síntese de informações em um modelo unificado de
  dados para o NEWAVE.

Options:
  --help  Show this message and exit.

Commands:
  completa  Realiza a síntese completa do NEWAVE.
  cenarios  Realiza a síntese dos dados de cenários do NEWAVE.
  execucao  Realiza a síntese dos dados da execução do NEWAVE.
  politica  Realiza a síntese dos dados da política do NEWAVE (NWLISTCF).
  operacao  Realiza a síntese dos dados da operação do NEWAVE (NWLISTOP).
  sistema   Realiza a síntese dos dados do sistema do NEWAVE.
  limpeza   Realiza a limpeza dos dados resultantes de uma síntese.

Para ver as opções de um subcomando específico, use --help após o nome do comando. Consulte o Tutorial para exemplos de uso detalhados.

Como sintetizar apenas algumas variáveis em vez de todas?¶

Todos os subcomandos de síntese aceitam argumentos posicionais com os nomes das variáveis desejadas. Por exemplo, para sintetizar apenas o Custo Marginal de Operação por submercado e a Energia Armazenada no SIN:

sintetizador-newave operacao CMO_SBM EARMF_SIN

Se nenhum argumento for passado, todas as variáveis disponíveis para aquele subcomando são sintetizadas.

Posso usar curingas (wildcards) para selecionar variáveis?¶

Sim. Desde a versão v2.0.0 é possível usar o caractere * para selecionar múltiplas variáveis com base em um prefixo ou sufixo comum. Por exemplo, para sintetizar todas as variáveis de energia armazenada:

sintetizador-newave operacao "EARM*"

Nota

Use aspas ao redor do argumento com * para evitar que o shell expanda o curinga antes de passá-lo ao programa.

Como executar o sintetizador a partir de um diretório diferente do caso?¶

Por padrão, os subcomandos de síntese (operacao, cenarios, sistema, execucao, politica, completa) lêem os arquivos do diretório de trabalho atual (os.curdir). Para executar a síntese apontando para um diretório diferente, defina a variável de ambiente APP_BASEDIR antes de chamar o comando limpeza.

Aviso

A variável de ambiente APP_BASEDIR é obrigatória apenas para o comando limpeza. Os demais comandos sempre utilizam o diretório de trabalho corrente como diretório base. Para executar a síntese sobre um caso em outro diretório, mude para esse diretório antes de executar o comando.

cd /caminho/para/o/caso
sintetizador-newave operacao --processadores 4

Formato de Saída ¶

Qual é o formato padrão dos arquivos de saída?¶

O formato padrão é PARQUET, um formato colunar eficiente para armazenamento de dados tabulares, amplamente utilizado em aplicações de big data. Os arquivos são gerados com compressão Snappy (padrão do Apache Arrow) e extensão .parquet.

Nota

A partir da versão v2.0.0, o formato PARQUET não utiliza mais compressão gzip automática. A extensão dos arquivos mudou de .parquet.gz para .parquet.

Os arquivos são gravados no subdiretório sintese/ dentro do diretório base do caso.

Como alterar o formato de saída para CSV?¶

Use o argumento --formato seguido do nome do formato desejado. Os valores aceitos são PARQUET (padrão) e CSV:

sintetizador-newave execucao --formato CSV
sintetizador-newave operacao --formato CSV --processadores 4

Os arquivos CSV são gerados sem índice e com codificação UTF-8.

Por que as colunas têm nomes diferentes da versão 1.x?¶

A partir da versão v2.0.0, todos os nomes de colunas dos DataFrames de síntese foram padronizados para snake_case. Exemplos de mudanças:

Usina → usina / codigo_usina
Submercado → submercado / codigo_submercado
Estagio → estagio

Além disso, as entidades passaram a ser indexadas pelos seus códigos numéricos ao invés de nomes nos DataFrames das sínteses de operação e cenários. Por exemplo, a coluna usina foi substituída por codigo_usina. O mapeamento entre códigos e nomes está disponível na síntese do sistema (sistema).

Como ler os arquivos Parquet gerados?¶

Os arquivos .parquet gerados são compatíveis com o Apache Arrow e podem ser lidos com Polars, pandas ou PySpark:

# Usando Polars
import polars as pl
df = pl.read_parquet("sintese/CMO_SBM.parquet")

# Usando pandas
import pandas as pd
df = pd.read_parquet("sintese/CMO_SBM.parquet")

As colunas de data e hora são armazenadas em fuso horário UTC para garantir compatibilidade na leitura em diferentes implementações do Arrow.

Paralelismo ¶

Quais comandos suportam o argumento `--processadores`?¶

Os subcomandos que suportam paralelização são operacao, cenarios e completa. Os subcomandos sistema, execucao e politica não aceitam --processadores e sempre executam de forma sequencial.

# Suportado
sintetizador-newave operacao --processadores 8
sintetizador-newave cenarios --processadores 8
sintetizador-newave completa --processadores 24

# NÃO suportado (o argumento será ignorado ou causará erro)
sintetizador-newave sistema --processadores 4

Quantos processadores devo usar?¶

O valor ideal depende do hardware disponível e do número de variáveis a sintetizar. Como referência:

Para máquinas com 4 a 8 núcleos, valores de --processadores entre 4 e 8 costumam oferecer bom desempenho.
Para servidores com muitos núcleos, valores maiores (por exemplo, 16 ou 24) podem ser usados com completa.
Valores maiores que o número de núcleos físicos disponíveis tendem a não trazer ganho adicional e podem aumentar a contenção de I/O.

O padrão é --processadores 1 (execução sequencial) quando o argumento é omitido.

O paralelismo aplica-se a todas as variáveis?¶

Sim. Desde a versão v1.1.0, o paralelismo está habilitado para todas as variáveis das sínteses de operação e cenários, e não apenas para variáveis relacionadas a UHEs. A síntese completa aplica o paralelismo a todas as categorias de síntese que suportam essa funcionalidade.

Erros Comuns ¶

Erro: arquivos de entrada não são encontrados ¶

O erro mais comum ocorre quando o sintetizador-newave é executado a partir de um diretório que não contém os arquivos de saída do modelo NEWAVE. A aplicação lê os arquivos do diretório de trabalho corrente.

ERROR: Arquivo 'nwlistop.rel' não encontrado.

Solução: mude para o diretório do caso antes de executar o sintetizador:

cd /caminho/para/o/caso/newave
sintetizador-newave operacao

Erro de incompatibilidade com versões do NEWAVE anteriores a 29.4 ¶

A partir da versão v2.1.0, o sintetizador-newave adicionou suporte completo ao NEWAVE >= 29.4, que renomeou diversos arquivos de saída. Ao utilizar uma versão do NEWAVE anterior a 29.4 com uma versão recente do sintetizador, pode ocorrer falha na leitura de arquivos renomeados.

Aviso

Para garantir compatibilidade total, recomenda-se utilizar o NEWAVE na versão >= 29.4 com o sintetizador-newave na versão >= 2.1.0.

Se necessário utilizar uma versão mais antiga do NEWAVE, verifique se o sintetizador-newave na versão v1.2.0 (série de compatibilidade v1-compat) atende às suas necessidades.

Erro de incompatibilidade de formato após atualização para v2.0 ¶

A versão v2.0.0 introduziu mudanças incompatíveis no formato dos arquivos de saída: nomes de colunas em snake_case, indexação por códigos e novos arquivos de metadados e estatísticas. Scripts e pipelines construídos para a série v1.x precisam ser atualizados.

Principais mudanças que podem causar erros em código legado:

Colunas renomeadas para snake_case (ex.: codigo_usina, estagio)
Novos arquivos METADADOS_*.parquet e ESTATISTICAS_*.parquet são gerados automaticamente
A coluna patamar substitui a separação anterior por sufixo _EST / _PAT; patamar = 0 representa o valor médio do estágio

Consulte o CHANGELOG.md do repositório para a lista completa de mudanças dessa versão.

A síntese termina sem erros mas os arquivos de saída não aparecem ¶

Os arquivos de saída são gravados no subdiretório sintese/ dentro do diretório de trabalho corrente (ou no caminho indicado pela variável de ambiente DIRETORIO_SINTESE). Verifique se esse subdiretório existe e se há permissão de escrita:

ls -la sintese/

Se o diretório sintese/ não existir, ele é criado automaticamente pela aplicação na primeira execução. Se houver erro de permissão, ajuste as permissões do diretório pai:

chmod u+w /caminho/para/o/caso