Vehicle Allocation#

The vehicle allocation model selects which vehicle would be used for a tour of given occupancy. The alternatives for the vehicle allocation model consist of the vehicles owned by the household and an additional non household vehicle option. (Zero-auto households would be assigned the non-household vehicle option since there are no owned vehicles in the household). A vehicle is selected for each occupancy level set by the user such that different tour modes that have different occupancies could see different operating characteristics. The output of the vehicle allocation model is appended to the tour table with column names vehicle_occup_{occupancy} and the values are the vehicle type selected.

In prototype_mtc_extended, three occupancy levels are used: 1, 2, and 3.5. The auto operating cost for occupancy level 1 is used in the drive alone mode and drive to transit modes. Occupancy levels 2 and 3.5 are used for shared ride 2 and shared ride 3+ auto operating costs, respectively. Auto operating costs are selected in the mode choice pre-processors by selecting the allocated vehicle type data from the vehicles table. If the allocated vehicle type was the non-household vehicle, the auto operating costs uses the previous default value from prototype_mtc. All trips and atwork subtours use the auto operating cost of the parent tour. Functionality was added in tour and atwork subtour mode choice to annotate the tour table and create a selected_vehicle which denotes the actual vehicle used. If the tour mode does not include a vehicle, then the selected_vehicle entry is left blank.

The current implementation does not account for possible use of the household vehicles by other household members. Thus, it is possible for a selected vehicle to be used in two separate tours at the same time.

Structure#

  • Configuration File: vehicle_allocation.yaml

  • Result Field: vehicle_occup_{occupancy}

Configuration#

settings activitysim.abm.models.vehicle_allocation.VehicleAllocationSettings#

Bases: LogitComponentSettings

Settings for the joint_tour_scheduling component.

Fields:
Validators:

  • nests_are_for_nl » NESTS

field COEFFICIENTS: Path | None = None#

Coefficients filename.

This is a CSV file giving named parameters for use in the utility expression. If it is not provided, then it is assumed that all model coefficients are given explicitly in the SPEC as numerical values instead of named parameters. This is perfectly acceptable for use with ActivitySim for typical simulation applications, but may be problematic if used with “estimation mode”.

field CONSTANTS: dict[str, Any] = {}#

Named constants usable in the utility expressions.

field LOGIT_TYPE: Literal['MNL', 'NL'] = 'MNL'#

Logit model mathematical form.

  • “MNL”

    Multinomial logit model.

  • “NL”

    Nested multinomial logit model.

field NESTS: LogitNestSpec | None = None#

Nesting structure for a nested logit model.

The nesting structure is specified heirarchically from the top, so the value of this field should be the “root” level nest of the nested logit tree, which should contain references to lower level nests and/or the actual alternatives.

For example, this YAML defines a simple nesting structure for four alternatives (DRIVE, WALK, WALK_TO_TRANSIT, DRIVE_TO_TRANSIT) with the two transit alternatives grouped together in a nest:

NESTS:
  name: root
  coefficient: coef_nest_root
  alternatives:
    - DRIVE
    - WALK
    - name: TRANSIT
      coefficient: coef_nest_transit
      alternatives:
      - WALK_TO_TRANSIT
      - DRIVE_TO_TRANSIT
Validated by:

  • nests_are_for_nl

field OCCUPANCY_LEVELS: list = [1]#

Occupancy level

It will create columns in the tour table selecting a vehicle for each of the occupancy levels. They are named vehicle_occup_1, vehicle_occup_2,… etc. if not supplied, will default to only one occupancy level of 1

field SPEC: Path [Required]#

Utility specification filename.

This is sometimes alternatively called the utility expressions calculator (UEC). It is a CSV file giving all the functions for the terms of a linear-in-parameters utility expression.

field annotate_tours: PreprocessorSettings | None = None#

Preprocessor settings to annotate tours

field preprocessor: PreprocessorSettings | None = None#

Setting for the preprocessor.

field sharrow_skip: bool = False#

Skip sharrow when evaluating this component.

field source_file_paths: list[Path] = None#

A list of source files from which these settings were loaded.

This value should not be set by the user within the YAML settings files, instead it is populated as those files are loaded. It is primarily provided for debugging purposes, and does not actually affect the operation of any model.

validator nests_are_for_nl  »  NESTS#

Checks that nests are provided if (and only if) LOGIT_TYPE is NL.

Examples#

Implementation#

activitysim.abm.models.vehicle_allocation.vehicle_allocation(state: State, persons: DataFrame, households: DataFrame, vehicles: DataFrame, tours: DataFrame, tours_merged: DataFrame, network_los: Network_LOS, model_settings: Optional[VehicleAllocationSettings] = None, model_settings_file_name: str = 'vehicle_allocation.yaml', trace_label: str = 'vehicle_allocation') → None#

Selects a vehicle for each occupancy level for each tour.

Alternatives consist of the up to the number of household vehicles plus one option for non-household vehicles.

The model will be run once for each tour occupancy defined in the model yaml. Output tour table will columns added for each occupancy level.

The user may also augment the tours tables with new vehicle type-based fields specified via the annotate_tours option.

Parameters:
stateworkflow.State
personspd.DataFrame
householdspd.DataFrame
vehiclespd.DataFrame
tourspd.DataFrame
tours_mergedpd.DataFrame
network_loslos.Network_LOS
activitysim.abm.models.vehicle_allocation.annotate_vehicle_allocation(state: State, model_settings: VehicleAllocationSettings, trace_label: str)#

Add columns to the tours table in the pipeline according to spec.

Parameters:
model_settingsVehicleAllocationSettings
trace_labelstr
activitysim.abm.models.vehicle_allocation.get_skim_dict(network_los: Network_LOS, choosers: DataFrame)#

Returns a dictionary of skim wrappers to use in expression writing.

Skims have origin as home_zone_id and destination as the tour destination.

Parameters:
network_losactivitysim.core.los.Network_LOS object
chooserspd.DataFrame
Returns:
skimsdict

index is skim wrapper name, value is the skim wrapper