Arquitetura da API¶

A solução Aimsun Next¶

A abordagem adotada no Aimsun Next é considerar uma Aplicação Telemática Avançada a ser testada 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, por meio de um conjunto de funções, ele fornece à aplicação externa os "Simulation Detection Data" 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 gerenciamento devem ser aplicadas na rede viária. Por fim, a aplicação externa envia as atuações correspondentes (por exemplo, alterar o estado do semáforo, a duração da fase, exibir uma mensagem em um VMS etc.) ao modelo de simulação, que então emula sua operação por meio dos componentes correspondentes do modelo, como semáforos, VMSs e sinais de medidores de rampa.

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

Implementação¶

Introdução à API do Aimsun Next¶

O módulo 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 ligação e pode variar desde programação direta (isto é, o código que usa a API é a aplicação externa) para um protocolo de comunicação de rede que emula hardware de comunicações em via pública e em que a aplicação externa é um sistema de produção em grande parte não modificado.

API de Microssimulação do Aimsun Next¶

O módulo API do Aimsun Next tem seis funções de alto nível que fazem a comunicação entre o Módulo API do Aimsun Next e o modelo de Simulação. Elas são: AAPILoad, AAPIInit, AAPISimulationReady, AAPIManage, AAPIPostManage, AAPIFinish, AAPIUnLoad.

Ele também tem oito funções adicionais que são chamadas quando certos eventos ocorrem. São elas: AAPIEnterVehicle e AAPIExitVehicle, AAPIEnterVehicleSection, AAPIExitVehicleSection, AAPIPreRouteChoiceCalculation, AAPIVehicleStartParking, AAPIActionActivated e AAPIActionDeactivated.

Gerenciamento 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 tudo e os veículos estão prontos para começar a se mover.

Funções de Passo de Tempo¶

Há duas funções de simulação chamadas a cada passo de tempo AAPIManage é chamada antes que o simulador execute quaisquer ações; em seguida, o simulador realiza seus cálculos e atualiza os veículos e semáforos. Finalmente, ao fim do passo de tempo, AAPIPostManage é chamado.

Portanto, quando o timestep da simulação é avaliado, as ações realizadas em AAPIManage são incluídos e quando AAPIPostManage é chamado, as ações realizadas em ambos AAPIManage e o timestep estão incluídos. Ações realizadas em AAPIPostManage de uma etapa de simulação será então levada em consideração na etapa de simulação seguinte. Em geral, é preferível fazer alterações para ITS ou semáforos em AAPIManage para que sejam levadas em conta pelos veículos naquele timestep e para fazer alterações para veículos em AAPIPostManage para que os veículos ao redor deles estejam atualizados com suas próprias ações.

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

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

  - *time*: Absolute time of simulation in seconds. At the beginning of the simulation (beginning of the warm-up, if any), it takes the value 0.
  - *timeSta*: Time of simulation in stationary period (start from Simulated Initial Time), in seconds from midnight. The value of timeSta is invalid during the warm-up period (where it will always return beginning of the stationary period).
  - *timeTrans*: Duration of warm-up period, in seconds.
  - *cycle*: Duration of each simulation step in seconds.
  

  Exemplo:

  Iniciamos uma simulação às 07:00, com 5 minutos de período de aquecimento, e simulamos um minuto com 1 segundo como passo de simulação. Considerando 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)

  Chamada em cada passo de simulação ao final do ciclo, e pode ser usada para solicitar medidas de detectores, informações de veículos e interagir com interseções, medidores de rampa e VMS para implementar a política de controle e gerenciamento. Esta função recebe quatro parâmetros relacionados ao tempo:

  • tempo: Tempo absoluto de simulação em segundos. No início da simulação (início do aquecimento, se houver), ele assume o valor 0.
  • timeSta: Tempo de simulação no período estacionário (início a partir de Simulated Initial Time), em segundos a partir da meia-noite. O valor de timeSta é inválido durante o período de aquecimento (quando sempre retornará o início do período estacionário).
  • timeTrans: Duração do período de aquecimento, em segundos.
  • ciclo: Duração de cada etapa de simulação em segundos.

Funções de Encerramento¶

• AAPIFinish ()

  Chamado quando o Aimsun Next conclui a simulação e pode ser usado para encerrar as operações do módulo, gravar 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 API Module interagem.

Eventos de simulação¶

• AAPIEnterVehicle (int idveh, int idsection)

  Chamada quando um novo veículo entra no sistema, isto é, quando o veículo entra em sua primeira seção, não quando entra em uma fila Virtual, se houver uma. Esta função recebe dois parâmetros:

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

• AAPIExitVehicle (int idveh, int idsection)

  Chamado quando um veículo sai da rede. Esta função recebe 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 recebe três parâmetros:

  - *idveh*: Identifier of the vehicle.
  - *idsection*: Identifier of the section the vehicle is entering.
  - *atime*: Absolute time of the simulation when the vehicle enters the section. At the beginning of the simulation (beginning of the warm-up, if any), it takes the value 0.
  

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

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

  - *idveh*: Identifier of the vehicle.
  - *idsection*: Identifier of the section the vehicle is exiting.
  - *atime*: Absolute time of the simulation when the vehicle exits the section. At the beginning of the simulation (beginning of the warm-up, if any), it takes the value 0.
  

• AAPIEnterPedestrian (int idPedestrian, int originCentroid)

  Chamado quando um novo pedestre entra no sistema, isto é, quando o pedestre entra por sua entrada. Esta função recebe dois parâmetros:

  - *idPedestrian*: Identifier of the new pedestrian entering the network.
  - *originCentroid*: Identifier of the pedestrian entrance where the pedestrian enters the network.
  

• AAPIExitPedestrian (int idPedestrian, int destinationCentroid)

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

  - *idPedestrian*: Identifier of the pedestrian exiting the network.
  - *destinationCentroid*: Identifier of the pedestrian exit where the pedestrian exits the network.
  

• AAPIPreRouteChoiceCalculation (double time, double timeSta)

  Chamado imediatamente antes do início de um novo ciclo de cálculo de escolha de rotas. Pode ser usado para modificar os custos de seções e movimentos de conversão para afetar o cálculo de escolha de rotas. Esta função recebe dois parâmetros relacionados ao tempo:

  - *time*: Absolute time of simulation in seconds. At the beginning of the simulation (beginning of the warm-up, if any), it takes the value 0.
  - *timeSta*: Time of simulation in stationary period (start from Simulated Initial Time), in seconds from midnight. The value of timeSta is invalid during the warm-up period (where it will always return beginning of the stationary period).
  

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

  Called when a vehicle starts a parking maneuver.
  
      - *idveh*: Vehicle identifier.
      - *idsection*: Section identifier where vehicle is doing the parking.
      - *time*: Current simulation time.
  

• char* AAPIInternalName ()

  Retorna o nome interno exclusivo da API. Ele é chamado ao registrar APIs antes da simulação.

• AAPIActionActivated (int idAction)

  Called when a traffic management action is activated.
  
      - *idAction*: Traffic management action identifier.
  

• AAPIActionDeactivated (int idAction)

  Called when a traffic management action is deactivated.
  
      - *idAction*: Traffic management action identifier.
  

API Mesoscópica do Aimsun Next¶

O módulo Aimsun Next Mesoscopic API tem quatro funções de alto nível que fazem a comunicação entre o API Module e o modelo de simulação. São elas: MesoAPILoad, MesoAPIUnLoad, MesoAPIInit, MesoAPIFinish.

Ele também tem cinco funções adicionais que são chamadas quando determinados eventos ocorrem. São elas: MesoAPINewVehicleSystem, MesoAPINewVehicleNetwork, MesoAPIFinishVehicleNetwork, MesoAPIEnterVehicleSection, MesoAPIActionActivated, MesoAPIActionDeactivated, MesoAPIExitVehicleSection e MesoAPIPostManageControl.

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

Gerenciamento da Simulação¶

• MesoAPILoad ():

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

• 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*: The iteration number. In a one-shot simulation this  parameter is not used but in DUE simulation iterationNumber goes from 1 to number of iterations.
  - *statisticsAllowed*: true if statistics are allowed in this iteration or simulation when executing a one-shot simulation.
  

• MesoAPISimulationReady (void * simhandler)

  Chamado quando o Aimsun Next inicia a simulação e tudo está pronto para começar a movimentar os veículos. É 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)

  Chamada quando o Aimsun Next finaliza a simulação. Ao executar um DUE, esta função é chamada ao final de cada iteração.

A figura a seguir mostra como o Aimsun Next e o API Module interagem.

Eventos de simulação ¶

• MesoAPINewVehicleSystem(void * simhandler, void * vehhandler)

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

  - *simhandler*: Simulator.
  - *vehhandler*: The vehicle generated.
  

• MesoAPINewVehicleNetwork (void * simhandler, void * vehhandler)

  Chamado quando um novo veículo entra na rede. Isso ocorre quando ele sai da fila virtual, caso estivesse aguardando para entrar na rede:

  - *simhandler*: Simulator.
  - *vehhandler*: The vehicle generated.
  

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

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

  - *simhandler*: Simulator.
  - *vehhandler*: The vehicle.
  - *fromSection*: Identifier of the section origin
  - *toSection*: Identifier of the section it is entering.
  

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

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

  - *simhandler*: Simulator.
  - *vehhandler*: The vehicle.
  - *section*: Identifier of the section it is exiting
  

• 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 recebe três parâmetros:

  - *simhandler*: Simulator.
  - *vehhandler*: The vehicle.
  - *section*: Identifier of the next section
  

• MesoAPIPostManageControl (void * simhandler)

  Chamada sempre que há uma alteração no controle. Esta função só é chamada quando o plano de controle mestre possui controladores adaptativos. Esta função recebe um parâmetro:

  - *simhandler*: The simulator.
  

• MesoAPIPreManageRouteChoice (void * simhandler)

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

  - *simhandler*: The simulator.
  

• MesoAPINewStatisticalInterval (void * simhandler)

  Chamada toda vez que o ciclo de estatísticas é iniciado. Esta função recebe um parâmetro:

  - *simhandler*: The simulator.
  

• MesoAPINewDetectorStatisticalInterval (void * simhandler)

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

    - *simhandler*: The simulator.

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

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

  - *simhandler*: The simulator.
  - *vehiclehandler*: The vehicle
  - *nodeid*: Node Identifier of the node
  

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

  Chamado toda vez que o veículo chega a um ponto de parada de transporte coletivo:

  - *simhandler*: The simulator.
  - *vehiclehandler*: The vehicle
  - *sectionId*: Current vehicle's section ID
  - *stopid*: Current vehicle's transit stop ID
  

• MesoAPIManageCycleEvent (void * simhandler, int cycleEventId)

  Chamado a cada vez para cada cycleEventId e para cada tempo de ciclo. O id do evento e o tempo de ciclo foram definidos usando as funções AMesoAddCycleEvent para adicionar um novo evento e AMesoChangeCycleEventTime para alterar o evento predefinido. A ideia por trás destas funções, MesoAPIManageCycleEvent, AMesoAddCycleEvent e AMesoChangeCycleEventTime, é que o usuário da api tenha um mecanismo para sincronizar a simulação com a api em cada tempo de ciclo.

  - *simhandler*: The simulator.
  - *cycleEventId*: An event identifier. How these events id are created and controller is under the responsibility of the api.
  

• MesoAPIActionActivated (void * simhandler, unsigned int idAction)

  Chamado quando uma ação de gestão de tráfego é ativada.

  - *simhandler*: The simulator.
  - *idAction*: Traffic management action identifier.
  

• MesoAPIActionDeactivated (void * simhandler, unsigned int idAction)

  Chamado quando uma ação de gerenciamento de tráfego é desativada.

  - *simhandler*: The simulator.
  - *idAction*: Traffic management action identifier.
  

Modelo mesoscópico externo de dar preferência ¶

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

• MesoAPIInterstedInGivewayModel(void *simhandler)

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

• MesoAPIInterstedInGivewayModelNode(void * simhandler, int nodeid)

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

• MesoAPIApplyExtGivewayModel(void simhandler, int modelResult, void vehhandler, void *otherVehHandler, bool spatialConflict) Chamado toda vez que é necessário aplicar um modelo de prioridade e decidir qual de dois veículos tem preferência. Os valores de retorno são: - 0: o veículo na prioridade representado por vehhandler pode se mover - 1: o veículo na prioridade representado por vehhandler não pode se mover porque o outro veículo representado por otherVehHandler tem preferência. - 2: o veículo na prioridade representado por vehhandler não pode se mover porque o outro veículo representado por otherVehHandler tem preferência e o outro veículo também tem uma placa de yield 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 conversão que deve ceder passagem - otherVehHandler: o veículo na corrente principal ou veículos aos quais aplicar o dê a preferência - spatialConflict: boolean que é true quando há um conflito espacial entre as trajetórias de ambos os veículos. False quando ambos os veículos não têm um conflito espacial.