Phase 7a Scope of Work - ActivitySim/activitysim GitHub Wiki

Table of Contents

Revised Schedule for Code Deliverables

  • Task 2: Sharrow Part 1, 1 Zone Models - PR #542
  • Task 3: Sharrow Part 2: 2 & 3 Zone Models - PR by August 23rd
  • Task 4: Sharrow Time Windows - PR by Sept 13th
  • Task 5: School Pickup - PR by Aug 15th
  • Task 6: Disaggregate Accessibility – PR by August 31st
  • Task 7: Shadow Pricing - PR by Sept 30th

Task 1: Project Management

Consultant will provide management support for the overall project, including conference call management with the project team, coordination with the ActivitySim Project Management Committee (PMC). Consultant will provide maintenance and support services to ensure ActivitySim and PopulationSim are in good working order. Tasks include dealing with updates in dependent packages, maintaining the test system, examples, and documentation, assisting with pull requests, making improvements based on agency user feedback, supporting agency users with questions, and implementing agreed upon GitHub issues. Consultant will also provide code review, software development support, and support performance enhancement activities of project team members. All deliverables, including meeting notes, software, tests, documentation, and issue tracking will be managed through GitHub.

Deliverables:

  • Co-management of ActivitySim Project Management Committee Weekly Meetings
  • Pre-and Post-Meeting Notes
  • Email and online support to contributor and agency user and pull requests
  • Updated source code as necessary
  • Updated examples as necessary
  • Updated documentation as necessary
  • Updated tests as necessary
  • Updated issues as necessary

top

Task 2: Performance Enhancement Part 1

The goals of the Performance Enhancement Part 1 task are:

  • To integrate revisions and extensions to the ActivitySim code base that reduce ActivitySim’s runtime and memory requirements while requiring minimal revisions to ActivitySim inputs;
  • To demonstrate these runtime and memory requirement reductions using the ActivitySim examples present in the project examples repository as of the start date of this task order;
  • To verify that the revised ActivitySim examples produce outputs consistent with those generated without the code revisions and extensions.

The Consultant will revise the ActivitySim code base to leverage the new sharrow library developed by the Consultant, as well as the open source Xarray package. The Consultant will release the sharrow library under the same permissive BSD 3-Clause license as ActivitySim itself, with copyright assigned to AMPO Research Foundation, and will open a pull request to the ActivitySim repository with the code necessary to implement sharrow within ActivitySim. The consultant will ensure that only negligible changes to the interface or to user-facing data, configuration, and utility specification files that define current ActivitySim implementations are required in order to benefit from the Part 1 modifications. The consultant will ensure that all pull requests to ActivitySim include updated source code, documentation and tests.

For each of the ActivitySim example in the examples repository as of the start date of this task order, the Consultant will:

  • Identify files that need to be modified to run with the Part 1 modifications;
  • Implement any modifications to ensure that each example is stable and operational with the Part 1 modifications. If consultant discovers any particular ActivitySim example implementations with components that contain extensive incompatibilities, Consultant will ensure that these components still operate correctly, reverting to the existing ActivitySim methods and functionality as necessary. Consultant will work with the consortium and individual agencies to develop a plan for any additional effort to bring the full benefit of our enhancement package to every ActivitySim example implementation;
  • Quantify and document the changes in runtimes and memory requirements resulting from the revisions and extensions to the ActivitySim codebase. To the extent possible, this quantification will leverage the airspeed velocity infrastructure and reporting implemented by the Consultant in an earlier task order. All ActvitySim examples will be tested with “chunking” disabled, and on the same server. AMPO and the ActivitySim partners will work with the Consultant to identify and secure use of sufficient computing hardware resources if the Consultant is unable to do so independently;
  • Verify that the outputs of the ActivitySim example models run with Part 1 modifications results are consistent with outputs of the ActivitySim example models run without Part 1 modifications. Consistency will be demonstrated by repurposing the aggregate model summaries used in the original MTC ActivitySim verification process, as documented here. Note that 100% consistency in disaggregate model outputs is not expected nor a requirement.

The Consultant will provide email and online support to the ActivitySim partners and to the other ActivitySim bench consultants. The Consultant will also coordinate with the other ActivitySim bench consultants and partners to develop a schedule for sequencing and timing of other ActivitySim development and implementation efforts so as leverage this Performance Enhancement Part 1 task.

Deliverables:

  • Publication of sharrow under the same BSD 3-Clause license as ActivitySim itself, with copyright assigned to AMPO Research Foundation.
  • Pull requests to ActivitySim with updated source code, documentation and tests.
  • Updated, operational ActivitySim examples
  • Verification of updated ActivitySim examples.
  • Email and online support for contributor and agency users.

Schedule: Overall completion by June 3, 2022

top

Task 3: Performance Enhancement Part 2 / Two-Zone and Three-Zone systems

The goal of the Performance Enhancement Part 2 task is to extend sharrow fully into Two-Zone and Three-Zone systems:

  • For components of the ActivitySim codebase that support the “two-zone” and “three-zone” ActivitySim implementations, to extend the types of revisions and extensions to the ActivitySim code base that reduce ActivitySim's runtime and memory requirements while requiring only minimal revisions to ActivitySim inputs;
  • To demonstrate these reductions in the ActivitySim two-zone and three-zone examples present in the project examples repository as of the start date of this task order;
  • To verify that the revised ActivitySim two-zone and three-zone examples produce outputs consistent with those generated without the code revisions and extensions.

The ActivitySim code base will be revised to leverage the new sharrow library developed by the Consultant, as well as the open source Xarray package to effect runtime reductions and memory reductions in ActivitySim code that supports two-zone and three-zone ActivitySim implementations. The consultant will ensure that only negligible changes to the interface or to user-facing data, configuration, and utility specification files that define current ActivitySim implementations are required in order to benefit from the code updates. The consultant will ensure that all pull requests to ActivitySim include updated source code, documentation and tests.

For each of the two-zone and three-zone ActivitySim examples in the examples repository as of the start date of this task order, the Consultant will:

  • Identify files that need to be modified to run with the new two-zone and three-zone modifications;

  • Implement any modifications to ensure that each example is stable and operational with the new modifications. If consultant discovers any particular ActivitySim example implementations with components that contain extensive incompatibilities, Consultant will ensure that these components still operate correctly, reverting to the existing ActivitySim methods and functionality as necessary. Consultant will work with the consortium and individual agencies to develop a plan for any additional effort to bring the full benefit of our enhancement package to every two-zone and three-zone ActivitySim example implementation;

  • Quantify and document the changes in runtimes and memory requirements resulting from the revisions and extensions to the ActivitySim codebase. To the extent possible, this quantification will leverage the airspeed velocity infrastructure and reporting implemented by the Consultant in an earlier task order. All two-zone and three-zone ActivitySim examples will be tested with “chunking” disabled, and on the same server. AMPO and the ActivitySim partners will work with the Consultant to identify and secure use of sufficient computing hardware resources if the Consultant is unable to do so independently;

  • Verify that the outputs of the two-zone and three-zone ActivitySim example models run with modifications are consistent with outputs of the ActivitySim example models run without Part 1 modifications. Consistency will be demonstrated by repurposing and updating the aggregate model summaries used in the original MTC ActivitySim verification process, as documented here. Note that 100% consistency in disaggregate model outputs is not expected nor a requirement.

The Consultant will provide email and online support to the ActivitySim partners and to the other ActivitySim bench consultants. The Consultant will also coordinate with the other ActivitySim bench consultants and partners to develop a schedule for sequencing and timing of other ActivitySim development and implementation efforts so as leverage the benefits from task.

Deliverables:

  • Pull requests to ActivitySim with updated source code, documentation and tests.
  • Updated, operational two-zone and three-zone ActivitySim examples
  • Verification of updated two-zone and three-zone ActivitySim examples.
  • Email and online support for contributor and agency users.

Schedule: Complete by July 1, 2022

top

Task 4: Performance Enhancement Part 2 / Time Windows

The goals of the Performance Enhancement Part 2: Bring Sharrow to Time Windows task are:

  • To extend the types of revisions and extensions to the ActivitySim code base that reduce ActivitySim's runtime and memory requirements to ActivitySim’s scheduling components, which include customized Python functions to compute available time windows that were not revised as part of the Performance Enhancement Part 1 task.
  • To demonstrate the runtime and memory requirement reductions in the ActivitySim examples present in the project examples repository as of the start date of this task order;
  • To verify that the revised ActivitySim examples produce outputs consistent with those generated without the code revisions and extensions.

The consultant will ensure that only negligible changes to the interface or to user-facing data, configuration, and utility specification files that define current ActivitySim implementations are required in order to benefit from the updates to the scheduling models. The consultant will ensure that all pull requests to ActivitySim include updated source code, documentation and tests.

For each of the ActivitySim example in the examples repository as of the start date of this task order, the Consultant will:

  • Identify files that need to be modified to run with the time window and scheduling modifications;
  • Implement any modifications to ensure that each example is stable and operational with the time window and scheduling model modifications. If consultant discovers any particular ActivitySim example implementations with components that contain extensive incompatibilities, Consultant will ensure that these components still operate correctly, reverting to the existing ActivitySim methods and functionality as necessary.
  • Quantify and document the changes in runtimes and memory requirements resulting from the time window and scheduling revisions and extensions to the ActivitySim codebase. To the extent possible, this quantification will leverage the airspeed velocity infrastructure and reporting implemented by the Consultant in an earlier task order. All ActvitySim examples will be tested with “chunking” disabled, and on the same server. AMPO and the ActivitySim partners will work with the Consultant to identify and secure use of sufficient computing hardware resources if the Consultant is unable to do so independently;
  • Verify that the outputs of the ActivitySim example models run with time window and scheduling model modifications results are consistent with outputs of the ActivitySim example models run without Part 1 modifications. Consistency will be demonstrated by repurposing and updating the aggregate model summaries used in the original MTC ActivitySim verification process, as documented here. Note that 100% consistency in disaggregate model outputs is not expected nor a requirement.

The Consultant will provide email and online support to the ActivitySim partners and to the other ActivitySim bench consultants. The Consultant will also coordinate with the other ActivitySim bench consultants and partners to develop a schedule for sequencing and timing of other ActivitySim development and implementation efforts so as leverage the benefits from task.

Deliverables:

  • Pull requests to ActivitySim with updated source code, documentation and tests.
  • Updated, operational ActivitySim examples
  • Verification of update ActivitySim examples.
  • Email and online support for contributor and agency users.

Schedule: Complete by July 29, 2022

Task 5: School Drop-off and Pickup Model

The goal of this task is to implement with the ActivitySim framework a school escorting / drop-off model which will determine whether children are dropped-off at or picked-up from school, simultaneously with the driver responsible for chauffeuring the children, which children are bundled together on half-tours, and the type of tour (pure escort versus rideshare).

The consultant will prepare and present a slide deck on the proposed school escorting model to the ActivitySim partners and other ActivitySim bench contractors, so that the consortium can learn about the model and review and confirm the overall approach prior to implementation. The Consultant will then draft a product requirement and model design document that addresses any comments received during the initial model review session and upload to the project repository Wiki. RSG will incorporate comments received on draft product requirements and design into a final model design. RSG will then implement the model design in ActivitySim.

The Consultant will implement the model in the SANDAG ActivitySim model example and calibrate the model to the SANDAG data. Once the model is calibrated it will be transferred into the MTC model with the calibrated coefficients from SANDAG. The Consultant will adjust downstream models such as the individual tour frequency model (which will be adjusted to generate significantly fewer escort tours), and the stop frequency and stop purpose models (which will be adjusted to reduce the number of stops generated for school drop-offs and pickups). Stop departure and arrival times will also be adjusted to reflect the removal of these stops. The Consultant will also assess whether other model modifications may be necessary. For example, it is possible that the stop out-of-direction distance may also be affected by removal of school drop-offs and pickups. RSG will analyze observed data and implement an approach to address these downstream impacts as described in the design plan.

Consultant will provide detailed technical documentation of the school escort / drop-off model or methods. Consultant will update the online users guide to include the new submodel and will add the new examples (SANDAG and MTC) and tests to the repository.

Deliverables:

  • Draft and final school escort model product requirement, design and implementation plan, in project repository Wiki (Draft by April 22, comments by April 29, final by May 5; see also School dropoff-pickup model.pptx)
  • Pull request to ActivitySim repo with school escort model source code, documentation, and tests (June 30, 2022)
  • Full scale school escort model implemented and calibrated to SANDAG data and implemented in the MTC model with SANDAG alternative-specific constants (October 31, 2022)

Schedule: Complete by June 30, 2022

Task 6: Disaggregate Accessibilities

The goal of this task is to establish a process to generate a set of accessibilities that are consistent with the actual ActivitySim destination and mode choice models, and which can be used by ActivitySim model components and post-processing procedures such as logsum based benefit cost assessments.

The Consultant will generate a set of disaggregate accessibilities similar to what is implemented in MTC Travel Model 1.5, which can then be used in any ActivitySim model as a substitute for the current aggregate accessibilities. The Consultant will prepare and present a slide deck describing the MTC and SANDAG disaggregate accessibility calculators and outlining a proposed approach for ActivitySim. Consultant will then develop a model implementation plan, incorporating feedback from the consortium, that will address:

  • Population segments (household and person variables) to include in the synthetic population and which combinations of purposes, departure and arrival times, and modes to calculate accessibilities over.
  • User interface for the population\tour generator and level of configurability
  • Other options to consider such as whether to provide the ability to output mode choice logsums at a TAZ and/or district level for use in land-use models and/or as a substitute for tour specific mode choice logsums in destination choice. RSG will integrate the calculator with the MTC ActivitySim model and update one of the model components to use a disaggregate accessibility to ensure that the process works as anticipated. RSG is re-estimating the ActivitySim models as part of the SANDAG ABM3 deployment and will use the disaggregate accessibility calculator to refresh the accessibility coefficients used in ActivitySim which would then be made available to other implementations.

Deliverables:

  • Draft and final disaggregate accessibility design and implementation plan, in project repository Wiki (Draft by April 15, comments by April 22, final by April 29; also see Disaggregate accessibilities.pptx)
  • Pull request to the ActivitySim repo with disaggregate accessibility source code, documentation, and tests (June 10)
  • Full scale MTC test model with disaggregate accessibilities implemented and verified (July 8)

Schedule: Complete by July 8, 2022

Task 7: Revised Shadow Pricing Mechanism

The purpose of this task is to improve the computational efficiency and the better align the spatial distribution of total workers across all segments with the spatial distribution of total employment.

In order to address these issues, the Consultant will update the ActivitySim shadow pricing code to replace the size term adjustment factors with one set of alternative-specific constants (by zone) that will be calibrated based on a comparison of total scaled workers compared to total employment. This will ensure that the workplace location choice model matches total employment rather than scaled workers by size term segment. The consultant will also implement a method where in each iteration after the first iteration, the workplace location choice model will re-simulate a random sample drawn from workers who chose to work in "over-subscribed" zones. The model will re-choose a workplace for these workers after eliminating all zones where the number of scaled workers in the last iteration is equal to or over total employment in the zone, accounting for the fact that some jobs are “consumed” by out of region workers and some workers commute out of the region. It is anticipated that these changes will significantly reduce the computational burden required to match input employment and ensure a closer match to input employment data. A similar method will be implemented for school location choice, where constants will be calibrated by school type segment. Users will be given the flexibility to run either the existing procedure or the revised procedure. RSG will document and compare the convergence properties, validation and runtimes of the revised methods against the existing methods, using the Bay Area full scale model as the example.

Deliverables:

  • Slide deck on mandatory location choice model shadow pricing revision (complete; Shadow pricing.pptx)
  • Pull request to the ActivitySim repo with revised shadow pricing source code, documentation, and tests (July 1)
  • Full scale test model with revised shadow pricing procedure implemented and verified (July 30)

Schedule: Complete by July 30, 2022

Task 8: Extend ActivitySim Code to Enable More Flexible Number of Tours and Stops

ActivitySim currently hard codes the number of possible tour and stop frequency alternatives. For example, the maximum number of mandatory tours a person is allowed to take is two: two work tours, two school tours, or one work and one school. Any tour or trip combinations that do not fit within the currently specified alternatives are not allowed. This can be limiting when processing survey data through ActivitySim’s estimation mode where any tours or trips that do not fall within the acceptable alternatives must be removed or ActivitySim will throw an error. Approximately 8% of the tours in the Southeast Michigan Council of Governments travel survey had to be removed from the dataset due to being outside of the available tour frequencies. Travel surveys that include GPS tracking also show an increase in the number of intermediate stops compared to self-reported surveys which were common when CT-RAMP was initially developed. Improving the ActivitySim code to be more flexible with the tour and stop frequency alternatives would allow for more user flexibility when processing survey data and more faithful modeling of observed travel patterns.

Under the hood, tour and trip frequencies are closely tied to tour and trip IDs, and those IDs to the random number generator. (This primarily happens in the util/canonical_ids.py code.) Restructuring this code to gather the available alternatives from the supplied ActivitySim configuration files would allow the user the ability to change the allowed alternatives by changing the configuration files. If the user wishes to allow for three work tours, they would simply add an alternative to the mandatory_tour_frequencies.csv file with the name “work3” and supply their desired utility function for that alternative. ActivitySim would be enhanced to be smart and flexible enough to read the headers of the corresponding configuration files, understand the allowed alternatives, and handle the tour and trip ID creation in a stable and consistent manner. It should be noted that this enhancement would also allow for the tours and stops created by the school pickup/drop-off model described in Task 5.

Deliverables:

  • Pull request with updated ActivitySim source code and documentation (June 15, 2022)
  • Verified test model with tour and stop frequency alternative extensions example (July 31, 2022)

Schedule: Complete by July 31, 2022

top