Pular para o conteúdo

Construção de uma API Microscópica do Aimsun Next

O módulo da API do Aimsun Next pode ser implementado como uma biblioteca dinâmica escrita em C++ ou como um arquivo de script escrito em Python (versão 3.12 para Ubuntu 24, Mac ARM e Windows) (para mais informações sobre esta linguagem de scripting, visite http://www.python.org)

Construindo uma API Micro do Aimsun Next usando C++

Uma Extensão API C++ do Aimsun Next é uma biblioteca dinâmica que contém o código desejado que interagirá com o simulador microscópico. O Aimsun Next carregará essa biblioteca dinâmica, se selecionada no Editor de Cenário, quando uma simulação for iniciada.

Para ajudar a desenvolver esta biblioteca, os seguintes arquivos são fornecidos:

  • Arquivos de Cabeçalho:
    • AKIProxie.h
    • CIProxie.h
    • ANGConProxie.h
    • AAPI_Util.h
  • Bibliotecas:
    • Versão Windows 64 bits: a2kernel26.lib e acontrol26.lib
    • Versões Linux 64 bits: liba2kernel26.so e libacontrol26.so (localizadas na pasta Aimsun Next Home)
    • Versão para Mac: liba2kernel26.0.0.dylib e libacontrol26.0.0.dylib (localizados na pasta Aimsun Next.app/Contents/PlugIns)
  • Arquivos de Exemplo:
    • AAPI.h
    • AAPI.cxx

Somente o arquivo de exemplo AAPI.cxx pode ser modificado; preencha as rotinas AAPILoad(), AAPIInit(), AAPISimulationReady(), AAPIManage(…), AAPIPostManage(…), AAPIFinish() e AAPIUnLoad() e adicione outros arquivos, se necessário.

Na versão Windows 64-bit, há um projeto de exemplo Visual C++ 2013 pronto para compilar e gerar a DLL. O projeto Visual C++ 2013 tem duas configurações disponíveis: a configuração Debugger, que gera a AAPI_D.dll por padrão, e as configurações Release, que geram a AAPI_R.dll por padrão.

Um exemplo muito simples do Módulo API do Aimsun Next é mostrado no seguinte arquivo AAPI.cxx:

#include "AKIProxie.h"
#include "CIProxie.h"
#include "ANGConProxie.h"
#include "AAPI.h"
#include <stdio.h>

// Procedures that could be modified by the user

int AAPILoad()
{
    AKIPrintString("LOAD");
    return 0;
}

int AAPIInit()
{
    AKIPrintString("\tInit");
    return 0;
}

int AAPISimulationReady()
{
    AKIPrintString("\tAAPISimulationReady");
    return 0;
}

int AAPIManage(double time, double timeSta, double timeTrans, double acycle)
{
    return 0;
}

int AAPIPostManage(double time, double timeSta, double timeTrans, double acycle)
{
    return 0;
}

int AAPIFinish()
{
    AKIPrintString("\tFinish");
    return 0;
}

int AAPIUnLoad()
{
    AKIPrintString("UNLOAD");
    return 0;
}

Criando uma API Micro do Aimsun Next usando um script Python

A Extensão da API do Aimsun Next pode ser implementada usando um script Python. Esse script Python é um arquivo ASCII com a extensão PY e pode ser criado em qualquer editor de texto.

Um script Python deve definir as dezessete funções de alto nível: AAPILoad(), AAPIInit(), AAPIManage(...), AAPIPostManage(…), AAPIFinish(), AAPIUnLoad(), AAPIPreRouteChoiceCalculation(...), AAPIVehicleStartParking(...), AAPIActionActivated(...), AAPIActionDeactivated(...), AAPIEnterVehicle(...), AAPIExitVehicle(...), AAPIEnterPedestrian(...), AAPIExitPedestrian(...), AAPIEnterVehicleSection(...) e AAPIExitVehicleSection(...). Todas as funções de alto nível devem estar definidas no arquivo para que ele seja executado com sucesso.

Um exemplo muito simples de Aimsun Next API Module com o seguinte conteúdo é fornecido no arquivo sample.py:

from AAPI import *

def AAPILoad():
    AKIPrintString( "AAPILoad" )
    return 0

def AAPIInit():
    AKIPrintString( "AAPIInit" )
    return 0

def AAPISimulationReady():
    AKIPrintString( "AAPISimulationReady" )
    return 0

def AAPIManage(time, timeSta, timeTrans, acycle):
    AKIPrintString( "AAPIManage" )
    return 0

def AAPIPostManage(time, timeSta, timeTrans, acycle):
    AKIPrintString( "AAPIPostManage" )
    return 0

def AAPIFinish():
    AKIPrintString( "AAPIFinish" )
    return 0

def AAPIUnLoad():
    AKIPrintString( "AAPIUnLoad" )
    return 0

def AAPIPreRouteChoiceCalculation(time, timeSta):
    AKIPrintString( "AAPIPreRouteChoiceCalculation" )
    return 0

def AAPIVehicleStartParking(idveh, idsection, time):
    return 0

def AAPIActionActivated(idAction):
    return 0

def AAPIActionDeactivated(idAction):
    return 0

def AAPIEnterVehicle(idveh, idsection):
    return 0

def AAPIExitVehicle(idveh, idsection):
    return 0

def AAPIEnterPedestrian(idPedestrian, originCentroid):
    return 0

def AAPIExitPedestrian(idPedestrian, destinationCentroid):
    return 0

def AAPIEnterVehicleSection(idveh, idsection, atime):
    return 0

def AAPIExitVehicleSection(idveh, idsection, atime):
    return 0

Há algumas funções que precisam passar parâmetros por referência. Em Python não é possível passar parâmetros por referência, mas há algumas funções extras para permitir isso.

No código a seguir há um exemplo de como funções com parâmetros por referência podem ser usadas em um script Python. A função calcula a duração do ciclo de um cruzamento.

def getCycleTime(junctionId , numPhases, t):
    cycle = 0
    pdur = doublep()
    pcmax = doublep()
    pcmin = doublep()
    for i in range(1, numPhases):
    ECIGetDurationsPhase(junctionId, i, t, pdur, pcmax, pcmin)
    cycle = cycle + pdur.value()
    del pdur
    del pcmax
    del pcmin
    return cycle

Criar uma Aplicação da API Mesoscópica do Aimsun Next

O módulo da API do Aimsun Next pode ser implementado como uma biblioteca dinâmica escrita em C++ ou como um arquivo de script escrito em Python (versão 3.12 para Ubuntu 24, Mac ARM e Windows) (para mais informações sobre esta linguagem de scripting, visite http://www.python.org)

Construindo uma API Meso do Aimsun Next usando C++

Uma Extensão Next da API C++ do Aimsun Next é uma biblioteca dinâmica que contém o código desejado que interagirá com o simulador mesoscópico. O Aimsun Next carregará essa biblioteca dinâmica, se selecionada no Editor de Cenários, quando uma simulação for iniciada.

Para desenvolver esta biblioteca, os seguintes arquivos são fornecidos:

  • Arquivos de Cabeçalho:
    • AMesoAPIHelper.h
    • CIProxie.h
    • AAPI_Util.h
  • Bibliotecas:
    • Versão Windows 64 bits: aimsunmesoplugin26.lib, acontrol26.lib
  • Arquivos de Exemplo:
    • AAPI.h
    • AAPI.cxx

Somente o arquivo de exemplo AAPI.cxx deve ser modificado para preencher as rotinas MesoAPILoad(…), MesoAPIInit(…), MesoAPISimulationReady(…), MesoAPIFinish(…), MesoAPIUnLoad(…), MesoAPINewVehicleSystem(…), MesoAPINewVehicleNetwork(…),MesoAPIEnterVehicleSection(…) e MesoAPIExitVehicleSection(…), MesoAPIPostManageControl(…), MesoAPIPreManageRouteChoice(…), MesoAPIActionActivated(…), MesoAPIActionDeactivated(…) e outros arquivos incluídos, se necessário.

Na versão Windows 64-bit, há um projeto de exemplo Visual C++ 2013 pronto para compilar e gerar a DLL. O projeto Visual C++ 2013 tem duas configurações disponíveis: a configuração Debugger, que gera a AAPI_D.dll por padrão, e as configurações Release, que geram a AAPI_R.dll por padrão.

Um exemplo muito simples do módulo da API do Aimsun Next poderia ser definido pelo seguinte conteúdo de AAPI.cxx:

#include "AMesoAPIHelper.h"


#include "AAPI.h"
#include <stdio.h>

// Procedures could be modified by the user

int MesoAPILoad()
{
    return 0;
}

int MesoAPIUnLoad(void * handler)
{
    AMesoPrintString(handler, "UnLOAD");
    return 0;
}

int MesoAPIInit(void * handler, int iterationNumber, bool statisticsAllowed)
{
    AMesoPrintString(handler, "\tInit");
    return 0;
}

int MesoAPISimulationReady(void * handler)
{
    AMesoPrintString(handler, "\tSimulation Ready");
    return 0;
}

int MesoAPIFinish(void * handler)
{
    AMesoPrintString(handler, "\tFinish");
    return 0;
}

int MesoAPINewVehicleSystem(void * simhandler, void * vehhandler)
{
    return 0;

}

int MesoAPINewVehicleNetwork(void * simhandler, void * vehhandler)
{
    return 0;
}

int MesoAPIFinishVehicleNetwork(void * simhandler, void * vehhandler, bool normalOut)
{
    //AMesoPrintString(simhandler, "\tFinish system");
    return 0;
}

int MesoAPIEnterVehicleSection(void * simhandler, void * vehhandler, int fromSection, int toSection)
{
    AMesoVehicleInfo vehInf = AMesoGetVehicleInfo(simhandler, vehhandler);
    return 0;
}

int MesoAPIExitVehicleSection(void * simhandler, void * vehhandler, int section)
{
    AMesoVehicleInfo vehInf = AMesoGetVehicleInfo(simhandler, vehhandler);
    return 0;
}

int MesoAPIVehicleReadyForSection(void * simhandler, void * vehhandler, int section)
{
    AMesoVehicleInfo vehInf = AMesoGetVehicleInfo(simhandler, vehhandler);
    return 0;
}

int MesoAPIPostManageControl(void * simhandler)
{
    std::cout << "Post Manage Control" << '\n';
    return 0;
}

int MesoAPIPreManageRouteChoice(void * simhandler)
{
    std::cout << "Pre Manage Route Choice" << '\n';
    return 0;
}

int MesoAPIActionActivated(void* simhandler, unsigned int idAction)
{
    const std::string str = "Activating action with id " + std::to_string(idAction);
    AMesoPrintString(simhandler, str.data());
    return 0
}

int MesoAPIActionDeactivated(void* simhandler, unsigned int idAction)
{
    const std::string str = "Deactivating action with id " + std::to_string(idAction);
    AMesoPrintString(simhandler, str.data());
    return 0
}

Criando uma API Meso do Aimsun Next usando um script Python

A Extensão da API do Aimsun Next pode ser implementada usando um script Python. Esse script Python é um arquivo ASCII com a extensão PY e pode ser criado em qualquer editor de texto.

Um script Python deve ser escrito para definir as funções de alto nível: MesoAPILoad(…), MesoAPIInit(…), MesoAPISimulationReady(…), MesoAPIUnLoad(…),MesoAPIFinish(…),MesoAPINewVehicleSystem(…), MesoAPINewVehicleNetwork(…),MesoAPIFinishVehicleNetwork(…), MesoAPIEnterVehicleSection(…), MesoAPIExitVehicleSection(…), MesoAPIPostManageControl(…), MesoAPIPreManageRouteChoice(…), MesoAPIActionActivated(…) e MesoAPIActionDeactivated(…).

Um exemplo muito simples de Aimsun Next API Module com o seguinte conteúdo é fornecido no arquivo sample.py:

from AMesoAPI import *

def MesoAPILoad():
    print("AMesoAPILoad" )
    return 0

def MesoAPIInit(simhandler, iterationNumber, statisticsActivated):
    AMesoPrintString( simhandler, "AMesoAPIInit" )
    return 0

def MesoAPISimulationReady(simhandler):
    AMesoPrintString( simhandler, "AMesoSimulationReady" )
    return 0

def MesoAPIUnLoad(simhandler):
    AMesoPrintString(simhandler, "AMesoUnAPILoad" )
    return 0

def MesoAPIFinish(simhandler):
    AMesoPrintString(simhandler, "AMesoFinish" )
    return 0

def MesoAPINewVehicleSystem(simhandler, vehhandler):
    vehInf = AMesoGetVehicleInfo(simhandler, vehhandler)
    AMesoPrintString(simhandler, "Veh system id %d"%vehInf.id)
    return 0

def MesoAPINewVehicleNetwork(simhandler, vehhandler):
    vehInf = AMesoGetVehicleInfo(simhandler, vehhandler)
    AMesoPrintString(simhandler, "Veh network id %d"%vehInf.id)
    return 0

def MesoAPIFinishVehicleNetwork(simhandler, vehhandler, normalOut):
    vehInf = AMesoGetVehicleInfo(simhandler, vehhandler)
    AMesoPrintString(simhandler, "Veh finish id %d"%vehInf.id)
    return 0


def MesoAPIEnterVehicleSection(simhandler, vehhandler, fromSection, toSection):
    vehInf = AMesoGetVehicleInfo(simhandler, vehhandler)
    AMesoPrintString(simhandler, "Veh enter id %d %f %d %d"%(vehInf.id, AMesoGetCurrentTime(simhandler), fromSection, toSection))
    return 0

def MesoAPIExitVehicleSection(simhandler, vehhandler, section):
    vehInf = AMesoGetVehicleInfo(simhandler, vehhandler)
    AMesoPrintString(simhandler, "Veh exit id %d %f %d"%(vehInf.id, AMesoGetCurrentTime(simhandler), section))
    return 0

def MesoAPIVehicleReadyForSection(simhandler, vehhandler, section):
    vehInf = AMesoGetVehicleInfo(simhandler, vehhandler)
    AMesoPrintString(simhandler, "Veh ready for section id %d %f %d"%(vehInf.id, AMesoGetCurrentTime(simhandler), section))
    return 0

def MesoAPIPostManageControl(simhandler):
    return 0

def MesoAPIPreManageRouteChoice(simhandler):
    return 0

def MesoAPIVehicleAtDestination(simhandler, vehhandler, nodeid):
    return 0

def MesoAPIVehicleAtPTStop(simhandler, vehhandler, section, transitstop):
    return 0

def MesoAPIActionActivated(simhandler, idAction):
    return 0

def MesoAPIActionDeactivated(simhandler, idAction):
    return 0

Há algumas funções que precisam passar parâmetros por referência. Em Python não é possível passar parâmetros por referência, mas há algumas funções extras que permitem isso.

No código a seguir há um exemplo de como funções com parâmetros por referência podem ser usadas em um script Python. A função calcula a duração do ciclo de um cruzamento.

def getCycleTime(junctionId , numPhases, t):
    cycle = 0
    pdur = doublep()
    pcmax = doublep()
    pcmin = doublep()
    for i in range(1, numPhases):
        ECIGetDurationsPhase(junctionId, i, t, pdur, pcmax, pcmin)
        cycle = cycle + pdur.value()
    del pdur
    del pcmax
    del pcmin
    return cycle

Como habilitar e carregar uma Extensão da API do Aimsun Next a partir do Aimsun Next

Para habilitar uma Aimsun Next API Extension definida pelo usuário, adicione-a na definição do Scenario. Clicando no Scenario, selecionando a pasta da aba API quando a seguinte caixa de diálogo aparecer:


Caixa de Diálogo de Extensões

Nesta caixa de diálogo, use o botão Add ou o botão Remove para carregar ou descarregar um conjunto de Extensões do Aimsun Next (bibliotecas dinâmicas ou scripts Python).