Arquitetura da API

A solução Aimsun Next

A abordagem adotada no Aimsun Next é considerar um Aplicativo Telemático Avançado a ser testado usando o modelo como uma aplicação externa que pode se comunicar com a simulação.

Usando as funções da API do Aimsun Next, os dados da rede simulada são transferidos para a aplicação externa; a aplicação aplica seus próprios algoritmos para avaliar a situação na simulação e responde com ações dinâmicas apropriadas a serem implementadas na simulação. O processo de troca de informações entre a simulação e a aplicação externa é mostrado abaixo

O modelo da rede viária emula o processo de detecção. Então, através de um conjunto de funções, ele fornece à aplicação externa os "Dados de Detecção da Simulação" necessários (por exemplo, fluxo, ocupação, etc.). A aplicação externa usa esses dados para avaliar suas políticas de controle e decide quais ações de controle e/ou gestão devem ser aplicadas na rede viária. Finalmente, a aplicação externa envia as respectivas atuações (por exemplo, mudar o estado do semáforo, a duração da fase, exibir uma mensagem em um VMS, etc.) para o modelo de simulação, que emula sua operação através dos componentes correspondentes do modelo, como semáforos, VMSs e sinais de controle de rampas.

Outro uso da API do Aimsun Next é acessar dados simulados detalhados de veículos e transmiti-los para um modelo desenvolvido pelo usuário (por exemplo, consumo de combustível e emissões de poluentes), para acompanhar um veículo guiado através da rede por um sistema de orientação de veículos externo, ou para simular as atividades de veículos, como carros flutuantes.

Implementação

Introdução à API do Aimsun Next

O módulo da API do Aimsun Next está logicamente posicionado entre o modelo de simulação e a aplicação externa. Internamente, dentro do Aimsun Next, a API é capaz de se comunicar com o módulo de simulação, externamente, com a aplicação externa. O mecanismo de comunicação entre as funções da API e a aplicação é decidido pelo analista que implementa a conexão e pode variar desde programação direta (ou seja, o código que usa a API é a aplicação externa) até um protocolo de comunicação em rede emulando o hardware de comunicações de rua e onde a aplicação externa é um sistema de produção amplamente não modificado.

API de Microsimulação do Aimsun Next

O módulo da API do Aimsun Next possui seis funções de alto nível que se comunicam entre o Módulo da API do Aimsun Next e o modelo de simulação. Essas são: AAPILoad, AAPIInit, AAPISimulationReady, AAPIManage, AAPIPostManage, AAPIFinish, AAPIUnLoad.

Ele também possui seis funções adicionais que são chamadas quando certos eventos ocorrem. Elas são: AAPIEnterVehicle e AAPIExitVehicle, AAPIEnterVehicleSection, AAPIExitVehicleSection, AAPIPreRouteChoiceCalculation e AAPIVehicleStartParking.

Gestão da Simulação

Funções de Inicialização

• AAPILoad ()

  Chamado quando o módulo é carregado pelo Aimsun Next.

• AAPIInit ()

  Chamado quando o Aimsun Next inicia a simulação e pode ser usado para inicializar o módulo.

• AAPISimulationReady ()

  Chamado quando o Aimsun Next inicializou todos os veículos e eles estão prontos para começar a se mover.

Funções de Intervalo de Tempo

Existem duas funções de simulação chamadas em cada intervalo de tempo AAPIManage é chamada antes que o simulador execute quaisquer ações, o simulador então faz seus cálculos e atualiza veículos e semáforos. Finalmente, no final do intervalo de tempo, AAPIPostManage é chamado.

Assim, quando o intervalo de tempo da simulação é avaliado, as ações realizadas em AAPIManage são incluídas e quando AAPIPostManage é chamado, as ações realizadas em AAPIManage e no intervalo de tempo são incluídas. Ações feitas em AAPIPostManage de um passo de simulação serão então consideradas no próximo passo de simulação. Em geral, é preferível fazer alterações para ITS ou sinalizações em AAPIManage para que sejam consideradas pelos veículos naquele intervalo de tempo e fazer alterações para os veículos em AAPIPostManage para que os veículos ao redor estejam atualizados com suas próprias ações.

• AAPIManage (double time, double timeSta, double timeTrans, double cycle)

  Chamado em cada passo de simulação no início do ciclo, e pode ser usado para solicitar medidas de detector, informações de veículos e interagir com interseções, metragens e VMS a fim de implementar a política de controle e gestão. Esta função aceita quatro parâmetros relacionados ao tempo:

  - *time*: Tempo absoluto da simulação em segundos. No início da simulação (início da fase de aquecimento, se houver), assume o valor 0.
  - *timeSta*: Tempo da simulação no período estacionário (começo do Tempo Inicial Simulado), em segundos desde a meia-noite. O valor de timeSta é inválido durante o período de aquecimento (onde sempre retornará ao início do período estacionário).
  - *timeTrans*: Duração do período de aquecimento, em segundos.
  - *cycle*: Duração de cada passo de simulação em segundos.
  

  Exemplo:

  Iniciamos uma simulação às 07:00, com 5 minutos de período de aquecimento e simulamos um minuto com 1 segundo como o passo de simulação. Tomando esses valores, os parâmetros serão:

  - time = 5*60 + 60 = 360.0
  - timeSta = 7*3600+60 = 25260.0
  - timeTrans = 5*60 = 300.0
  - cycle = 1.0
  

• AAPIPostManage (double time, double timeSta, double timeTrans, double cycle)

  Chamado em cada passo de simulação no final do ciclo, e pode ser usado para solicitar medidas de detector, informações de veículos e interagir com interseções, metragens e VMS para implementar a política de controle e gestão. Esta função aceita quatro parâmetros relacionados ao tempo:

  • time: Tempo absoluto da simulação em segundos. No início da simulação (início da fase de aquecimento, se houver), assume o valor 0.
  • timeSta: Tempo da simulação no período estacionário (começo do Tempo Inicial Simulado), em segundos desde a meia-noite. O valor de timeSta é inválido durante o período de aquecimento (onde sempre retornará ao início do período estacionário).
  • timeTrans: Duração do período de aquecimento, em segundos.
  • cycle: Duração de cada passo de simulação em segundos.

Funções de Término

• AAPIFinish ()

  Chamado quando o Aimsun Next termina a simulação e pode ser usado para encerrar as operações do módulo, escrever informações de resumo, fechar arquivos, etc.

• AAPIUnLoad ()

  Chamado quando o módulo é descarregado pelo Aimsun Next.

A figura a seguir mostra graficamente como o Aimsun Next e o Módulo da API interagem.

Eventos de Simulação

• AAPIEnterVehicle (int idveh, int idsection)

  Chamado quando um novo veículo entra no sistema, ou seja, quando o veículo entra na sua primeira seção, não quando ele entra em uma fila virtual, se uma estiver presente. Esta função aceita dois parâmetros:

  • idveh: Identificador do novo veículo que entra na rede.
  • idsection: Identificador da seção onde o veículo entra na rede.

• AAPIExitVehicle (int idveh, int idsection)

  Chamado quando um veículo sai da rede. Esta função aceita dois parâmetros:

  • idveh: Identificador do veículo que sai da rede.
  • idsection: Identificador da seção onde o veículo sai da rede.

• AAPIEnterVehicleSection (int idveh, int idsection, double atime)

  Chamado quando um veículo entra em uma nova seção. Esta função aceita três parâmetros:

  - *idveh*: Identificador do veículo.
  - *idsection*: Identificador da seção que o veículo está entrando.
  - *atime*: Tempo absoluto da simulação quando o veículo entra na seção. No início da simulação (início da fase de aquecimento, se houver), assume o valor 0.
  

• AAPIExitVehicleSection (int idveh, int idsection, double atime)

  Chamado quando um veículo sai de uma seção. Esta função recebe dois parâmetros:

  - *idveh*: Identificador do veículo.
  - *idsection*: Identificador da seção que o veículo está saindo.
  - *atime*: Tempo absoluto da simulação quando o veículo sai da seção. No início da simulação (início da fase de aquecimento, se houver), assume o valor 0.
  

• AAPIEnterPedestrian (int idPedestrian, int originCentroid)

  Chamado quando um novo pedestre entra no sistema, ou seja, quando o pedestre entra pela sua entrada. Esta função aceita dois parâmetros:

  - *idPedestrian*: Identificador do novo pedestre que entra na rede.
  - *originCentroid*: Identificador da entrada do pedestre onde o pedestre entra na rede.
  

• AAPIExitPedestrian (int idPedestrian, int destinationCentroid)

  Chamado quando um pedestre sai da rede. Esta função aceita dois parâmetros:

  - *idPedestrian*: Identificador do pedestre que sai da rede.
  - *destinationCentroid*: Identificador da saída do pedestre onde o pedestre sai da rede.
  

• AAPIPreRouteChoiceCalculation (double time, double timeSta)

  Chamado logo antes de um novo ciclo de cálculo de escolha de rota estar prestes a começar. Pode ser usado para modificar os custos das seções e desvios para afetar o cálculo da escolha de rota. Esta função aceita dois parâmetros em relação ao tempo:

  - *time*: Tempo absoluto da simulação em segundos. No início da simulação (início da fase de aquecimento, se houver), assume o valor 0.
  - *timeSta*: Tempo da simulação no período estacionário (começo do Tempo Inicial Simulado), em segundos desde a meia-noite. O valor de timeSta é inválido durante o período de aquecimento (onde sempre retornará ao início do período estacionário).
  

• AAPIVehicleStartParking (int idveh, int idsection, double time)

  Chamado quando um veículo inicia uma manobra de estacionamento.
  
      - *idveh*: Identificador do veículo.
      - *idsection*: Identificador da seção onde o veículo está fazendo o estacionamento.
      - *time*: Tempo atual da simulação.
  

• char* AAPIInternalName ()

  Retorna o nome interno único da API. É chamado ao registrar APIs antes da simulação.

API Mesoscópica do Aimsun Next

O módulo da API Mesoscópica do Aimsun Next possui quatro funções de alto nível que se comunicam entre o Módulo da API e o modelo de simulação. Essas são: MesoAPILoad, MesoAPIUnLoad, MesoAPIInit, MesoAPIFinish.

Ele também possui cinco funções adicionais que são chamadas quando certos eventos ocorrem. Elas são: MesoAPINewVehicleSystem, MesoAPINewVehicleNetwork, MesoAPIFinishVehicleNetwork, MesoAPIEnterVehicleSection, MesoAPIExitVehicleSection e MesoAPIPostManageControl.

Em quase todas as funções da API mesoscópica, há parâmetros simhandler e vehhandler, que são usados por razões internas e para alcançar melhores resultados de desempenho. Simhandler representa o simulador interno enquanto o vehhandler representa o veículo.

Gestão da Simulação

• MesoAPILoad ():

  Chamado quando o módulo é carregado pelo Aimsun Next. O simulador não está disponível neste ponto.

• MesoAPIInit (void * simhandler, int iterationNumber, bool statisticsAllowed)

  Chamado quando o Aimsun Next inicia a simulação e pode ser usado para inicializar o módulo. É chamado no início de cada iteração em uma simulação DUE.

  - *iterationNumber*: O número da iteração. Em uma simulação única, este parâmetro não é utilizado, mas na simulação DUE, iterationNumber vai de 1 ao número de iterações.
  - *statisticsAllowed*: verdadeiro se estatísticas são permitidas nesta iteração ou simulação ao executar uma simulação única.
  

• MesoAPISimulationReady (void * simhandler)

  Chamado quando o Aimsun Next inicia a simulação e tudo está pronto para que os veículos comecem a se mover. É chamado no início de cada iteração em uma simulação DUE.

• MesoAPIUnLoad (void * simhandler)

  Chamado quando o módulo é descarregado pelo Aimsun Next.

• MesoAPIFinish(void * simhandler)

  Chamado quando o Aimsun Next termina a simulação. Ao executar uma DUE, esta função é chamada no final de cada iteração.

A figura a seguir mostra como o Aimsun Next e o Módulo da API interagem.

Eventos de Simulação

• MesoAPINewVehicleSystem(void * simhandler, void * vehhandler)

  Chamado quando um novo veículo é gerado, ele pode entrar na rede ou entrar em uma fila virtual. Esta função aceita dois parâmetros:

  - *simhandler*: Simulador.
  - *vehhandler*: O veículo gerado.
  

• MesoAPINewVehicleNetwork (void * simhandler, void * vehhandler)

  Chamado quando um novo veículo entra na rede. Este é o momento em que deixa a fila virtual se estava esperando para entrar na rede:

  - *simhandler*: Simulador.
  - *vehhandler*: O veículo gerado.
  

• MesoAPIEnterVehicleSection (void * simhandler, void * vehhandler, int fromSection, int toSection)

  Chamado quando um novo veículo entra em uma nova seção. Esta função aceita quatro parâmetros:

  - *simhandler*: Simulador.
  - *vehhandler*: O veículo.
  - *fromSection*: Identificador da seção origem
  - *toSection*: Identificador da seção que está entrando.
  

• MesoAPIExitVehicleSection (void * simhandler, void * vehhandler, int section)

  Chamado quando um novo veículo sai da seção. Esta função aceita três parâmetros:

  - *simhandler*: Simulador.
  - *vehhandler*: O veículo.
  - *section*: Identificador da seção que está saindo
  

• MesoAPIVehicleReadyForSection (void * simhandler, void * vehhandler, int section)

  Chamado quando um novo veículo está pronto para sair da seção. O veículo é o primeiro na fila. Esta função aceita três parâmetros:

  - *simhandler*: Simulador.
  - *vehhandler*: O veículo.
  - *section*: Identificador da próxima seção
  

• MesoAPIPostManageControl (void * simhandler)

  Chamado toda vez que há uma mudança no controle. Esta função é chamada apenas quando o plano de controle mestre tem controladores adaptativos. Esta função aceita um parâmetro:

  - *simhandler*: O simulador.
  

• MesoAPIPreManageRouteChoice (void * simhandler)

  Chamado toda vez que os algoritmos de escolha de rota são executados. Esta função recebe um parâmetro:

  - *simhandler*: O simulador.
  

• MesoAPINewStatisticalInterval (void * simhandler)

  Chamado toda vez que o ciclo de estatísticas começa. Esta função recebe um parâmetro:

  - *simhandler*: O simulador.
  

• MesoAPINewDetectorStatisticalInterval (void * simhandler)

Chamado toda vez que o intervalo de estatísticas de detecção começa. Esta função recebe um parâmetro:

    - *simhandler*: O simulador.

• MesoAPIVehicleAtDestination (void * simhandler, void *vehhandler, int nodeid)

  Chamado toda vez que o veículo chega ao seu destino:

  - *simhandler*: O simulador.
  - *vehiclehandler*: O veículo
  - *nodeid*: Identificador do nó
  

• MesoAPIVehicleAtPTStop (void * simhandler, void * vehhandler, int sectionId, int stopid)

  Chamado toda vez que o veículo chega a uma parada de transporte público:

  - *simhandler*: O simulador.
  - *vehiclehandler*: O veículo
  - *sectionId*: ID da seção atual do veículo
  - *stopid*: ID da parada de transporte público atual do veículo
  

• MesoAPIManageCycleEvent (void * simhandler, int cycleEventId)

  Chamado toda vez para cada cycleEventId e para cada intervalo de tempo do ciclo. O ID do evento e o tempo do ciclo foram definidos usando funções AMesoAddCycleEvent para adicionar um novo evento e AMesoChangeCycleEventTime para alterar o evento pré-definido. A ideia por trás dessas funções, MesoAPIManageCycleEvent, AMesoAddCycleEvent e AMesoChangeCycleEventTime é que o usuário da API tem um mecanismo para sincronizar a simulação com a API em cada tempo de ciclo.

  - *simhandler*: O simulador.
  - *cycleEventId*: Um identificador de evento. Como esses IDs de eventos são criados e controlados é responsabilidade da API.
  

Modelo mesoscópico externo de dê preferência

Essas funções podem ser usadas para modificar o comportamento interno do modelo de dê preferência quando há sinais dê preferência.

• MesoAPIInterstedInGivewayModel(void *simhandler)

  Chamado sempre que é necessário aplicar um modelo de dê preferência e decidir qual dos dois veículos tem preferência. - simhandler: O simulador.

• MesoAPIInterstedInGivewayModelNode(void * simhandler, int nodeid)

  Chamado sempre que é necessário aplicar um modelo de dê preferência e decidir qual dos dois veículos tem preferência em um dado nó. - simhandler: O simulador. - nodeid: O ID do nó.

• MesoAPIApplyExtGivewayModel(void simhandler, int modelResult, void vehhandler, void *otherVehHandler, bool spatialConflict) Chamado sempre que é necessário aplicar um modelo de dê preferência e decidir qual dos dois veículos tem preferência. Os valores de retorno são: - 0: veículo na situação de dê preferência representado por vehhandler pode mover - 1: veículo na situação de dê preferência representado por vehhandler não pode mover porque o outro veículo representado por otherVehHandler tem preferência. - 2: veículo na situação de dê preferência representado por vehhandler não pode mover porque o outro veículo representado por otherVehHandler tem preferência e o outro veículo também tem um sinal de dê preferência afetando seu movimento.

  Os parâmetros de entrada são os seguintes: - simhandler: o simulador. - modelResult: este é o resultado da aplicação do modelo mesoscópico interno. - vehhandler: o veículo na situação de dê preferência - otherVehHandler: o veículo na corrente principal ou veículos para aplicar o dê preferência - spatialConflict: booleano que é verdadeiro quando há um conflito espacial entre as trajetórias de ambos os veículos. Falso quando ambos os veículos não têm conflito espacial.