Trucker.alp

Trucker.alp is an AnyLogic model along with some supporting software. It is an initial proof-of-concept model in which truckers move through real GIS space, and stop at truck stops and cities corresponding to real locations.

This wiki describes the model logic and provides a guide to understanding and stepping through the .alp file in AnyLogic.

Reading this documentation

Each agent type has its own page describing its behaviour, parameters, and sources of data if applicable. Most of the parameters are described in the Main agent's documentation. Many sections also include a section on possible improvements, which should be carefully considered before making any major refactors to the model or reimplementing it.

Some of the more complex decision processes in this model are illustrated by flow charts which can be found in the private Google Drive folder for this project (TODO move them here). If you are studying this model for the first time, you will probably find it very helpful to keep those charts handy as a reference.

Running the model

AnyLogic

The main model implementation lives in the file Trucker.alp. The model is currently not runnable in Anylogic PLE due to the number of different agent types, however we could possibly change that in the future by reducing the number of agents (e.g. Location, Storyteller). Production runs of this model will only be possible using Anylogic Professional because they will certainly need to be exported and run on an external server with a number of agents too large for PLE.

Dependencies

Java Archives

Trucker.alp depends on the following .jar files. They must be present in the same folder as Trucker.alp when running the model. These .jar files are included with the git repository, and copies can also be found on the private Google Drive folder for this project. Note that the version numbers may change in the future -- I will try to keep them up-to-date here but might forget.

• GravityModelDistribution-1.0.2.jar
• jhighway-0.0.1.jar
• graphhopper-map-matching-8.0.jar

Data files

The Excel files mentioned below are loaded into the model as AnyLogic databases. This is supposed to work automatically, but if you get errors related to missing data files you can fix it by deleting the database and re-loading each of the 3 files. This can be done by clicking the "Database" entry on the left sidebar, going to the right sidebar and clicking "Delete Database" if the option isn't disabled, then clicking "Create or Import A Table" to import the 3 files. More detailed instructions can be found here.

• Highways
  • The model requires OpenStreetMap highway data in the form of a .osm.pbf file. At the time of this writing, it is not included with the git repo due to its large size, but I might change my mind in the future. If it is not available in the repo, get it here. The path to this file needs to be loaded into Trucker.alp by editing the value of pathToOsmFile.
    • Ideally, the highway data should be pruned by deleting locations and residential streets.
      • TODO figure out how I did this and document the process.
  • You must also provide a path at which to store compiled highway data by editing the value of pathToRouteDataCache.
    • TODO we should just put this all in the same folder as Trucker.alp so that users don't have to edit paths.
    • The .osm.pbf data must be compiled into a more detailed form before running the model.
    • This happens automatically, however it means that the first time you run the model it will take a very long time to initialize.
    • The compiled data is stored at the provided path to allow for faster startup in future runs.
• Truck Stops & Gas Stations
  • Available in allstays_truckstop_data.xlsx. Simply make sure that this file is in the same folder as Trucker.alp.
  • This data comes from the AllStays PDF available for purchase at their website. Mike and I purchased a copy and extracted it to an Excel file using extract-pdf-data.py.
• Rest Areas
  • Available in rest-areas.xlsx. Simply make sure that this file is in the same folder as Trucker.alp.
  • This data comes from rest-areas.kml, which was extracted from the map shown at the Interstate Rest Areas website.
• Cities
  • Available in USA_Major_Cities.xlsx. Simply make sure that this file is in the same folder as Trucker.alp.
  • This was retrieved from USA government sources at this URL..

Running the Visualizer

Model runs will output data to .csv files in a folder called ModelRun-xyz. To visualize these results, use python from the command line to run visualizer/main.py. View the help menu for details on how to use the command line arguments. I have not properly set this up as a python project and so setting up dependencies on your own machine might be a bit of a pain. TODO fix this.