ABM3 Intra-Household AV Allocation and Taxi/TNC Routing Models

docs/design/demand/av-routing.md

@@ -0,0 +1,88 @@
+# Autonomous Vehicle (AV) Routing Model
+
+The AV routing model simulates how household-owned autonomous vehicles are dispatched to serve household members' travel needs throughout the day. This model runs as a post-processing step after the resident model generates trips for households that own autonomous vehicles.
+
+## Model Overview
+
+The AV routing model performs intra-household autonomous vehicle routing, determining which trips are served by the household's AV(s) and how the vehicles reposition between trips. The model operates on a time-period basis, processing trips chronologically throughout the simulated day.
+
+The model design is shown below:
+
+![](../../images/design/av_routing_model_design.png)
+
+## Model Components
+
+### AV-Trip Matching
+
+For each time period, the model matches available household AVs to trips that need to be served. The matching process:
+
+1. **Identifies eligible trips**: Selects driving-mode trips from households with AVs
+2. **Constructs alternatives**: Creates all possible AV-to-trip assignments within the household
+3. **Evaluates utilities**: Uses skim data (travel time from vehicle location to trip origin) and other factors to score each assignment
+4. **Makes choices**: Selects the optimal assignment of trips to AVs using a logit model
+
+If multiple trips exist on the same tour during a time period, both trips are served by the same AV. If the AV is not at the trip origin, an additional repositioning trip is added.
+
+### AV Repositioning
+
+After serving trips, the model determines where each AV should go next. The repositioning alternatives include:
+
+1. **Stay with person**: The AV waits at the current location with the person it just dropped off
+2. **Go home**: The AV returns to the household's home location
+3. **Go to remote parking**: The AV travels to a designated parking zone (useful in areas with limited parking)
+4. **Service next household trip**: The AV proactively repositions to the origin of an upcoming trip for another household member
+
+The repositioning choice is made using a utility-based model that considers:
+- Travel time to each alternative destination
+- Time until the next potential trip
+- Parking availability at the current location
+
+## Vehicle Trip Types
+
+The model generates several types of vehicle trips:
+
+| Trip Type | Description |
+|-----------|-------------|
+| `serving_trip` | AV traveling with a passenger to their destination |
+| `going_home` | Empty AV returning to home location |
+| `going_to_parking` | Empty AV traveling to remote parking |
+| `repositioning` | Empty AV traveling to serve an upcoming trip |
+
+## Outputs
+
+The AV routing model produces:
+
+- **AV Vehicle Trips Table**: A record of all vehicle movements including:
+  - Vehicle ID and household ID
+  - Origin and destination zones
+  - Departure time
+  - Whether the trip is a deadhead (empty) trip
+  - Trip type (serving, repositioning, etc.)
+
+## Relationship to Other Models
+
+The AV routing model depends on outputs from the [resident model](resident.md), specifically the trip list for households with AVs. It uses skim matrices generated during the travel model run to evaluate travel times for both serving trips and repositioning trips.  The AV routing model runs as part of the resident model between trip mode choice and parking location choices models.
+
+## Integration with Traffic Assignment
+
+The AV vehicle trips are aggregated into origin-destination matrices for traffic assignment:
+
+- **EmptyAVTrips.omx**: Contains deadhead/repositioning trips by time period
+  - `EmptyAV_EA`, `EmptyAV_AM`, `EmptyAV_MD`, `EmptyAV_PM`, `EmptyAV_EV`
+
+These matrices are imported alongside other demand matrices in the traffic assignment process. See the matrix builder (src/asim/scripts/taxi_tnc_routing/tnc_av_matrix_builder.py) for details on how these matrices are created.
+
+ActivitySim resident model output matrices account for the trips served by AVs, so only the deadhead trips need to be added separately in this step.
+
+## Configuration
+
+The AV routing model is configured through `av_routing.yaml` with key settings including:
+
+- `AV_TRIP_MATCHING_SPEC`: Specification file for AV trip matching model
+- `AV_TRIP_MATCHING_COEFFICIENTS`: Coefficients file for AV trip matching model
+- `AV_REPOSITIONING_SPEC`: Specification file for AV repositioning model
+- `AV_REPOSITIONING_COEFFICIENTS`: Coefficients file for AV repositioning model
+- `DRIVING_MODES`: List of trip modes eligible for AV routing
+- `AV_PARKING_ZONE_COLUMN`: Land use column indicating remote AV parking availability
+- `NEAREST_ZONE_SKIM`: Skim matrix used to find nearest parking zones
+

docs/design/demand/resident.md

@@ -88,5 +88,5 @@ flowchart TD
 ```
 
 
-At this point, all tours are generated, scheduled, have a primary destination, and a selected tour mode. The next set of models fills in details about the tours - number of intermediate stops, location of each stop, the departure time of each stop, and the mode of each trip on the tour. Finally, the parking location of each auto trip to the central business district (CBD) is determined.
+At this point, all tours are generated, scheduled, have a primary destination, and a selected tour mode. The next set of models fills in details about the tours - number of intermediate stops, location of each stop, the departure time of each stop, and the mode of each trip on the tour. For households that own autonomous vehicles, an additional [AV Routing Model](av-routing.md) is run after the resident model completes. This model simulates how household AVs are dispatched to serve household members' trips throughout the day. Finally, the parking location of each auto trip to the central business district (CBD) is determined.
 After the model is run, the output files listed above are created. The trip lists are then summarized into origin-destination matrices by time period and vehicle class or transit mode and assigned to the transport network.

docs/design/demand/taxi-tnc-routing.md

@@ -0,0 +1,125 @@
+# Taxi and TNC Routing Model
+
+The Taxi and Transportation Network Company (TNC) routing model simulates the operation of for-hire vehicle fleets serving passenger trips. This model processes TNC and taxi trips generated by the activity-based demand models and creates realistic vehicle routing patterns including pooled rides, empty repositioning, and refueling trips.
+
+## Model Overview
+
+The model operates as a microsimulation of a taxi/TNC fleet, processing trips in chronological order through fine-grained time bins. Key features include:
+
+- **Trip pooling**: Matches compatible shared-ride requests to reduce vehicle miles traveled
+- **Vehicle dispatching**: Assigns vehicles to trips based on proximity and availability  
+- **Fleet management**: Tracks vehicle locations, mileage, and refueling needs
+- **Deadhead routing**: Simulates empty vehicle repositioning between trips
+
+The model design is shown below:
+
+![](../../images/design/taxi_tnc_model_design.png)
+
+## Model Components
+
+### Trip Pooling
+
+For shared TNC modes, the model identifies opportunities to combine multiple passenger trips into a single vehicle route:
+
+1. **Proximity filtering**: Finds trip pairs where both origins and destinations are within a configurable buffer (default: 10 minutes)
+2. **Detour calculation**: Evaluates four possible routing scenarios for each pair:
+
+    - Origin i → Origin j → Destination i → Destination j
+    - Origin j → Origin i → Destination j → Destination i  
+    - Origin i → Origin j → Destination j → Destination i
+    - Origin j → Origin i → Destination i → Destination j
+
+3. **Detour validation**: Filters out pairs where either passenger's detour exceeds the maximum allowed (default: 15 minutes)
+4. **Mutual best selection**: Uses a recursive algorithm to select trip pairs where both trips prefer each other
+
+### Vehicle Dispatching
+
+The model maintains a fleet of vehicles and matches them to trips:
+
+- **Free vehicles**: Vehicles that have completed their previous trip are matched to new trips based on proximity
+- **New vehicles**: When no free vehicle is available within the maximum wait time, a new vehicle is created at the trip origin
+- **Wait time tracking**: Records the time passengers wait for vehicle arrival
+
+### Occupancy Tracking
+
+Vehicle occupancy is tracked for each trip leg:
+
+| Occupancy | Description |
+|-----------|-------------|
+| 0 | Empty/deadhead trip (repositioning or refueling) |
+| 1 | Single passenger (or driver in non-AV scenario) |
+| 2 | Two passengers |
+| 3+ | Three or more passengers |
+
+### Refueling
+
+The model tracks cumulative vehicle mileage and routes vehicles to refueling stations when needed:
+
+- Vehicles exceeding the maximum distance threshold are routed to the nearest zone with refueling stations
+- Refueling trips are marked as deadhead trips with occupancy 0
+- After refueling, the vehicle's odometer is reset
+
+## Configuration
+
+Key settings in `taxi_tnc_routing_settings.yaml`:
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `time_bin_size` | Simulation time bin size (minutes) | 10 |
+| `pooling_buffer` | Max O-O and D-D time for pooling (minutes) | 10 |
+| `max_detour` | Maximum detour time for pooled trips (minutes) | 15 |
+| `max_wait_time` | Maximum wait before creating new vehicle (minutes) | 15 |
+| `max_refuel_dist` | Maximum distance before refueling (miles) | 300 |
+| `shared_tnc_modes` | Modes eligible for pooling | TNC_SHARED |
+| `single_tnc_modes` | Solo ride modes | TNC_SINGLE, TAXI |
+
+## Outputs
+
+The model produces several output files:
+
+### TNC Vehicle Trips (`output_tnc_vehicle_trips.csv`)
+
+Each row represents a vehicle trip leg with columns:
+- `vehicle_id`: Unique vehicle identifier
+- `origin_taz`, `destination_taz`: Trip endpoints (TAZ level)
+- `depart_bin`: Departure time bin
+- `occupancy`: Number of passengers
+- `trip_type`: pickup, dropoff, refuel, etc.
+- `is_deadhead`: Whether the trip is empty
+
+### Pooled Trips (`output_tnc_pooled_trips.csv`)
+
+Details of matched trip pairs including:
+- Trip IDs for both passengers
+- Route scenario used
+- Detour times for each passenger
+- Stop sequence
+
+This file is useful for analyzing pooling efficiency and general debugging of the pooling algorithm.
+
+## Integration with Traffic Assignment
+
+TNC vehicle trips are aggregated into origin-destination matrices:
+
+- **TNCVehicleTrips_pp.omx**: One file per period with occupancy-based cores
+  - `TNC_EA_0`, `TNC_EA_1`, `TNC_EA_2`, `TNC_EA_3` (and similar for AM, MD, PM, EV)
+
+The matrix builder script (`tnc_av_matrix_builder.py`) reads the vehicle trip outputs and creates OMX matrices that are imported into traffic assignment alongside other demand matrices.
+
+## Relationship to Other Models
+
+### Upstream Dependencies
+
+- **Resident Model**: Generates TNC_SINGLE, TNC_SHARED, and TAXI trips
+- **Visitor Model**: Generates visitor TNC/taxi trips
+- **Cross-border Model**: Generates cross-border TNC/taxi trips
+- **Airport Model**: Generates airport ground access TNC/taxi trips
+
+### Downstream Integration
+
+The vehicle trip outputs can be used for:
+
+- Traffic Assignment: TNC vehicle matrices are assigned to the highway network
+- Fleet sizing analysis
+- VMT and emissions calculations
+- Equity analysis of service availability

mkdocs.yml

@@ -60,6 +60,8 @@ nav:
         - design/demand/visitor.md
         - design/demand/cvm.md
         - design/demand/external.md
+        - design/demand/av-routing.md
+        - design/demand/taxi-tnc-routing.md
     - Supply: 
         - design/supply/index.md
         - design/supply/bike-logsums.md

src/asim/configs/common/constants.yaml

@@ -89,6 +89,9 @@ autoParkingCostFactorAV: {policy-AV-autoParkingCostFactor:}
 autoCostPerMileFactorAV: {policy-AV-autoCostPerMileFactor:}
 autoTerminalTimeFactorAV: {policy-AV-autoTerminalTimeFactor:}
 minAgeDriveAloneAV: {policy-AV-minAgeDriveAlone:}
+AV_maxDuration: 1.5 # max duration for keeping car close (hrs)
+AV_maxBenefit: 60 # max benefit for keeping car close (mins)
+RemoteParkingCostPerHour: 3  #dollar
 
 
 #valueOfTime: 8.00

src/asim/configs/resident/av_repositioning.csv

@@ -0,0 +1,31 @@
+Label,Description,Expression,stay_with_person,go_to_parking,go_home,service_next_trip_1,service_next_trip_2,service_next_trip_3
+# stay with person utils,,,,,,,,
+util_cost_of_parking,Cost of parking at destination,parkingCost,coef_cost,,,,,
+util_time_stay,Stay- Need car soon,"@np.where(df.duration_hrs < df.AV_maxDuration, (-1)*(df.AV_maxBenefit + (df.duration_hrs*df.slope)), 0)",coef_ivt,,,,,
+# go to parking utils,,,,,,,,
+util_remote_park_only_if_park_const,Can only use remote parking if in parking constrained zone,~parkingConstrained,,coef_unavailable,,,,
+util_time_go_to_parking,Remote- Need car soon,"@np.where(df.duration_hrs < df.AV_maxDuration, (-1)*(df.AV_maxBenefit + (df.duration_hrs*df.slope)), 0)",,coef_ivt,,,,
+util_remote_cost,Remote park - Cost of parking until departure,duration_hrs * RemoteParkingCostPerHour * 100,,coef_cost,,,,
+util_remote_ivt,in vehicle time to remote parking location,@v_to_parking_skim['SOV_TR_H_TIME'],,coef_ivt,,,,
+util_remote_rel,reliability vehicle location to remote parking location,"@v_to_parking_skim['SOV_TR_H_REL'] * 14 / np.maximum(0.1, v_to_parking_skim['SOV_TR_H_DIST'])",,coef_ivt,,,,
+util_remote_auto_cost,auto operating cost from vehicle location to remote parking location,@(v_to_parking_skim['SOV_TR_H_DIST'] * costPerMile * autoCostPerMileFactorAV) + v_to_parking_skim['SOV_TR_H_TOLLCOST'],,coef_cost,,,,
+# go home utils,,,,,,,,
+util_already_at_home,Unavailable if already at home destination,destination == home_zone_id,,,coef_unavailable,,,
+util_home_ivt,in vehicle time to go home,@v_to_home_skim['SOV_TR_H_TIME'],,,coef_ivt,,,
+util_home_rel,reliability vehicle location to home,"@v_to_home_skim['SOV_TR_H_REL'] * 14 / np.maximum(0.1, v_to_home_skim['SOV_TR_H_DIST'])",,,coef_ivt,,,
+util_home_auto_cost,auto operating cost from vehicle location to home,@(v_to_home_skim['SOV_TR_H_DIST'] * costPerMile * autoCostPerMileFactorAV) + v_to_home_skim['SOV_TR_H_TOLLCOST'],,,coef_cost,,,
+# service next trip util 1,,,,,,,,
+util_next_trip_available,Unavailable if no next trip,next_trip_id_1 == -1,,,,coef_unavailable,,
+util_next1_ivt,in vehicle time to next trip 1 origin,v_to_trip_orig1_time,,,,coef_ivt,,
+util_next1_rel,reliability vehicle location to next trip 1 origin,"@df.v_to_trip_orig1_rel * 14 / np.maximum(0.1, df.v_to_trip_orig1_dist)",,,,coef_ivt,,
+util_next1_auto_cost,auto operating cost from vehicle location to next trip 1 origin,@(df.v_to_trip_orig1_dist * costPerMile * autoCostPerMileFactorAV) + df.v_to_trip_orig1_toll,,,,coef_cost,,
+# service next trip util 2,,,,,,,,
+util_next_trip_available,Unavailable if no next trip,next_trip_id_2 == -1,,,,,coef_unavailable,
+util_next2_ivt,in vehicle time to next trip 2 origin,v_to_trip_orig2_time,,,,,coef_ivt,
+util_next2_rel,reliability vehicle location to next trip 2 origin,"@df.v_to_trip_orig2_rel * 14 / np.maximum(0.2, df.v_to_trip_orig2_dist)",,,,,coef_ivt,
+util_next2_auto_cost,auto operating cost from vehicle location to next trip 2 origin,@(df.v_to_trip_orig2_dist * costPerMile * autoCostPerMileFactorAV) + df.v_to_trip_orig2_toll,,,,,coef_cost,
+# service next trip util 3,,,,,,,,
+util_next_trip_available_3,Unavailable if no next trip 3,next_trip_id_3 == -1,,,,,,coef_unavailable
+util_next3_ivt,in vehicle time to next trip 3 origin,v_to_trip_orig3_time,,,,,,coef_ivt
+util_next3_rel,reliability vehicle location to next trip 3 origin,"@df.v_to_trip_orig3_rel * 14 / np.maximum(0.3, df.v_to_trip_orig3_dist)",,,,,,coef_ivt
+util_next3_auto_cost,auto operating cost from vehicle location to next trip 3 origin,@(df.v_to_trip_orig3_dist * costPerMile * autoCostPerMileFactorAV) + df.v_to_trip_orig3_toll,,,,,,coef_cost

src/asim/configs/resident/av_repositioning_coefficients.csv

@@ -0,0 +1,4 @@
+coefficient_name,value,constrain
+coef_unavailable,-999.0,F
+coef_ivt,-0.03,F
+coef_cost,-0.002,F

src/asim/configs/resident/av_repositioning_preprocessor.csv

@@ -0,0 +1,50 @@
+Description,Target,Expression
+next trip start time,next_depart,df['trip_id'].map(trips.groupby('tour_id')['depart'].shift(-1).to_dict())
+trip duration,duration_hrs,"np.where(next_depart.isna(), 0, next_depart - df.depart) / 2"
+duration benefit,duration_benefit,"np.where((duration_hrs < 1.5) & (duration_hrs > 0), 60 - (60/1.5 * duration_hrs), 0)"
+#Parking cost calculation,,
+,tour_id,"reindex(trips.tour_id, df.trip_id)"
+,tour_type,"reindex(tours.tour_type, tour_id)"
+,person_id,"reindex(trips.person_id, df.trip_id)"
+,ptype,"reindex(persons.ptype, person_id)"
+,free_parking_at_work,"reindex(persons.free_parking_at_work,  person_id)"
+,free_parking_available,(tour_type == 'work') & free_parking_at_work
+,number_of_participants,"reindex(tours.number_of_participants, tour_id)"
+,is_indiv,(number_of_participants == 1)
+person has free on-site parking at workplace,freeOnsite,"(free_parking_available)*np.where(is_indiv,1,0)"
+new reimbursement amount,reimburseProportion,0
+new daily parking cost with reimbursement,parkingCostDayDollars,"reindex(land_use.exp_daily, df.destination)"
+new hourly parking cost with reimbursement,parkingCostHourDollars,"reindex(land_use.exp_hourly, df.destination)"
+new monthly parking cost with reimbursement,parkingCostMonthDollars,"reindex(land_use.exp_monthly, df.destination)"
+daily cost converted to cents,parkingCostDay,parkingCostDayDollars*100
+hourly cost converted to cents,parkingCostHour,parkingCostHourDollars*100
+monthly cost converted to cents,parkingCostMonth,parkingCostMonthDollars*100
+Trip parking cost for full-time workers and university students,_parkingCostBeforeReimb,"ptype.isin([1,3]).values * is_indiv * np.minimum(parkingCostMonth/22, parkingCostDay)"
+Trip parking cost for full-time workers and university students,_parkingCostBeforeReimb,"ptype.isin([1,3]).values * is_indiv * np.minimum(_parkingCostBeforeReimb, parkingCostHour * duration_hrs)"
+,is_joint,(number_of_participants > 1)
+Trip parking cost for other person types,parkingCostBeforeReimb,"np.where((~ptype.isin([1,3]).values * is_indiv) | (is_joint), np.minimum(parkingCostDay, parkingCostHour * duration_hrs), _parkingCostBeforeReimb)"
+Reimbursement applies to this tour purpose,reimbursePurpose,tour_type=='work'
+Effective parking cost for free parkers,_parkingCost,"0 * np.where(reimbursePurpose*freeOnsite,1,0)"
+Effective parking cost for reimbursed parkers,_parkingCost,"np.where(is_indiv*reimbursePurpose*(1-freeOnsite), np.maximum((1-reimburseProportion) * parkingCostBeforeReimb, 0),_parkingCost)"
+Effective parking cost,parkingCost,"np.where(is_joint+is_indiv*(1-reimbursePurpose), parkingCostBeforeReimb,_parkingCost)"
+Parking cost is 0 if going home,parkingCost,"np.where(df.destination == df.home_zone_id, 0, parkingCost)"
+# These following two are from AutonomousVehicleAllocationChoice.xls,,
+Maximim benefit for keeping car close (min),AV_maxBenefit,60
+Maximum duration for keeping car close (hrs),AV_maxDuration,1.5
+Slope of benefit calculation,slope, (-1)*(AV_maxBenefit / AV_maxDuration)
+# below taken from parametersByYear.csv,,
+,RemoteParkingCostPerHour,0.81
+#,,
+,parkingConstrained,"reindex(land_use.parking_type,df.destination)==1"
+,v_to_trip_orig1_time,"np.where(df.next_trip_id_1 > 0, v_to_trip_orig1_skim['SOV_TR_H_TIME'], 0)"
+,v_to_trip_orig2_time,"np.where(df.next_trip_id_2 > 0, v_to_trip_orig2_skim['SOV_TR_H_TIME'], 0)"
+,v_to_trip_orig3_time,"np.where(df.next_trip_id_3 > 0, v_to_trip_orig3_skim['SOV_TR_H_TIME'], 0)"
+,v_to_trip_orig1_dist,"np.where(df.next_trip_id_1 > 0, v_to_trip_orig1_skim['SOV_TR_H_DIST'], 0)"
+,v_to_trip_orig2_dist,"np.where(df.next_trip_id_2 > 0, v_to_trip_orig2_skim['SOV_TR_H_DIST'], 0)"
+,v_to_trip_orig3_dist,"np.where(df.next_trip_id_3 > 0, v_to_trip_orig3_skim['SOV_TR_H_DIST'], 0)"
+,v_to_trip_orig1_rel,"np.where(df.next_trip_id_1 > 0, v_to_trip_orig1_skim['SOV_TR_H_REL'], 0)"
+,v_to_trip_orig2_rel,"np.where(df.next_trip_id_2 > 0, v_to_trip_orig2_skim['SOV_TR_H_REL'], 0)"
+,v_to_trip_orig3_rel,"np.where(df.next_trip_id_3 > 0, v_to_trip_orig3_skim['SOV_TR_H_REL'], 0)"
+,v_to_trip_orig1_toll,"np.where(df.next_trip_id_1 > 0, v_to_trip_orig1_skim['SOV_TR_H_TOLLCOST'], 0)"
+,v_to_trip_orig2_toll,"np.where(df.next_trip_id_2 > 0, v_to_trip_orig2_skim['SOV_TR_H_TOLLCOST'], 0)"
+,v_to_trip_orig3_toll,"np.where(df.next_trip_id_3 > 0, v_to_trip_orig3_skim['SOV_TR_H_TOLLCOST'], 0)"