Park-and-ride lot choice and capacity

[dhensle]

Code changes for #965

[jpn--]

@copilot resolve the merge conflicts in this pull request

[jpn--]

Mostly good. That several agencies have collaborated and tested this already gives some extra confidence. Only a couple minor bugs/concerns to address.

[Copilot]

Pull request overview

Implements explicit Park-and-Ride (PnR) lot choice and capacity-constrained iteration with tour mode choice, and extends skimming/logsum/matrix-writing infrastructure so PnR auto/transit legs can be modeled and reported without relying on expensive precomputed PnR skim sets.

Changes:

• Added a new park_and_ride_lot_choice model plus ParkAndRideCapacity helper to iterate tour mode choice until PnR lots are within capacity.
• Extended skim plumbing (flow, logsums, tour scheduling logsums) to support origin→lot and lot→destination skims and optional inclusion of PnR in logsum computation.
• Updated trip matrix writing to support table-specific origin/destination columns (enabling PnR leg matrix outputs) and added tests for both PnR iteration and matrix writing behavior.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
activitysim/core/util.py	Keeps pnr_lot_dest_col_name columns when dropping unused chooser columns.
activitysim/core/steps/output.py	Adjusts data dictionary text formatting width calculation.
activitysim/core/mp_tasks.py	Allocates shared multiprocessing buffers for PnR capacity iteration when configured.
activitysim/core/flow.py	Adds support for PnR lot destination column and additional PnR skim relationships.
activitysim/core/configuration/logit.py	Adds settings flags for at-work PnR and optional PnR inclusion in logsums.
activitysim/abm/test/test_misc/test_tour_mode_choice_simulate.py	New integration-style tests for tour mode choice with/without PnR iteration.
activitysim/abm/test/test_misc/test_park_and_ride_models.py	New unit tests for PnR lot choice filtering, utilities, and capacity synchronization logic.
activitysim/abm/tables/disaggregate_accessibility.py	Updates nearest accessibility zone helper signature to accept model settings.
activitysim/abm/models/util/vectorize_tour_scheduling.py	Integrates optional PnR lot choice into tour scheduling logsum computation and centralizes skim setup.
activitysim/abm/models/util/test/test_write_matrices.py	New tests validating matrix writing with custom OD columns for PnR legs.
activitysim/abm/models/util/school_escort_tours_trips.py	Tightens integer casting to explicit int64 dtype.
activitysim/abm/models/util/park_and_ride_capacity.py	New multiprocessing-aware PnR capacity accounting and chooser resampling logic.
activitysim/abm/models/util/logsums.py	Adds shared setup_skims helper and optional PnR lot choice during logsum creation.
activitysim/abm/models/trip_matrices.py	Supports per-table origin/destination columns and accumulating repeated table names into a single matrix.
activitysim/abm/models/tour_mode_choice.py	Adds iterative PnR capacity-constrained tour mode choice and reuses shared skim setup.
activitysim/abm/models/park_and_ride_lot_choice.py	New PnR lot choice model implementation and settings schema.
activitysim/abm/models/disaggregate_accessibility.py	Adds NEAREST_ZONE_SKIM configuration for nearest-zone selection behavior.
activitysim/abm/models/atwork_subtour_mode_choice.py	Adds optional at-work subtour PnR lot choice integration and shared skim setup.
activitysim/abm/models/init.py	Registers the new park_and_ride_lot_choice model module.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dhensle]

@jpn-- I have address all the comments and merged in the latest main code. I think this should be ready to merge (assuming all the tests pass as expected)

[jpn--]

A re-review found a few more issues.

1. Resampled PnR lot choices are not written back to tours.

   final_choices is updated before pnr_zone_id is attached to choices_i; subsequent lot choices modify only the merged choosers frame. At completion, only final_choices is assigned back to tours. Thus a tour’s mode can be calculated using a newly selected lot while downstream outputs retain its original lot. That undermines both capacity results and the new PnR-leg matrices.

2. PnR-enabled mandatory-tour scheduling logsums use the wrong destination column.

   _compute_logsums runs lot choice with hard-coded choosers_dest_col_name="destination" before resolving DESTINATION_FOR_TOUR_PURPOSE. Mandatory scheduling normally uses workplace_zone_id or school_zone_id, so enabling include_pnr_for_logsums will access a missing/wrong column.

3. RESAMPLE_STRATEGY: random remains incorrect.

   Under multiprocessing, choices_synced and probs contain tours from every process, but each subprocess RNG channel contains only its local tour IDs. random_for_df(probs) therefore tries to locate foreign IDs in local RNG state and raises KeyError. Even single-process sampling uses occupancy / capacity - 1. On the initial pass, the rate needed to remove the expected excess is (occupancy - capacity) / occupancy. For occupancy 3 and capacity 2, the code uses 0.5 rather than 1/3; for 4 and 2 it resamples everyone rather than half.

I pushed a commit that includes tests demonstrating all three problems. Then I pushed a commit with fixes. @dhensle if you approve I will merge this.

[dhensle]

These are good catches and the fixes look good. Thanks @jpn--. I approve and think this is ready for merge!

[bhargavasana]

I would like to record this comment for future PRs. I think it would be great to include at least a basic https://github.com/ActivitySim/activitysim/tree/main/docs update for a major feature like this. SANDAG is also interested in this feature, but I am not sure what exactly has been implemented and how exactly to use it. Maybe agencies already using this feature can contribute for the benefit of other members.
cc @bwentl @bettinardi @stefancoe @joecastiglione