Anatomy of a Polaris model

Contents

Anatomy of a Polaris model#

Understanding the anatomy of a model is a helpful activity when working with POLARIS, especially when editing existing models or creating new ones. In this section we discuss the folder structure of an POLARIS model. For the structure of a model repository, please refer to Storing models with Polaris-Studio.

Polaris models consist of multiple files of different types and organized in a specific folder structure, as shown below.

Model root folder

The most important components, circled in the image above, are detailed below:

  • Control files

    • convergence_control.yaml : Contains the run configuration (regular convergence, calibration procedure, simple skimming, etc.)

    • scenario_abm.json: Contains the POLARIS base configuration for a regular single-shot model run, which is automatically modified for each iteration specified in the convergence_control file.

  • Databases

    • MODEL-Supply.sqlite: Contains all the supply model (e.g. Links & nodes, transit system, EV charger locations, etc.)

    • MODEL-Demand.sqlite: Contains definitions of the travel demand (Trips, Activities, etc) as well as the population (Person, Household, Vehicle, etc). This also includes the exogenous demand (trip type = EXTERNAL) to be considered in the model run.

    • MODEL-Freight.sqlite: Contains both freight infrastructure (airports, ports, etc.) as well as the firms and establishments that generate freight travel. Note that Freight demand is stored in the trips table in the Demand database alongside all other types of trip.

    • Both the Freight and Demand databases store outputs of the model and will generally be copied from the iteration sub-directory to the root directory after each iteration to serve as the inputs to the next iteration.

  • Population data: (usually stored in the config folder)

    • linker_file.txt: Configuration file for the population synthesizer

    • sf1_file.txt: Control totals for the population synthesizer

    • pums_file.txt: Microsample information on households for the population synthesizer

    • pums_person_file.txt: Microsample information on population for the population synthesizer

  • Parameters: (usually stored in the config folder)

    • mode_choice.json: Contains the parameters for the mode choice model

    • destination_choice.json: Contains the parameters for the destination choice model

    • activity_generation.json: Contains the parameters for the activity generation model

    • …

Other files not essential for the model run, but useful during model application are:

  • Calibration targets: Stored in the calibration_targets folder, are used when both Running calibration and for generating validation charts after model run, which can be automatically done by Polaris-Studio.

    • activity_generation_targets.csv: Contains the targets for the activity generation model

    • mode_choice_targets.csv: Contains the targets for the mode choice model

    • …

Model iterations#

When running Polaris, all model outputs are stored in a separate folder for each iteration, facilitating convergence and result analysis. Each one of these models starts with the name of the model (Bloomington for the example below), and have a suffix that indicates the iteration number and type, such as Bloomington_iteration-1 or Bloomington_00_skim_iteration.

Organization of iteration folders

Inside each iteration folder, copies of all parameters and input databases are stored alongside the iteration outputs, ensuring reproducibility for each iteration. It is worth highlighting the following contents of each iteration folder:

  • Databases

    • MODEL-demand.sqlite: Contains the results for the demand model, including records on the population, fleet, activities and trips generated by the model.

    • MODEL-Result.sqlite: Contains many aggregate results of the simulation, such as TNC statistics, average wait times, walk times, zonal accessibility, etc.

    • MODEL-Freight.sqlite: Contains the results for the freight model, including shipments, delivery vehicle tours and trips

  • Binary files:

    • MODEL-Result.h5: Contains the disaggregated results of the simulation, such as link and turn performances for each reported time step (e.g. every 2s).

  • Skims:

    • highway_skim_file.omx: Highway skims are computed in this iteration

    • transit_skims_file.omx: Transit skims. They are generally only computed once, and therefore would be present in the skimming iteration folder only.

  • Text files:

    • log/polaris_progress.log: Log of the POLARIS executable run

    • model_files/*: Contains a copy of all model parameters and scenario_abm.json as used in the iteration, as well as as option_usage.csv, which consolidates all the parameters used in the model run

    • kpi.cache/*: Cached computation of the KPIs computed after the model run. These KPIs are computed asynchronously after each iteration is completed, all but eliminating the added time required for obtaining model KPIS after the model run is finalized.

    • gap_*.csv: Various gap calculations

    • summary.csv: Snapshot of the simulation at every timestep (number of vehicles in the network, completed trips, etc.)

These files look like the following on disk. It should be noted that Polaris-Studio compresses the largest model outputs after each iteration (asynchronously, after KPI calculations) to save disk space:

Iteration folder contents

Contents