Skip to content

Getting started

Jump to bottom
Alex Bettinardi edited this page Dec 1, 2020 · 30 revisions

The ABM is a collection of travel modeling components. The core components of the system are:

  • OR-RAMP – ODOT’s version of the CT-RAMP family of ABMs for modeling resident travel, implemented in Java.
  • VISUM and Python – Zone and network data management, as well as network skimming and assignment procedures.
  • Commercial vehicle model (CVM) – ODOT’s trip-based commercial vehicle model implemented in R.
  • External model – ODOT’s external travel model based on select link analysis flows from SWIM at each ABM external station location, implemented in R along with the CVM.

The model system is run from a DOS batch program, RunModel.bat

Hardware Requirements

The ABM can be run on a typical Windows 64-bit machine, with the following settings:

  • At least 24GB of RAM is required to run the base year version of the model
  • At least 4 processors – additional cores will reduce runtime
  • At least 10GB of free storage – a single model run currently takes around 7GB

Software Requirements

The model is configured to run on Windows, and uses VISUM, Python, Java, and R. To ease installation and setup, complete installations of Python, Java, and R are included in the model setup and are used when running the model.

  • Python is VISUM’s preferred scripting tool, Java is used for CT-RAMP, and R is used for the commercial vehicle model and external model. The installations include the third-party libraries required as well.
  • VISUM is a commercial transport modeling software package developed by PTV. 64bit VISUM is required (currently in version 18, needs to be 18.02-07 or later) and the latest installer is available here.

Model Setup

First, download the model program files. The model program files are stored on github. The first step is to clone the github repository SOABM to the machine that the model is going to be run. In order to do this, the user must have git-lfs installed first.

# with git-lfs installed, open a dos prompt, navigate to a directory, and type:
git clone https://username:[email protected]/rsginc/SOABM

In the SOABM directory, a ~625MB dependencies.zip will be downloaded if the SOABM repository was cloned correctly. This zipped folder has all of the required programs to run the model (Java, Python, and R) other than VISUM. If this file does not exist or is smaller than 600MB, git lfs is probably not working correctly on your machine. If this is the case, you can directly download dependencies.zip into the SOABM folder.

In addition to the dependencies.zip file, the SOABM repository contains a template folder with a number of subdirectories, as shown in Template Model Directory. The template model directory contains the RunModel.bat file that is used to launch a full model run. Some of the subdirectories are empty, and will get populated as the model runs. Other subdirectories have files in them that are used by the model. SOABM also includes a source subdirectory, which contains Java source code for the CT-RAMP model and the volume-delay function used in the model. The source files are not required for running the model; only the dependencies.zip file and the template directory from the SOABM directory are required.

Next, download the SOABMTest repository from here or from github. The SOABMTest directory has all base-year inputs for the model (synthetic population, a VISUM version file, and other inputs), and can serve as a demo SOABM scenario to build off of.

The SOABMTest github repository uses git-lfs as well.

# with git-lfs installed, type:
git clone https://username:[email protected]/rsginc/SOABMTest

Setup

On initial checkout/download, the user will need to:

  • Create a scenario folder with a scenario specific name, such as "NoBuild2040"
  • Expand SOABM\dependencies.zip into a directory at the same level as the scenario folder since it will be used by multiple scenarios.
  • Copy the SOABM\template folder contents to the scenario folder.
  • Copy the SOABMTest\inputs folder to the inputs folder in the new scenario folder. Or use your own inputs, such as the inputs for a "NoBuild2040".
    • An important note and consideration, if the year being setup (in this example 2040) is different than the template or scenario being copied to build the new scenario, the user needs to remember to update SWIM_External_Properties.csv in the config\swim_ext folder. There is a "year" field in that file that tells the external model what year to adjust land use outside of the model region up to, and what year to set external volumes to. That year value needs to be properly set to get correct values from the external model.
  • Ensure that the ODOT VDF files get copied to the user-defined DLL folder. Note that the DLL is copied by the RunModel.bat file to the AppData/Roaming directory of the current Windows session, so the user shouldn't need to copy anything by hand for this step. The user just needs to be aware that this is a critical step that must occur, and if the model produces assignments that run too long or don't make sense, it might be due to this step not properly copying the VDF files.

File Structure

The scenario directory should have a file structure as shown below (all paths relative to the installation location):

Template Model Directory

The input directory should have all of the model inputs. In addition there should be a dependencies folder that is the same level as the scenario directory.

Following is a description of each folder:

root/dependencies/
  jdk1.8.0_111/ – Java installation directory
  Python27/ – Python 2.7 installation directory
  Python37/ – Python 3.7 installation directory
  R-3.3.1/ – R installation directory
root/scenario_name/
  RunModel.bat – Script used to run model
  application/ – DOS batch files, Java jar file, HDF5 DLLs for OMX, VDF DLLs
  config/ – ORRAMP properties file, ORRAMP JPPF config files
    cvm/ – CVM model parameters
    visum/ – skimming procedure files
  inputs/ – Popsyn files, VISUM scenario version file, external model files, etc.
  inputChecker/ - Input Checker Tool
  logs/ – ORRAMP output log files
  outputs/ – other model outputs – skims, trip lists, matrices, etc.
  scripts/ – VISUM skimming, OMX reader/writer, external model, CVM
  uec/ – ORRAMP utility expression calculator (UEC) model parameter files
  visualizer/ - ORRAMP visualization tool

Running the Model

Make sure to edit any inputs in the inputs folder if needed. Open a DOS command window in the scenario folder and type RunModel.bat:

# In the scenario directory, type:
RunModel.bat

If the amount of RAM or the number of processing threads for CT-RAMP needs to be updated (because the population increased or the run machine changed) then the following settings should be reviewed:

  • application\runHhMgr.cmd – near the bottom of the script, the START … -Xmx10000m setting specifies how much RAM is allocated to the household data manager
  • application\runMtxMgr.cmd – near the bottom of the script, the START … the -Xmx10g setting specifies how much RAM is allocated to the matrix data manager
  • application\runORRAMP.cmd – near the bottom of the script, the java … the –Xmx40g setting specifies how much RAM is allocated to the main process
  • config\jppf-clientLocal.properties – at the bottom of the file, the jppf.local.execution.threads = 10 setting specifies how many threads are allocated to CT-RAMP.

Creating and Running a new Scenario

To create and run a new model scenario (run), do the following:

  1. On initial checkout, expand the dependencies.zip to a folder called dependencies. This includes installs of Java, Python, and R. Every scenario is contained within its own folder, with a unique name. The folder name is the same as the scenario name. The dependencies folder must be next to the scenario folder since it is referenced in the RunModel.bat via ..\dependencies. Note this is only on initial checkout, so once the dependencies folder is established on a machine, it is used for all the ABM scenarios for the ABM.
  2. If the scenario involves household or person changes, refer to Running the Population Synthesizer. The Population Synthesizer only needs to be run once for each land use scenario.
  3. Ensure all required inputs are in the inputs folder.
  4. Edit the necessary input files for the scenario:
    1. Network – If there are network revisions for the scenario, edit the SOABM.ver file in VISUM.
    2. MAZ land use data – If there are population, employment, or other zone related revisions, edit the zones (typically mainzones, MAZs) in the SOABM.ver file. VISUM zones are TAZs and VISUM mainzones are MAZs. TAPs are stops in VISUM.
    3. If any edits are made in the version file, the user should ensure that the revised version file passes all relevant Network checks under the Calculate -> Network check function in Visum. All checks may not be necessary. Typically the user should be able to ensure the follow checks complete without issue:
      • Isolated nodes
      • Zones not connected for PrT
      • Check network consistency (for all auto modes)
      • Dead-end roads PrT (for all auto modes)
      • Links without succeed. link (for all auto modes)
      • Links with Capacity PrT = 0 or v0 = 0
  5. Model setup – If desired, set the number of feedback iterations and the OR-RAMP household sample rate in the RunModel.bat file.
  6. If the scenario is for a different year, the user needs to update the year value in config\swim_ext\SWIM_External_Properties.csv to the correct scenario year.
  7. Open a DOS command prompt in the scenario folder via Shift + Right click then Open Command Window Here (or "Open PowerShell Window Here")
  8. As shown in below, type RunModel.bat in the DOS window to run the model (if in PowerShell type .\RunModel.bat). Prior to running the RunModel.bat file the user can consider if any changes to the bat file are needed such as the number of iterations or the scenario to compare results to upon run completion. More information on making changes to the bat file can be found on the Run Model page.

RunModel.bat

  1. The model runtime depends on the number of machine processors, the household sample rate, and the number of overall model feedback loops. The initial network build and skimming steps take about 1 hour, a 100% run of CT-RAMP takes about 45 minutes, and assignment/skimming takes about 30 minutes. As a result, a 3 feedback loop model run takes about 5 hours (1 hr + 45min + 30 min + 45min + 30 min + 45min + 30min).
  2. The user should make sure to review the input check record as a QC that there were no issues with the new scenario inputs / setup. Refer to the Input Checker page for more details.

Go to Top

Home

Guides

Model Description

Appendix

Clone this wiki locally