diff --git a/docs/design.md b/docs/design.md index bb37ae75f..f047e8071 100644 --- a/docs/design.md +++ b/docs/design.md @@ -1,6 +1,6 @@ # Model Design -The ABM3 model system is primarily based on the [ActivitySim](https://research.ampo.org/activitysim/) platform; ActivitySim is used to model resident travel, cross-border travel, overnight visitor travel, airport ground access travel, and commercial vehicle travel including light, medium, and heavy commercial vehicles. Aggregate models are used to model external-internal travel (from external stations other than the U.S./Mexico border crossing) and through travel. The model system relies on [EMME](https://www.bentley.com/software/emme/) software for network processing, skimming, and assignment. Models are mostly implemented in [Python](https://www.python.org/), and some models are implemented in Java (https://www.java.com/en/). +The ABM3 model system is primarily based on the [ActivitySim](https://research.ampo.org/activitysim/) platform; ActivitySim is used to model resident travel, cross-border travel, overnight visitor travel, airport ground access travel, and commercial vehicle travel including light, medium, and heavy commercial vehicles. Aggregate models are used to model external-internal travel (from external stations other than the U.S./Mexico border crossing) and through travel. The model system relies on [EMME](https://www.bentley.com/software/emme/) software for network processing, skimming, and assignment. Models are mostly implemented in [Python](https://www.python.org/), and some models are implemented in [Java] (https://www.java.com/en/). The overall design of the model is shown in the figure below. @@ -43,6 +43,136 @@ After the model is run, the output files listed above are created. The trip list ## Crossborder Model +The Cross-Border Travel Model predicts travel made by residents of Mexico within San Diego County. It predicts the border crossing point of entry as well as all trips made within the county. The model is limited to simulating travel made by Mexican residents who return to Mexico within the simulation day. Cross-border travel not captured by the Cross-Border Model includes: + +* Residents of San Diego County who travel to/from Mexico. This travel is represented +by the resident travel model. +* Residents of Mexico (including U.S. citizens) who travel into San Diego County and who +do not return to Mexico at the end of the day. This travel is represented in the overnight +visitor travel model. +* Travel between points of entry through San Diego County to other U.S. destinations. This +travel is represented by the external-external travel model. +* Commercial vehicle travel to/from points of entry. This travel is represented by the +commercial vehicle model. + +The overall design of the model is shown in the figure below. + +![](images/design/crossborder_model_design.png) + +### Crossborder Model Purpose Definitions +There are five activity purposes in the cross-border travel demand model. +* Work: Any activity involving work for pay. +* School: Pre-k school, K-12, college/university, or trade school. +* Shop: Shopping at retail, wholesale, etc. +* Visit: Visiting friends or family +* Other: A broad category including eating out, medical appointments, recreational activities, etc. + +Note that home activities are not listed, since we do not model activities south of the border. + +### Crossborder Model Mode Definitions + +The model has the following mode types at the trip level: +* Drive-alone: Single occupant private vehicle +* Shared 2: A private vehicle with exactly two passengers +* Shared 3+: A private vehicle with three or more passengers +* Walk: Walk mode +* Bike: Bike mode +* Walk-transit: Walk access to transit. There are three sub-types of transit: Local only, +premium only, local + premium (which includes both local and premium services in the +transit path) +* Taxi: Door-to-door taxi trip +* Single-pay TNC: Door-to-door TNC trip with a single payer (e.g. UberX) +* Shared-pay TNC: Stop-to-stop TNC trip with potentially multiple payers (e.g. UberPool) + +We also model tour mode, which is the mode used to cross the border. These modes include +drive-alone, shared 2, shared 3+ and walk. We assume that anyone crossing by bus or taxi is +similar to walk, since they do not have access to a personal vehicle for the rest of their travel in +San Diego County. + +We also classify border crossings by lane type: general purpose, SENTRI, and Ready. We +assume that the use of these lanes is related to the border crossing party; we attribute each party with SENTRI or Ready availability. The proportion of total border crossing parties with access to SENTRI and Ready lanes are based on observed survey data, pooled across all stations. This data is used to simulate the availability of the lane to the travel party. Each lane crossing type is related to the wait time that the travel party experiences at each border crossing station by mode. + +Below is a general description of the model structure. + +1. Tour Enumeration: A list of person-tours is created by first cross-multiplying the input total +person tours with the share of tours by pass type, then expanding tours by pass type to tours +by pass type and purpose. +2. Tour Level Models +2.1 Time-of-day Choice: Each person-tour is assigned an outbound and return half-hour +period. +2.2 Primary Destination and Station Choice: Each border crossing person-tour chooses a +primary destination MGRA and border crossing station. +2.3 Border Crossing Mode Choice: Each person-tour chooses a border crossing tour mode. +3. Wait Time Model +3.1. Wait time model: Calculate wait time based on demand at each POE from model 2.2 +3.2. Convergence check: If max iterations reached (currently 3), goto Stop and Trip level +models, else goto Model 2.2 +4. Stop and Trip Level Models +4.1 Stop Frequency Choice: Each person-tour is assigned number of stops by half-tour +(outbound, return). +4.2 Stop Purpose Choice: Each stop is assigned a stop purpose (consistent with the tour +purposes). +4.3 Trip Departure Choice: Each trip is assigned a half-hourly time period. +4.4 Stop Location Choice: Each stop chooses an MGRA location. +4.5 Trip Mode Choice: Each trip is assigned a trip mode. +4.6 Trip Assignments: Trips are assigned to networks, along with resident and other special +market trip tables, and skims are created for the next iteration of the model. + +For more information on the Crossborder Travel Model see technical documentation. + ## Airport Ground Access Models +There are two airport ground access models - one for San Diego International Airport and one for the Crossborder Express terminal which provides access to Tijuana International Airport from the United States. Both models use the same structure and software code, though the parameters that control the total number of airport travel parties, off-airport destination, mode, arrival and departure times, and other characteristics, vary for each airport according to survey and airport-specific data. +The airport ground access model simulates trips to and from the airport for residents, visitors, and external travelers. These trips are generated by arriving or departing passengers and are modeled as tours within the ActivitySim framework. A post processing script also generates trips to serve passengers who require a pickup or dropoff at the airport. For example, a passenger who is picked up at the airport generates two trips; one trip to the airport by the driver to pick up the air passenger(s), and another trip from the airport with the driver and the air passenger(s). +It is important to note that, to work within the ActivitySim framework, the airport trips must be modeled as tours, rather than being generated directly as in the previous model. These tours are assigned an origin at the airport MGRA. During the stop frequency step of ActivitySim, a trip is assigned to the appropriate leg of the tour (either to or from the airport) while the opposite leg is not assigned any trips (referred to as the ‘dummy leg’). Passengers who are leaving on a departing flight and traveling to the airport are considered "inbound," while arriving passengers are considered "outbound". + +The overall design of the model is shown in the figure below. + +![](images/design/airport_model_design.png) + +1. Tour Enumeration: A list of airport travel parties is generated from input enplanements and transferring passenger rates, as well as distributions that describe the share of travel parties by purpose (business versus personal), household income, and party size. +2. Tour Level Models +2.1 Tour Scheduling Probabilistic: The tour scheduling model uses a probabilistic draw of the scheduling distribution. This model assigns start and end times to the tour. This is important because it will also serve as the schedule model for the final airport trips. In ActivitySim, trips are scheduled based on the tour schedule. If there is only one trip per leg on the tour (such as our case here) the trip is assigned the tour start/end time. +2.2 Tour Destination Choice: The destination choice model chooses the non-airport end of the airport trips. Each tour is set with an origin at the airport MGRA. The tour destination model of ActivitySim is used to choose the non-airport end of the trip. The utility equation includes the travel distance, and the destination size terms. ActivitySim destination choice framework requires a mode choice log sum. A dummy tour mode choice log sum was created which generates a value of zero for every destination using the ‘tour_mode_choice.csv’ and ‘tour_mode_choice.yml’ file. This is a work around to prevent ActivitySim from crashing and not having to include the tour mode choice log sum in the destination choice model. +2.3 Stop Frequency Choice: The stop frequency model is where the trip table is first created. The pre-processor tags each tour with a direction of ‘inbound’ or ‘outbound’ according to whether the tour is a departing or arriving passenger. For the Airport Ground Access model, inbound tours are tagged with zero outbound trips and -1 inbound trips (and the opposite is true for outbound tours: -1 outbound trips and 0 inbound trips). The 0 signifies that no intermediate stops are made; this leg of the tour will only have one trip. The -1 signifies that no trip is made at all on that leg. Using the -1 allows us to create ‘half-tours’ where only one leg of the tour is recorded as a trip. +3. Trip Level Models +3.1 Trip Departure Choice: The trip scheduling model assigns depart times for each trip on a tour. ActivitySim requires trip scheduling probabilities; however, these are not used in this implementation since there is only one trip on any given tour leg. This means the trips will be assigned the tour scheduling times which were determined in the tour scheduling model. The trip scheduling probabilities file is just a dummy file. +3.2 Trip Mode Choice: Each trip is assigned a trip mode; in the Airport Ground Access Model, trip mode refers to the airport arrival mode which simultaneously predicts the arrival mode and the location which the passenger uses to access that model. The arrival modes are shown in the table below. The trip mode choice yaml file contains detailed variables associated with each trip mode. For example, each parking location is given an MGRA location, a walk time, a wait-time, and a cost. If a parking location MGRA is set to -999 it is assumed to be unavailable and will not be in the choice set. The pre-processor in this step stores all values of skims from the trip origin to each of the access modes destinations along with any associated costs. Costs include parking fees per day, access fees, fares, and rental car charges. +Employees are not fed into the trip mode choice model. Instead, if a transit share is specified in the employee park file, that percentage of employees will be assigned ‘Walk Premium’ mode in the pre-processor. Otherwise, employees are all assigned ‘Walk’ mode from the employee parking lot to the terminal. +3.3 Airport Returns: Airport trips where the party is dropped of curbside or parked and escorted are assumed to also have the driver make a return trip to the non-airport location. This procedure is done as a post-processing step after mode choice and before trip tables are written out. An ‘airport_returns.yml’ file takes a user setting to determine which trip modes will include a return trip. These trips records are flagged and duplicated. The duplicated trips swap the origin and destination of the original trip and are assigned a unique trip id. These trips are tagged with ‘trip_num =2’ so they are easily sorted in any additional processing (such as for writing trip matrices). +3.4 Write trip matrices: The write trip matrices step converts the trip lists into vehicle trip matrices. The matrices are segmented by trip mode and value of time bins. The vehicle trip modes in the matrices include SOV, HOV2, HOV3+, Taxi, and TNC-single. Value of time segmentation is either low, medium, or high bins based on the thresholds set in the model settings. +#### Airport Ground Access Model Trip Arrival Modes +| **Arrival Mode** | **Description** | +| --- | --- | +| Park Location 1 | Party drives personal vehicle to an on or off-site parking location. | +| Park Location 2 | | +| Park Location 3 | | +| Park Location 4 | | +| Park Location 5 | | +| Curb Location 1 | Party is dropped off or picked up by another driver at designated curbside location. | +| Curb Location 2 | | +| Curb Location 3 | | +| Curb Location 4 | | +| Curb Location 5 | | +| Park and Escort | Party is driven in personal vehicle, parks on-site at the airport and is escorted to/from airport. | +| Rental Car | Party arrives/departs by rental car. | +| Shuttle Van | Party takes shuttle van. | +| Hotel Courtesy | Party takes hotel courtesy transportation. | +| Ridehail Location 1 | Party takes ridehail to ridehail pick-up/drop-off location | +| Ridehail Location 2 | | +| Taxi Location 1 | Party takes taxi to taxi pick-up/drop-off location | +| Taxi Location 2 | | +| Walk Local | Party walks to transit access. | +| Walk Premium | | +| Walk Mix | | +| KNR Local | Party kiss and rides to transit access. | +| KNR Premium | | +| KNR Mix | | +| TNC Local | Party takes TNC to transit access. | +| TNC Premium | | +| TNC Mix | | +| Walk | Walk mode is available only to employees who walk from off-site parking to the airport terminal. | + +For more information on the Crossborder Travel Model see technical documentation. + ## Overnight VIsitor Models diff --git a/docs/images/design/airport_model_design.png b/docs/images/design/airport_model_design.png new file mode 100644 index 000000000..21618b1f1 Binary files /dev/null and b/docs/images/design/airport_model_design.png differ diff --git a/docs/images/design/crossborder_model_design.png b/docs/images/design/crossborder_model_design.png new file mode 100644 index 000000000..6fce410c8 Binary files /dev/null and b/docs/images/design/crossborder_model_design.png differ