Installation

Installation

1. Clone this repository to your computer. This repository contains a template setup of swim.
2. Download the SWIM specific setups of Java, R, Python and other tools and unzip into the root/model/lib/ folder.
3. Create a PopulationSim specific swimpy environment in root/model/lib folder by calling (with double-click) extract_swimpy.bat script.
4. Create a java17 install in root/model/lib folder by calling (with double-click) download_java17.bat script.
5. ODOT has run into an issue with the sub folder under java17. The download_java.bat script should work without intervention, but as a quick check. Review the folder name under root/model/lib/java17 if the folder is not 'jre', update to root/model/lib/java17/jre.
6. Open command prompt and navigate to root/model/census directory. Download ACS PUMS data by running downolad_census.bat script within the command prompt.
7. Open command prompt and navigate to root/model/faf directory. Download FAF v4.5.1 data by running download_faf.bat script within the command prompt. If that script fails then manually download the FAF v4.5.1 zipped csv file from www.bts.dot.gov/faf/faf4 and unzip it into root/model/faf folder.
8. To ensure external users contact ODOT staff when running SWIM for analysis, an input network and zone Visum version file must be obtained from ODOT. This step is part of our modeling QA/QC policy. For those wanting to use this repository as a starting point for setting up a scenario for their own region, ODOT staff can provide examples and instruction on the file requirements to make the model operational for development purposes.
9. Copy into the root/scenario/inputs/t0 folder the Visum network and zone version file. The filename is referenced in the globalTemplate.properties as the ta.base.version.file token.
10. For machines that have never run SWIM before, the user might need to install Python to setup the Python27.dlls on the machine. First install Python 2.7.15 on the machine (likely in C:\Python27). Then open a command window (cmd) and navigate to C:\Python27, and run the following install line - 'python -m pip install pywin32'. Then copy the following file after the install from C:\Python27\Scripts\pywin32_postinstall.py to - D:\swim26\model\lib\Python27\Scripts\pywin32_postinstall.py. Then with admin privilages (right-click the cmd window shortcut to choose "run as administrator"), navigate to the directory - D:\swim26\model\lib\Python27- and enter this second command - 'python Scripts/pywin32_postinstall.py -install'. That should establish python on the machine to run with SWIM.

SWIM uses Visum to manage network data and run highway assignments. The user will need to install a licensed version of this software prior to running SWIM.

The current version of the model requires a computer with a 64-bit Windows operating system. The computer should have 48 gigabytes or more of RAM, and at least a few hundred gigabytes of free space on the model hard drive (a given model run may take up to 100 GB or more of hard drive space when finished).

File Structure

The installed model has a general file structure as shown below (all paths relative to the installation location):

build/
src/
root/model/
  census/
  faf/
  lib/
    Java/
    Python27/
    R/
    swimpy/
root/scenario_name/
  model/
    config/
    code/
      aa/
      ct/
      model_runner/
      visum/
      viz/
  inputs/
    parameters/
    t[year]/
  outputs/
    t[year]/

The build and src directories are used in compiling the TLUMIP Java archive. This archive is stored in root/scenario/model/code/tlumip.jar, and details of building it are given in Building TLUMIP

The main root/model/ directory contains large files which are too onerous to copy for every scenario. These include the Census ACS PUMS files and the external provided program executables for Java, Python, etc. Though outside of the main scenario directories, it is an essential part of the model distribution and should be included when transferring the model.

Every scenario is contained within its own folder, with a unique name. The folder name is the same as the scenario name. Within the scenario, the inputs/ folder contains the input files for a model run (i.e. those files that are an input to the model before it has started running). This includes parameters, template configuration properties, and bootstrap files (these latter files are held in the t[year]/ directories). The output/ folder holds the outputs of the model in the appropriate t[year]/ directories.

The model/ directory holds the model files used to control the actually running and runtime configuration of the model. The config/ directory contains the logging and DAF configuration files, and the runtime specification file. The details of these files are in Running Scenarios.

The model/code/ directory holds all of the code, scripts, and compiled Java executables to run the model. The details of these submodules are given in the individual sections.

Re-Building the SWIM Specific Setups of Java, R, and Python

To re-build the Java setup:

• install Java
• commit the revised setup to the tlumip_dependencies repository

To re-build the SWIM specific Python:

• install Mambaforge
• install VISUM
• update the swimpy_setup.yaml file
• run build_swimpy.bat (if needed, first update the locations of the VISUM and Mambaforge installs) from Mambaforge/Miniforge prompt.
• zip up the swimpy environment and split into chunks of size less than 95 Mb.
• copy the zipped chunks into swimpy_zipped_setup directory.
• commit the revised scripts and chunked zipped files to tlumip_dependencies repository

To re-build the SWIM specific R:

• install R
• install all the packages in R-requirements.csv
• commit the revised setup to tlumip_dependencies repository