User Model

This chapter specifies the reference implementations for User Model components in MaaS Blender. The User Model represents the decision-making logic of individual users throughout their journey. It orchestrates trip planning, route selection, reservation, and execution by coordinating with planners and mobility services through event-driven interactions.

The project currently ships two reference implementations under maasblender/src/user_model:

• Simple User Model: for straightforward route selection with basic preference handling.
• Favorite-based User Model: for more sophisticated per-user preferences including favorite services and sorting criteria.

Both implementations share the same event contract and lifecycle but differ in route-selection policies and configuration options.

Common Lifecycle

All User Model implementations follow this general flow:

1. The simulator forwards a DEMAND to the User Model via UserManager.demand(...).
2. The manager calls an external route planner (Planner) with plan(org, dst, dept).
3. The User Model ranks/filters candidates according to its selection policy (varies by implementation).
4. The selected route is converted into a sequence of tasks (Reserve, Trip, Wait).
5. The User entity runs the tasks in order, emitting RESERVE and/or DEPART at appropriate times.
6. On RESERVED failure, the User Model switches to a recovery task sequence (fallback to alternative plan or walking).
7. The User Model continues to observe DEPARTED and ARRIVED to orchestrate transfers and detect leg completion.

Simple User Model

• Files: user_model/simple/
• Primary class: UserManager

This model provides a user decision policy with a small set of preferences.

Behavior

• Calls Planner.plan(org, dst, dept) to retrieve route candidates.
• If the DEMAND provides service, applies preference mode:
  • PreferenceMode.fixed: keeps only plans that contain the specified service.
  • Otherwise: sorts so that plans containing the service come first.
• If only 1 plan is returned, builds tasks for that plan with walking fallback for mobility legs.
• If 2+ plans are returned, builds a primary sequence and sets the secondary as recovery; recovery is used if the primary mobility leg fails.
• If a route pattern matches "reservation-required" (heuristic: 3-trip route with the middle leg's service in confirmed_services), the manager builds a Reserve task for that leg. Otherwise, legs are built as direct Trip tasks (e.g., walking or services without reservations).
• If dept > now and the first task is a Trip, a Wait(dept) task is inserted before the first leg.

Configuration

{
  "preference_mode": "fixed",                   // or any other value for prefer mode
  "confirmed_services": ["taxi", "bus"]         // services that require reservation
}

• preference_mode (from jschema.query.PreferenceMode):
  • "fixed": filters plans to only those that include the specified service per demand.
  • Otherwise: prefers plans containing the specified service but allows others.
• confirmed_services: list of services that require reservation.

Favorite-based User Model

• Files: user_model/favorite/
• Primary class: UserManager

This model provides richer, per-user route preferences including favorite service, walking time limits, and candidate sorting.

Behavior

• Each user gets a RouteFilter instance. If a UserType is provided, the filter becomes a FavoriteSortedRouteFilter that:
  • Sorts plans by SortType (e.g., earliest arrival, least transfers, lowest cost).
  • Applies checks for favorite service presence and enforces a walking time cap when applicable.
• If fixed_service is provided in the DEMAND, it takes priority: plans are filtered so that the given service is included.
• Waiting and failure handling are analogous to the Simple model, including "reservation vs direct depart" and walking fallbacks.

Configuration

{
  "user_params": {
    "U001": {
      "favorite_service": "rail",
      "walking_time_limit_min": 15.0,
      "sort_type": "earliest_arrival"
    },
    "U002": {
      "favorite_service": "bus",
      "walking_time_limit_min": 10.0,
      "sort_type": "least_transfers"
    },
    "U003": null
  },
  "confirmed_services": ["taxi", "shuttle"]
}

• user_params: dictionary mapping user IDs to their preferences (UserType or null):
  • favorite_service: preferred mobility service (e.g., "rail", "bus").
  • walking_time_limit_min: maximum acceptable walking time in minutes.
  • sort_type: sorting a criterion from jschema.query.SortType (e.g., "earliest_arrival", "least_transfers", "lowest_cost").
• confirmed_services: list of services that require reservation (same as a Simple model).