updating stop frequency, trip purpose and trip scheduling documentation

docs/dev-guide/components/stop_frequency.md

@@ -0,0 +1,53 @@
+(component-stop-frequency)=
+# Stop Frequency
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.stop_frequency.py
+```
+
+The stop frequency model assigns to each tour the number of intermediate destinations a person
+will travel to on each leg of the tour from the origin to tour primary destination and back.
+The model incorporates the ability for more than one stop in each direction,
+up to a maximum of 3, for a total of 8 trips per tour (four on each tour leg).
+
+Intermediate stops are not modeled for drive-transit tours because doing so can have unintended
+consequences because of the difficulty of tracking the location of the vehicle. For example,
+consider someone who used a park and ride for work and then took transit to an intermediate
+shopping stop on the way home. Without knowing the vehicle location, it cannot be determined
+if it is reasonable to allow the person to drive home. Even if the tour were constrained to allow
+driving only on the first and final trip, the trip home from an intermediate stop may not use the
+same park and ride where the car was dropped off on the outbound leg, which is usually as close
+as possible to home because of the impracticality of coding drive access links from every park
+and ride lot to every zone.
+
+This model also creates a trips table in the pipeline for later models.
+
+The main interface to the intermediate stop frequency model is the
+[stop_frequency](activitysim.abm.models.stop_frequency.stop_frequency)
+function.  This function is registered as an Inject step in the example Pipeline.
+
+## Structure
+
+- *Configuration File*: `stop_frequency.yaml`
+- *Core Table*: `tours`
+- *Result Field*: `stop_frequency`
+
+## Configuration
+
+```{eval-rst}
+.. autopydantic_model:: StopFrequencySettings
+    :inherited-members: BaseModel, PydanticReadable
+    :show-inheritance:
+```
+
+### Examples
+
+- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/stop_frequency.yaml)
+- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/stop_frequency.yaml)
+
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: stop_frequency
+```

docs/dev-guide/components/trip_purpose.md

@@ -0,0 +1,44 @@
+(component-trip-purpose)=
+# Trip Purpose
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.trip_purpose.py
+```
+
+For trip other than the last trip outbound or inbound, assign a purpose based on an
+observed frequency distribution.  The distribution is segmented by tour purpose, tour
+direction and person type. Work tours are also segmented by departure or arrival time period.
+
+The main interface to the trip purpose model is the
+[trip_purpose](activitysim.abm.models.trip_purpose)
+function.  This function is registered as an Inject step in the example Pipeline.
+
+
+## Structure
+
+
+- *Core Table*: `trips`
+- *Result Field*: `purpose`
+
+## Configuration
+
+```{eval-rst}
+.. autopydantic_model::
+    :inherited-members: BaseModel, PydanticReadable
+    :show-inheritance:
+```
+
+### note::
+Trip purpose and trip destination choice can be run iteratively together [trip_purpose_and_destination_model](activitysim.abm.models.trip_purpose_and_destination.py)
+
+### Examples
+
+- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/trip_purpose.yaml)
+- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/trip_purpose.yaml)
+
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: trip_purpose
+```

docs/dev-guide/components/trip_scheduling_choice.md

@@ -0,0 +1,37 @@
+(component-trip-scheduling-choice)=
+# Trip Scheduling Choice
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.trip_scheduling_choice.py
+```
+
+This model uses a logit-based formulation to determine potential trip windows for the three
+main components of a tour.
+
+-  Outbound Leg: The time from leaving the origin location to the time second to last outbound stop.
+-  Main Leg: The time window from the last outbound stop through the main tour destination to the first inbound stop.
+-  Inbound Leg: The time window from the first inbound stop to the tour origin location.
+
+## Structure
+
+- *Configuration File*: `trip_scheduling_choice.yaml`
+- *Core Table*: `tours`
+- *Result Field*: `outbound_duration`, `main_leg_duration`, `inbound_duration`
+
+## Configuration
+
+```{eval-rst}
+.. autopydantic_model:: TripSchedulingChoiceSettings
+    :inherited-members: BaseModel, PydanticReadable
+    :show-inheritance:
+```
+
+### Examples
+
+- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/trip_scheduling_choice.yaml)
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: trip_scheduling_choice
+```