Getting started
The SOABM 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 SOABM external station location, implemented in R along with the CVM.
The model system is run from a DOS batch program, RunModel.bat
The SOABM 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
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.
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:password@github.com/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:password@github.com/rsginc/SOABMTest
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".
- 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.
The scenario directory should have a file structure as shown below (all paths relative to the installation location):
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 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.
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
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.
To create and run a new model scenario (run), do the following:
- 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 that given model.
- If running the population synthesizer, refer to Running the Population Synthesizer. It only needs to be run once for each land use scenario.
- Ensure all required inputs are in the inputs folder.
- Edit the necessary input files for the scenario:
- Network – If there are network revisions for the scenario, edit the SOABM.ver file in VISUM before running the scenario.
- TAZ land use data – If there are population, employment, or other TAZ related revisions, edit the zones or mainzones in the SOABM.ver file before running the scenario. VISUM zones are TAZs and VISUM mainzones are MAZs. TAPs are stops in VISUM.
- Model setup – If desired, set the number of feedback iterations and the OR-RAMP household sample rate in the RunModel.bat file.
- Open a DOS command prompt in the scenario folder via Shift + Right click then Open Command Window Here (or "Open PowerShell Window Here")
- As shown in below, type RunModel.bat in the DOS window to run the model (if in PowerShell type .\RunModel.bat).
- 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).