Phase 4 Scope of Work - ActivitySim/activitysim GitHub Wiki

Overview

Phase IV will be performed during FY1819, ending in June 2019, and will focus on multi-processing, shadow pricing, verification of model results and release of the initial version, support for two zone systems, and implementation support in two additional regions.

Task 1: Project Management
Task 2: Multi-Processing
Task 3: Shadow Pricing
Task 4: Verification and Release
Task 5: Implementation Support for ARC
Task 6: Support for Two Zone Systems
Task 7: Implementation Support for SANDAG

Task 1: Project Management

The purpose of this first task is to manage the overall project, including invoicing and conference calls with the project team, and coordination with the AMPO agency partners. All deliverables, including meeting notes, software, tests, documentation, and issue tracking will be managed through GitHub. UrbanLabs will twice review project progress and QA/QC select project deliverables, as identified by the AMPO partners.

Deliverable(s): (Due 10 months from NTP)

Management of Bi-Weekly Meetings
Pre- and Post-Meeting Notes
Invoicing and Progress Reports
Client Coordination
QA/QC of Select Deliverables

top

Task 2: Multi-Processing

The goal of this task is to revise ActivitySim to make use of multiple machine processors in order to reduce model run times. Currently, all ActivitySim procedures run in a single process. Within each sub-model, operations are chunked into reasonably sized chunks (for instance 5000 tours for choosing tour mode) in order to avoid creating data structures that are too big for the available memory. ActivitySim iterates through these chunks in a single process and accumulates the results.

In addition to iterating through the chunks, ActivitySim will concurrently operate on the chunks via multi-processing. Python multiprocessing is likely to be used, as opposed to threading within a single process, because an AB model fits better with the multiprocessing design pattern. Multiprocessing is a better approach when you need to do a lot of custom work within each process - data transformations, logging, tracing, expressions, building tours, etc. In addition, threading within a single process is difficult in Python due to the Global Interpreter Lock (GIL). To multi-process an ActivitySim model run requires the following basic steps:

Randomly assign households into process groups
Create shared data structures across processes for read only data - skims, zone data, etc
Start concurrent model runs for each of the household process groups
Merge the results into one data pipeline at two spots in the model run - at the end of work and school location choice and at the end of the overall model
Restart process after work and school location choice since shadow pricing requires data across households

We will begin by prototyping multi-processing for one sub-model, benchmarking the sub-model runtimes against the existing run, and discussing our findings with the AMPO partners. We will then revise the full example to use the new framework, and the updated software will be described in the online documentation.

Deliverable(s): (Due 2 months from NTP)

Prototype Multi-Process Sub-Model
Integration of Multi-Processing into the entire ActivitySim example
Updated Example
Updated Documentation and Tests

top

Task 3: Shadow Pricing

The goal of this task is to develop a shadow pricing module for the work and school destination choice models. Shadow pricing is an iterative mechanism that works to match estimated workers and students in each zone to input employment and enrollment totals. The calculated shadow prices are part of the destination choice model utilities and also output to a file so they can seed subsequent model runs in order to reduce run time. Shadow pricing in MTC travel model one is done by destination choice size variable segment (work low income, work medium income, work high income, work very high income, university, school grade, school high), zone, and walk transit sub-zone market (no walk %, short walk %, long walk %).

The ActivitySim Shadow Pricing module will provide the user with the optional ability to flexibly define a set of destination choice size terms by zone, segmented by purpose (e.g. work by industry sector, school by school type), worker or student attributes (e.g. income, age), and/or other geographies (school district boundaries). It will not include walk transit sub-zone markets since these are no longer needed in the multiple zone system approach (described below). The procedure will be implemented after multi-processing is added since shadow pricing requires summing data across processes (assuming processes process batches of households for example). Due to the iterative nature of the shadow pricing calculation, it will be implemented efficiently as possible. The module will include the ability to save results for input to subsequent model runs. The module will also include the ability to set iteration and convergence parameters, such as to iteratively update shadow prices up to a fixed number of times, or until a minimum threshold of destinations zones demonstrate a minimum performance criteria (eg. 95% of zones with more than 100 jobs are within +/- 5% relative to usual workplace destination choices). We will revise the existing ActivitySim work and school destination choice sub-models to use the new shadow pricing code. The new procedures will be described in the documentation.

Deliverable(s): (Due 3 months from NTP)

Shadow Pricing Calculation Procedure and Interface
Updated Work and School Destination Choice Sub-Models to Support Shadow Pricing
Updated Documentation and Tests

top

Task 4: Verification and Release

The goal of this task is to continue to verify, and correct as needed, all implemented sub-models. Consultant will work through the sub-models by comparing high level results to existing MTC TM1 calibration/validation summaries and will address significant issues in consultation with the PMC. Consultant will update the source code, documentation, and tests as a result of any revisions.

Deliverable(s): (Due 4 months from NTP)

Full Scale Example Model Run (All Zones, Skims, and Households) of All Implemented Sub-Models
Tabular Comparisons of Model Results to Expected Results
Updated Source Code, Configuration Files, Documentation, and Tests
Tagged Initial Release

top

Task 5: Implementation Support for ARC

(LIKELY PUSHED TO THE NEXT PHASE OF WORK) The goal of this task is to create a new test setup of the ActivitySim models that works with ARC model inputs. Consultant will assist ARC in preparing the input data and revising sub-model expression files. The level of implementation at this point assumes the setup will use all the existing TM1 implemented sub-models, and key structural components such as land use data, modes and skims, and times-of-day will be localized as budget permits. Consultant will prepare a brief implementation plan with work tasks and estimated level-of-effort for a complete implementation. The plan will include potential improvements to the software platform for easier implementation in additional regions.

Deliverable(s): (Due 6 months from NTP)

Assistance with Preparing Full Scale Example Model Run for ARC
Implementation plan
Informal Comparisons of Model Results to Expected Results
Additional Test Setup
Brief Implementation Plan

top

Task 6: Support for Two Zone Systems

(LIKELY PUSHED TO THE NEXT PHASE OF WORK) The goal of this task is to integrate comprehensive support for two zone system network level-of-service (see partner zone systems) into the ActivitySim framework. In two zone system models, for example the PSRC and SFCTA models, trips are modeled from MAZ/parcel-to-MAZ/parcel and the network level-of-service zone system varies by mode:

Auto - TAZ-to-TAZ skims
Walk/bike/near auto - MAZ-to-MAZ for nearby zone pairs using path costs from an allstreets network
Transit - TAZ-to-TAZ skims except for access/egress time, which comes from the MAZ/parcel file, which includes access distance by transit line-haul for each MAZ

In three zone system models, for example the SANDAG and MTC TM2 models, transit stop-to-stop skims + a set of nearby stops for each MAZ are used to do transit virtual path building during a demand model run in order to build MAZ-to-MAZ transit impedance through the best access and egress stops. Under a separate contract, support for three zone systems (minus transit virtual path building) was prototyped using the SANDAG ABM model inputs.

The scope of this task is to integrate the prototyped three zone system implementation into a new two zone system example model for the MTC TM1 example. This will include switching from the one-zone skims classes to the multi-zone NetworkLOS classes, updating logging, updating tracing, updating all expression files with spatial data, including logsums, updating tests, updating expected test results, and updating the documentation. Full support for three zone systems (which adds transit virtual path building) may be done in a later phase of work.

The model system will operate at the "zone" level, which could be either MAZs or TAZs, and it will be possible to index into skims using the zone IDs or other zone attributes (such as TAZ if zones are MAZs for example). For testing, the MTC TM1 TAZ data will be copied to MAZs as if there is a one-to-one correspondence. In order to better test the relationships between the different data structures, a couple of MAZs will be re-assigned to different TAZs. The complete new example model will be tested and documented.

Deliverable(s): (Due 8 months from NTP)

Integration of Support for both One and Two Zone System Models
Additional Full Scale Example
Updated Documentation and Tests

top

Task 7: Implementation Support for SANDAG

(LIKELY PUSHED TO THE NEXT PHASE OF WORK) The goal of this task is to create a new test setup of the ActivitySim models that works with SANDAG model inputs in order to test the two zone system approach implemented in Task 6. Consultant will assist SANDAG in preparing the input data and revising sub-model expression files. The setup will use all the existing TM1 implemented sub-models, with the addition of the Task 4 work, and key structural components such as land use data, modes and skims, and times-of-day will be localized as budget permits.

Consultant will also assist SANDAG with developing procedures to code transit access/egress distance by MAZ for each transit line-haul mode or skim set. DaySim's MAZ input file, as used by PSRC and SFCTA, has attributes for distance to the nearest transit stop by path type (line-haul mode). For the SANDAG example, a best stop for each MAZ will be identified and then the distance will be looked up from the transit access/egress distance file. Each MAZ will also be attributed with the best stop by path type in order to lookup the line-haul skim data such as in-vehicle time from the stop-to-stop skims. See the SANDAG Multiple Zone Systems Design for more info. Consultant will prepare a brief implementation plan with work tasks and estimated level-of-effort for a complete implementation. The plan will include potential improvements to the software platform for easier implementation in additional regions.