-
Notifications
You must be signed in to change notification settings - Fork 29
Lua Interface
SimMobility is a simulation platform implemented in C++. The target users of the software are researchers and engineers trying to solve problems with transportation and urban planning. SimMobility aims to give a much greater control to its users on the models that are used in the software compared to other simulation tools available today.
An intuitive but naive approach to meet this requirement is to rigidly define alternative models in detail and allow users to choose between them. This approach, however, is limited to the options developed in the software. Those options may not be applicable for all users. Also, it does not allow users to try their trailblazing ideas without modifying the software code.
SimMobility solves this problem by taking a rather novel approach of plug-and-play modelling by interfacing directly with a scripting language called Lua.
Lua is a powerful, efficient, lightweight, embeddable scripting language. It supports procedural programming, object-oriented programming, functional programming, data-driven programming, and data description. The language syntax is simple and intuitive even for novice programmers.
SimMobility defines a clear generic Lua interface for many models for which full user control may be needed. Modellers are free to define their own models in Lua, the only constraint being that the model must comply with the interface. New models can be easily integrated with SimMobility through configuration files. No further C++ code development is needed and the software need not be recompiled. This allows a much greater flexibility to users who want to try their own models with SimMobility.
SimMobility also provides a default model for every model interface to allow users to work with only the models of their interest.
The following models are currently implemented in SimMobility through the Lua interface. Each of these models expose a global function which is invoked directly from C++ code through Lua references. More details are provided later.
- dpb.lua - Day pattern binary model
- dpt.lua - Day pattern tours model
- dps.lua - Day pattern stops model
- ntw.lua - Number of tours work model
- nte.lua - Number of tours education model
- nts.lua - Number of tours shopping model
- nto.lua - Number of tours others model
- tuw.lua - Attend usual work model
- tmw.lua - Tour mode work model
- tme.lua - Tour mode education model
- tmdw.lua - Tour mode/destination work model
- tmds.lua - Tour mode/destination shopping model
- tmdo.lua - Tour mode/destination others model
- ttdw.lua - Tour time of day work model
- ttdo.lua - Tour time Of day others model
- ttde.lua - Tour time Of day education model
- tws.lua - Work based sub-tours model
- stmd.lua - Work based sub-tours mode/destination model
- sttd.lua - Work based sub-tours time of day model
- isg.lua - Intermediate stop generation model
- imd.lua - Intermediate stop mode/destination model
- itd.lua - Intermediate stop time of day model
- zpa.lua - Zone postcode assignment model
Refer to preday documentation for more details on each of these choice models.
- pvtrc.lua - private traffic route choice model
- ptrc.lua - public transit route choice model
- wdmw.lua - within-day mode choice model for work trips
- wdme.lua - within-day mode choice model for education trips
- wdmso.lua - within-day mode choice model for work shopping and other trips
SimMobility code base defines a Lua interface for every model it exposes. There is a C++ to Lua code translation and mapping module - the [Lua Bridge] (https://github.com/vinniefalco/LuaBridge) - included in the SimMobility code. The properties and functions of C++ objects are exposed to Lua models through what is known as Lua Bindings. Every Lua model is expected to expose a global function with a specific name. The signature of this global function together with the bound properties and functions form the Lua interface for that model.
The models are written completely in Lua and its functionality is exposed to SimMobility through the global function. When SimMobility execution starts, all configured Lua models are loaded into memory and special objects called Lua references are created for each model. SimMobility invokes the global function in the Lua model directly through the Lua references and passes necessary (binded) arguments to this function. The return value of the Lua function is captured and mapped back to the C++ layer by the Lua bridge.