README.pt-BR.md

For an English version of this file, see README.md.

AltDSS/DSS C-API: Uma biblioteca com interface C para uma implementação Alternativa do OpenDSS

Veja FAQ (em inglês) para algumas notas.

Esta biblioteca expõe o motor do OpenDSS/OpenDSS-PM (v9+) através de uma interface C plana, que tenta reproduzir a maioria dos métodos COM, além de adicionar diversas funcionalidades. De fato, a maior parte do código foi inicialmente derivado dos arquivos da implementação COM, com um conjunto crescente de modificações e extensões. O DLL resultante pode ser usado diretamente ou através de módulos de interface, como o módulo DSS-Python. DSS-Python representa um módulo para linguagem Python que imita a mesma estrutura do módulo COM (como exposto via win32com ou comtypes), efetivamente nos permitindo alcançar compatibilidade multi-plataforma a nível de Python.

Através dos outros projetos hospedados como DSS-Extensions, a biblioteca DSS C-API torna possível usar o motor do OpenDSS en múltiplos sistemas operacionais (Windows, Linux, macOS) e múltiplas arquiteturas (Intel x86, x86-64, ARM32, e ARM64, incluindo os processadores M1 e M2 da Apple). A grande maioria das funcionalidades adicionadas nesta biblioteca são compartilhadas com todos os outros projetos. Caso tenha interesse numa linguagem não suportada pelos projetos abaixo, abra um novo "issue" aqui ou em https://github.com/dss-extensions/dss-extensions/issues

Caso procure integração com outras linguagens de programação:

• DSS-Python é o módulo Python multi-plataforma (Windows, Linux, MacOS) bastante compatível com o módulo COM. Veja também OpenDSSDirect.py caso não precise de compatibilidade com COM, ou deseje empregar as funcionalidades extras do módulo (inclusive em conjunto).
• OpenDSSDirect.jl é um módulo em Julia, criado por Tom Short (@tshort), que recentemente passou a empregar DSS C-API no lugar do DLL direto com a ajuda de Dheepak Krishnamurthy (@kdheepak).
• DSS Sharp para .NET/C#, disponível também como pacote NuGet. Versões mais recentes são multi-plataforma! Em breve também será possível usá-lo via COM.
• DSS MATLAB permite integração multi-plataforma (Windows, Linux, MacOS) bastante compatível com a API do módulo COM oficial, de fato contorna algumas dificuldades de COM.
• dss.hpp: biblioteca de headers para C++, hospedada também neste repositório (pasta include/). Permite usar a DSS C-API de forma confortável sem ser necessário gerenciar os detalhes como o gerenciamento de memória ou convenção de API da DSS C-API. Atualmente usa Eigen e fmt.
• Novos projetos em 2024 incluem AltDSS-Python (onde está sendo testada a API alternativa), AltDSS-Go e AltDSS-Rust.

A versão 0.14.x é baseada no OpenDSS revisão (SVN) 3723 (OpenDSS v9.8.0.1), com várias funcionalidades customizadas e extras.

Este branch pode estar em desenvolvimento. Para uma versão específica, consulte os tags do Git do repositório.

Apesar de o objetivo principal (compatibilidade com COM) ter sido alcançado, este é um sempre um trabalho em andamento. Em especial, há mudanças planejadas para a versão 0.14, que se tornará v1.0 quando considerada completa.

Ao invés de usar parâmetros numéricos como na interface DDLL oficial ("OpenDSSDirect" ou "DCSL"), cada propriedade COM foi exposta como um par de funções. Por exemplo, a propriedade kVA das cargas é exposta como:

    double Loads_Get_kva();
    void Loads_Set_kva(double Value);

Com exceção de detalhes de baixo nível como gerenciamento de memória, a maioria da documentação do módulo COM pode ser usada como referência para este projeto.

A partir da versão 0.9.8, desabilitamos a criação do opendsscmd.ini, visto que causava estranheza entre os usuários. O usuário pode configurar a frequência de base padrão usando a variável de ambiente DSS_BASE_FREQUENCY, ou simplesmente através de scripts DSS (opção recomendada por nós). Isto também significa que o datapath inicial é configurado automaticamente para o diretório de trabalho corrente.

A partir de 2019-03-05, este repositório contém todo o código fonte em linguagem Pascal necessário para compilar a DSS C-API. O código da API é mantido na pasta src/, enquanto o código principal do OpenDSS (com modificações) é mantido em Version7/ e Version8/. O código fonte da versão oficial é mantido no branch opendss-official-svn e é integrado periodicamente — veja o documento upstream branch (em inglês) para mais informações.

Mudanças recentes

Veja o registro de alterações (em inglês) para listagem detalhada.

• 2024-02-26 / versão 0.14.2: Mais correções e atualizações incrementais, especialmente na API alternativa.
• 2024-02-16 / versão 0.14.1: Correções e atualizações incrementais, especialmente na API alternativa.
• 2023-06-27 / versão 0.13.4: Correção de bugs (CapControl), melhorias incrementais.
• 2023-06-11 / versão 0.13.3: Correção de bugs em alguns dos componentes (em especial Capacitor, Reactor, UPFC).
• 2023-05-24 / versão 0.13.2: Melhorias para exportação JSON, verificação de erros, refatoração do código interno, e port de algumas mudanças menores do OpenDSS oficial.
• 2023-04-01 / versão 0.13.1: Traz apenas algumas potenciais correções relacionadas a 3 propriedades de PVSystem
• 2023-03-29 / versão 0.13.0: Várias melhorias, incluindo correção de bugs e portes de várias modificações do OpenDSS oficial; a referência para esta versão é o OpenDSS v9.6.1.1.
• 2022-07-16 / versão 0.12.1: Versão incremental, corrigindo um bug encontrado logo após o lançamento da versão 0.12.0.
• 2022-07-13 / versão 0.12.0: Grande atualização, inclui funções do mecanismo paralelo, um novo sistema de propriedades, novas extensões de API, melhor desempenho, além de outras novidades.
• 2020-12-28 / versão 0.10.7: Versão de manutenção, baseado no OpenDSS r2963. Inclui correções importantes e algumas novas funções do OpenDSS oficial.
• 2020-07-31 / versão 0.10.6: Novas extensões para a API e alterações do OpenDSS oficial portadas. Inclui algumas correções de bugs, um novo mecanismo de mensagens de erro de validação, além de novos flags de compatibilidade.
• 2020-03-03 / versão 0.10.5: Principalmente manutenção, com correção de algumas falhas. Inclui alterações portadas da versão COM e do código do OpenDSS oficial. Binários da variação da versão 8 excluídos desta versão.
• 2019-11-16 / versão 0.10.4: Apenas manutenção: Corrige acesso a arquivos com caminho longo no Linux, e inclui alterações portadas da versão COM e do código do OpenDSS oficial.
• 2019-05-22 / versão 0.10.3: Algumas correções importantes, desempenho geral bastante melhorado, novas funções estendidas, e novas funcionalidades portadas do módulo COM e da versão atual do OpenDSS.
• 2019-03-05: o repositório Git electricdss-src foi integrado diretamente em dss_capi.
• 2019-02-28 / versão 0.10.2: Implementa a função CtrlQueue_Push (faltante na versão anterior); modificações em LoadShapes para melhor desempenho e mais validação; introduz DSS_Get_AllowEditor/DSS_Set_AllowEditor para (desa)ativar chamadas ao editor externo.
• 2019-02-12 / versão 0.10.1: Verificação de erros mais ampla, introdução da função Error_Get_NumberPtr, correções e melhor tratamento em Meters.
• 2018-11-17 / versão 0.10.0: Reduz o número de operações de alocação de memória se os buffers atuais forem reutilizados, introduz o mecanismo de Resultado Global, várias extensões de API (LineGeometry, WireData, LineSpacing, CNData, TSData, Reactor) — veja o documento de uso(em inglês) e o ticket #11.
• 2018-08-10 / versão 0.9.8: Grande reorganização do código fonte, várias pequenas correções, e novos scripts de compilação.
• 2018-04-05 / versão 0.9.5: Novas funções Circuit_SetCktElement* para definir o elemento de circuito ativo.
• 2018-03-06 / versão 0.9.4: Correções para DSSProperty, inclui os textos de ajuda originais no header C, integra modificações oficiais até a revisão 2152. Esta versão introduz a primeira versão de bindings de .NET para o DLL nativo.
• 2018-02-16 / versão 0.9.3: Integra correções da interface COM na revisão SVN 2136 (iteração via First Next)
• 2018-02-12 / versão 0.9.2: Suporte experimental para OpenDSS-PM and correções da interface COM integradas (OpenDSS revisão 2134)
• 2018-02-08 / versão 0.9.1: Primeira versão pública (OpenDSS revisão 2123)

Funcionalidades faltantes e limitações

• Ainda não implementados:
  • Gráficos em geral: mecanismo de callbacks adicionado na v0.12. Para exemplos, veja DSS-Python.
  • Diakoptics e AggregateProfiles: veja #46. Planejado.

Funcionalides extras

Além da grande maioria dos métodos da interface COM, alguns dos métodos únicos da DDLL oficial (como acesso a ponteiros internos) foram expostos em formas adaptadas. Entre eles estão métodos de DYMatrix.pas, em especial GetCompressedYMatrix (veja os headers ou código fonte em Pascal para maiores detalhes).

Veja também (em inglês) o documento de diferenças conhecidas, list of known differences, para métodos e opções extras não disponíveis no OpenDSS oficial.

Há um grande número de extensões de API. Parte destas ainda necessita de documentação e exemplos.

Download

Siga aqui. Disponibilizados downloads pré-compilados para Windows, Linux e MacOS.

Como compilar?

Caso deseje compilar o DLL:

• Instale o compilador Free Pascal. Caso já tenha instalado a IDE Lazarus, você já deve ter o compilador instalado. Adicione a pasta contendo o compilador (fpc.exe) para sua variável de ambiente PATH.

• Baixe (e compile) o código, ou baixe os binários já compilados, do projeto DSS-Extensions KLUSolve de https://github.com/dss-extensions/klusolve

• Clone este repositório:

    git clone https://github.com/dss-extensions/dss_capi

• Sobreponha uma cópia do diretório lib/ da KLUSolve sobre a pasta lib/ da dss_capi.

No Windows

Se você precisa apenas do arquivo DLL, lembre-se que ele pode ser baixado na página de "Releases" no GitHub. Pode ser necessário instalar o pacote de runtime do Microsoft Visual Studio 2017. Versões de teste durante o desenvolvimento podem ser baixadas dos artefatos da compilação do GitHub Actions. Caso precisa compilar:

• Caso pretenda utilizar a DLL no Visual Studio, você precisa gerar uma biblioteca de importação. Isto pode ser feito iniciando a próxima etapa em um prompt do Visual Studio, como o "x64 Native Tools Command Prompt for VS 2017" (ou equivalente para sua versão) — você precisa apenas dos utilitários dumpbin.exe e lib.exe.

• Abra um prompt de comando na pasta dss_capi que você clonou anteriormente e execute build/build_win_x64.bat

Os arquivos de saída do processo são depositados na subpasta lib/win_x64.

Caso precise apenas dos DLLs para versões ainda não lançadas, você pode encontrar os DLLs e LIBs para x64 nos artefatos da instância do AppVeyor. Estes arquivos são criados automaticamente a cada commit neste repositório e são mantidos por 6 meses.

No Linux

• Compile o projeto principal:

    bash build/build_linux_x64.sh

No MacOS

• Compile o projeto principal:

    bash build/build_macos_x64.sh

Como usar e exemplos

Para entender os principais conceitos da DSS C-API e como ela gerencia memória, veja o documento de uso(em inglês).

Dois exemplos mínimos (sem scripts DSS, use um dos seus) estão disponíveis em examples. Após compilar a DSS C-API, adicione aos parâmetros de compilação a subpasta da pasta include apropriada (include/v7 ou include/v8), e a biblioteca da pasta lib para seu sistema. O código dos exemplos, com seus comentários traduzidos para português, também estão disponíveis abaixo.

O código fonte da DSS-Python e da OpenDSSDirect.py são exemplos de uso mais completos e avançados.

#include <stdint.h>
#include <stdio.h>
#include "dss_capi.h"

int main(void)
{
    // Para numVoltages, o primeiro `int` representa o número atual de doubles, 
    // enquant o segundo `int` representa a capacidade alocada.
    int numVoltages[2] = {0, 0}; 
    double *voltages = NULL;
    int numNodes;
    int i;

    DSS_Start(0);
    Text_Set_Command("compile master.dss");
    Solution_Solve();
    Circuit_Get_AllBusVolts(&voltages, numVoltages);

    if (numVoltages[0] == 0)
    {
        return -1;
    }
    numNodes = numVoltages[0] / 2;
    
    for (i = 0; i < numNodes; ++i)
    {
        printf("node %d: %f + j%f\n", i, voltages[2*i], voltages[2*(i + 1)]);
    }

    // As da v0.10.0, se você precisasse chamar novamente Circuit_Get_AllBusVolts,
    // precisaria também chamar
    
    // DSS_Dispose_PDouble(&voltages);

    // Desde a versão 0.10.0, mesmo se mudanças ocorreram no circuito, 
    // ainda podemos reutilizar o ponteiro anterior.

    // Se a memória alocada previamente for suficiente para o número 
    // de doubles retornado por AllBusVolts, não será necessário
    // realocar memória!
    
    Solution_Solve();
    Circuit_Get_AllBusVolts(&voltages, numVoltages);

    // Como a memória para voltages é alocada em Pascal, precisamos
    // liberá-la em Pascal, logo a chamada para DSS_Dispose_PDouble
    DSS_Dispose_PDouble(&voltages);
    
    return 0;
}

Para usar a nova API empregando resultados globais (GR), os pointeiros para os GR precisam ser inicializados.

#include <stdint.h>
#include <stdio.h>
#include "dss_capi.h"

int main(void)
{
    char*** data_PPAnsiChar;
    double** data_PDouble;
    int32_t** data_PInteger;
    int8_t** data_PByte;
    int32_t* count_PPAnsiChar;
    int32_t* count_PDouble;
    int32_t* count_PInteger;
    int32_t* count_PByte;
    
    double* voltages;
    int numNodes;
    int i;
    
    DSS_Start(0);
    DSS_GetGRPointers(
        &data_PPAnsiChar,
        &data_PDouble,
        &data_PInteger,
        &data_PByte,
        &count_PPAnsiChar,
        &count_PDouble,
        &count_PInteger,
        &count_PByte
    );
    
    Text_Set_Command("compile master.dss");
    Solution_Solve();
    Circuit_Get_AllBusVolts_GR();
    
    // O resultado da chamada para Circuit_Get_AllBusVolts agora
    // está disponível em dataPtr_PDouble[0] e countPtr_PDouble
    
    // Aqui copiamos apenas o pointeiro para conveniência,
    // a memória ainda é de responsabilidade do mecanismo GR em 
    // Pascal
    voltages = dataPtr_PDouble[0];
    
    numNodes = count_PDouble[0]/2;
    if (numNodes == 0)
    {
        return -1;
    }
    for (i = 0; i < numVoltages; ++i)
    {
        printf("node %d: %f + j%f\n", i, voltages[2*i], voltages[2*(i + 1)]);
    }
    
    return 0;
}

Testes

Atualmente, todos os testes e validação são baseados no DSS-Python. Outros projetos como OpenDSSDirect.py e OpenDSSDirect.jl contêm testes que foram importantes para encontrar e corrigir bugs.

Planos

(Ainda sendo atualizados para versão 0.12.x)

Além de correções de problemas, a funcionalidade principal desta biblioteca está pronta. Alguns pontos que pretendemos trabalhar envolvem:

• Gráficos em geral: a implementação em Python está quase completa. Veja: DSS-Extensions — Integrated plotting in Python.
• Documentação melhor e mais completa. As strings de ajuda dos arquivos de definição IDL/COM já estão reproduzidas (e adaptadas) nos headers (pasta include), mas apenas em inglês.
• Validação automatizada dos binários no Linux (comparação das saídas com a versão Windows e oficial). Atualmente a validação é rodada manualmente.
• C++: Expor a API em C++ usando namespaces para organização, métodos com overload, etc.

Outras funções desejadas podem necessitar de mudanças invasivas na base de código provavelmente serão desenvolvidas inicialmente em um repositório a parte.

Perguntas?

Caso tenha alguma pergunta, sinta à vontade para abrir um "issue" no GitHub or me contatar diretamente (pmeira arroba ieee.org). Em geral, peço que me dê alguns dias para responder.

Créditos

Este projeto é derivado do OpenDSS, desenvolvido pelo EPRI, e assim mantém a mesma base de licença. Veja LICENSE e OPENDSS_LICENSE, e também verifique cada subpasta para maiores detalhes.

Note que, já que o OpenDSS depende da biblioteca através da KLUSolve, as condições de licença da KLU (LGPL oou GPL, dependendo de como a KLU for compilada) se aplicam aos binários resultantes; veja os arquivos klusolve/COPYING, klusolve/lgpl_2_1.txt e a documentação da SuiteSparse.

Agradecimentos aos colegas do Departamento de Sistemas e Energia, da Faculdade de Engenharia Elétrica e de Computação, na Universidade Estadual de Campinas (UNICAMP), pelos comentários e ajuda geral para testar este projeto.