updating component documentation

docs/dev-guide/components/atwork_subtour_destination.md

@@ -0,0 +1,46 @@
+(component-atwork-subtour-destination)=
+# At-work Subtours Destination Choice
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.atwork_subtour_destination.py
+```
+
+The at-work subtours destination choice model is made up of three model steps:
+
+  * sample - selects a sample of alternative locations for the next model step. This selects X locations from the full set of model zones using a simple utility.
+  * logsums - starts with the table created above and calculates and adds the mode choice logsum expression for each alternative location.
+  * simulate - starts with the table created above and chooses a final location, this time with the mode choice logsum included.
+
+At-work subtour location choice for [multiple_zone_systems](multiple_zone_systems) models uses [presampling](presampling) by default.
+
+The main interface to the at-work subtour destination model is the
+[atwork_subtour_destination](ctivitysim.abm.models.atwork_subtour_destination.atwork_subtour_destination)
+function.  This function is registered as an Inject step in the example Pipeline.
+[writing_logsums]`writing_logsums` for how to write logsums for estimation.
+
+## Structure
+
+- *Configuration File*: `atwork_subtour_destination.yaml`
+- *Core Table*: `tours`
+- *Result Field*: `destination`
+- *Skims keys*: `workplace_taz, alt_dest, MD time period`
+
+## Configuration
+
+```{eval-rst}
+.. autopydantic_model:: TourLocationComponentSettings
+    :inherited-members: BaseModel, PydanticReadable
+    :show-inheritance:
+```
+
+### Examples
+
+- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/atwork_subtour_destination.yaml)
+- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/atwork_subtour_destination.yaml)
+
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: atwork_subtour_destination
+```

docs/dev-guide/components/atwork_subtour_frequency.md

@@ -0,0 +1,48 @@
+(component-atwork-subtour-frequency)=
+# At-work Subtours Frequency
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.atwork_subtour_frequency.py
+```
+
+The at-work subtour frequency model selects the number of at-work subtours made for each work tour.
+It also creates at-work subtours by adding them to the tours table in the data pipeline.
+These at-work sub-tours are travel tours taken during the workday with their origin at the work
+location, rather than from home. Explanatory variables include employment status,
+income, auto ownership, the frequency of other tours, characteristics of the parent work tour, and
+characteristics of the workplace zone.
+
+Choosers: work tours
+Alternatives: none, 1 eating out tour, 1 business tour, 1 maintenance tour, 2 business tours, 1 eating out tour + 1 business tour
+Dependent tables: household, person, accessibility
+Outputs: work tour subtour frequency choice, at-work tours table (with only tour origin zone at this point)
+
+The main interface to the at-work subtours frequency model is the
+[atwork_subtour_frequency](activitysim.abm.models.atwork_subtour_frequency.atwork_subtour_frequency)
+function.  This function is registered as an Inject step in the example Pipeline.
+
+## Structure
+
+- *Configuration File*: `atwork_subtour_frequency.yaml`
+- *Core Table*: `tours`
+- *Result Field*: `atwork_subtour_frequency`
+
+## Configuration
+
+```{eval-rst}
+.. autopydantic_model:: AtworkSubtourFrequencySettings
+    :inherited-members: BaseModel, PydanticReadable
+    :show-inheritance:
+```
+
+### Examples
+
+- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/atwork_subtour_destination.yaml)
+- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/atwork_subtour_destination.yaml)
+
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: atwork_subtour_frequency
+```

docs/dev-guide/components/atwork_subtour_mode_choice.md

@@ -0,0 +1,41 @@
+(component-atwork-subtour-mode-choice)=
+# At-work Subtour Mode
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.atwork_subtour_mode_choice.py
+```
+
+The at-work subtour mode choice model assigns a travel mode to each at-work subtour using the `tour_mode_choice` model.
+
+The main interface to the at-work subtour mode choice model is the
+[atwork_subtour_mode_choice](activitysim.abm.models.atwork_subtour_mode_choice.atwork_subtour_mode_choice)
+function.  This function is called in the Inject step `atwork_subtour_mode_choice` and
+is registered as an Inject step in the example Pipeline.
+[writing_logsums](writing_logsums) for how to write logsums for estimation.
+
+## Structure
+
+- *Configuration File*: `tour_mode_choice.yaml`
+- *Core Table*: `tour`
+- *Result Field*: `tour_mode`
+- *Skims keys*: `workplace_taz, destination, start, end`
+
+## Configuration
+
+```{eval-rst}
+.. autopydantic_model:: TourModeComponentSettings
+    :inherited-members: BaseModel, PydanticReadable
+    :show-inheritance:
+```
+
+### Examples
+
+- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/tour_mode_choice.yaml)
+- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/tour_mode_choice.yaml)
+
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: atwork_subtour_mode_choice
+```

docs/dev-guide/components/atwork_subtour_scheduling.md

@@ -0,0 +1,50 @@
+(component-atwork-subtour-scheduling)=
+# At-work Subtour Scheduling
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.atwork_subtour_scheduling.py
+```
+
+The at-work subtours scheduling model selects a tour departure and duration period (and therefore a start and end
+period as well) for each at-work subtour.  This model uses person `time_windows`.
+
+This model is the same as the mandatory tour scheduling model except it operates on the at-work tours and
+constrains the alternative set to available person `time_windows`.  The at-work subtour scheduling model does not use mode choice logsums.
+The at-work subtour frequency model can choose multiple tours so this model must process all first tours and then second
+tours since isFirstAtWorkTour is an explanatory variable.
+
+Choosers: at-work tours
+Alternatives: alternative departure time and arrival back at origin time pairs WITHIN the work tour departure time and arrival time back at origin AND the person time window. If no time window is available for the tour, make the first and last time periods within the work tour available, make the choice, and log the number of times this occurs.
+Dependent tables: skims, person, land use, work tour
+Outputs: at-work tour departure time and arrival back at origin time, updated person time windows
+
+The main interface to the at-work subtours scheduling model is the
+[atwork_subtour_scheduling](activitysim.abm.models.atwork_subtour_scheduling.atwork_subtour_scheduling)
+function.  This function is registered as an Inject step in the example Pipeline.
+
+## Structure
+
+- *Configuration File*: `tour_scheduling_atwork.yaml`
+- *Core Table*: `tours`
+- *Result Field*: `start, end, duration`
+- *Skims keys*: `workplace_taz, alt_dest, MD time period, MD time period`
+
+## Configuration
+
+```{eval-rst}
+.. autopydantic_model:: AtworkSubtourSchedulingSettings
+    :inherited-members: BaseModel, PydanticReadable
+    :show-inheritance:
+```
+
+### Examples
+
+- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/tour_scheduling_atwork.yaml)
+- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/tour_scheduling_atwork.yaml)
+
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: atwork_subtour_scheduling
+```

docs/dev-guide/components/index.rst

@@ -5,14 +5,35 @@ Components
 .. toctree::
     :maxdepth: 1
 
-    accessibility
-    auto_ownership
-    free_parking
-    school_location_choice
-    trip_destination
-    work_from_home
-    work_location_choice
-
+   initialize
+   initialize_los
+   initialize_tours
+   accessibility
+   auto_ownership
+   disaggregate_accessibility
+   free_parking
+   school_location_choice
+   transit_pass_ownership
+   transit_pass_subsidy
+   trip_destination
+   free_parking
+   school_location_choice
+   work_from_home
+   work_location_choice
+   tour_mode_choice
+   atwork_subtour_frequency
+   atwork_subtour_destination
+   atwork_subtour_scheduling
+   atwork_subtour_mode_choice
+   stop_frequency
+   trip_purpose
+   trip_destination
+   trip_purpose_and_destination
+   trip_scheduling_choice
+   trip_departure_choice
+   trip_mode_choice
+   parking_location_choice
+   write_trip_matrices
 
 
 .. note::

docs/dev-guide/components/initialize.md

@@ -0,0 +1,24 @@
+(component-initialize)=
+# Initialize
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.initialize
+```
+
+The initialize model isn't really a model, but rather a few data processing steps in the data pipeline.
+The initialize data processing steps code variables used in downstream models, such as household and person
+value-of-time.  This step also pre-loads the land_use, households, persons, and person_windows tables because
+random seeds are set differently for each step and therefore the sampling of households depends on which step
+they are initially loaded in.
+
+The main interface to the initialize land use step is the :py:func:`~activitysim.abm.models.initialize.initialize_landuse`
+function. The main interface to the initialize household step is the :py:func:`~activitysim.abm.models.initialize.initialize_households`
+function.  The main interface to the initialize tours step is the :py:func:`~activitysim.abm.models.initialize_tours.initialize_tours`
+function.  These functions are registered as Inject steps in the example Pipeline.
+
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: initialize
+```

docs/dev-guide/components/initialize_los.md

@@ -0,0 +1,26 @@
+(component-initialize-los)=
+# Initialize LOS
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.initialize_los
+```
+
+The initialize LOS model isn't really a model, but rather a series of data processing steps in the data pipeline.
+The initialize LOS model does two things:
+
+  * Loads skims and cache for later if desired
+  * Loads network LOS inputs for transit virtual path building (see :ref:`transit_virtual_path_builder`), pre-computes tap-to-tap total utilities and cache for later if desired
+
+
+The main interface to the initialize LOS step is the :py:func:`~activitysim.abm.models.initialize_los.initialize_los`
+function.  The main interface to the initialize TVPB step is the :py:func:`~activitysim.abm.models.initialize_los.initialize_tvpb`
+
+function.  These functions are registered as Inject steps in the example Pipeline.
+
+
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: initialize_los
+```

docs/dev-guide/components/initialize_tours.md

@@ -0,0 +1,15 @@
+(component-initialize-tours)=
+# Initialize Tours
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.initialize_tours
+```
+
+
+
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: initialize_tours
+```

docs/dev-guide/components/tour_mode_choice.md

@@ -0,0 +1,64 @@
+(component-tour-mode-choice)=
+# Tour Mode Choice
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.tour_mode_choice.py
+```
+
+The mandatory, non-mandatory, and joint tour mode choice model assigns to each tour the "primary" mode that
+is used to get from the origin to the primary destination. The tour-based modeling approach requires a reconsideration
+of the conventional mode choice structure. Instead of a single mode choice model used in a four-step
+structure, there are two different levels where the mode choice decision is modeled: (a) the
+tour mode level (upper-level choice); and, (b) the trip mode level (lower-level choice conditional
+upon the upper-level choice).
+
+The mandatory, non-mandatory, and joint tour mode level represents the decisions that apply to the entire tour, and
+that will affect the alternatives available for each individual trip or joint trip. These decisions include the choice to use a private
+car versus using public transit, walking, or biking; whether carpooling will be considered; and
+whether transit will be accessed by car or by foot. Trip-level decisions correspond to details of
+the exact mode used for each trip, which may or may not change over the trips in the tour.
+
+The mandatory, non-mandatory, and joint tour mode choice structure is a nested logit model which separates
+similar modes into different nests to more accurately model the cross-elasticities between the alternatives. The
+eighteen modes are incorporated into the nesting structure specified in the model settings file. The
+first level of nesting represents the use a private car, non-motorized
+means, or transit. In the second level of nesting, the auto nest is divided into vehicle occupancy
+categories, and transit is divided into walk access and drive access nests. The final level splits
+the auto nests into free or pay alternatives and the transit nests into the specific line-haul modes.
+
+The primary variables are in-vehicle time, other travel times, cost (the influence of which is derived
+from the automobile in-vehicle time coefficient and the persons' modeled value of time),
+characteristics of the destination zone, demographics, and the household's level of auto
+ownership.
+
+The main interface to the mandatory, non-mandatory, and joint tour mode model is the
+[tour_mode_choice_simulate](activitysim.abm.models.tour_mode_choice.tour_mode_choice_simulate) function.  This function is
+called in the Inject step [tour_mode_choice_simulate](tour_mode_choice_simulate) and is registered as an Inject step in the example Pipeline.
+See [writing_logsums](writing_logsums) for how to write logsums for estimation.
+
+## Structure
+
+- *Configuration File*: `tour_mode_choice.yaml`
+- *Core Table*: `tours`
+- *Result Field*: `mode`
+- *Skims Keys*: `TAZ, destination, start, end`
+
+## Configuration
+
+```{eval-rst}
+.. autopydantic_model:: TourModeComponentSettings
+    :inherited-members: BaseModel, PydanticReadable
+    :show-inheritance:
+```
+
+### Examples
+
+- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/tour_mode_choice.yaml)
+- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/tour_mode_choice.yaml)
+
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: tour_mode_choice
+```