Ability to control the allowed state transitions during a simulation

[FlxPo]

Motivation

See : #283

PopulationTrips previously allowed all state transitions at every simulation step, with transitions driven only by utility differences. This makes all forms of behavioral adjustment happen on the same timescale, even though some changes are much easier than others in reality.

This PR adds an explicit way to stage behavioral adaptation over iterations. It allows us to reproduce simplified adjustment dynamics, for example by allowing mode changes first, then destination changes, then full daily programme changes, while we work toward a more complete transition-cost model (see #196).

---

Changes

Added a new staged behavior-change API to PopulationTripsParameters:

• BehaviorChangeScope
  • FULL_REPLANNING
  • DESTINATION_REPLANNING
  • MODE_REPLANNING
• BehaviorChangePhase(start_iteration, scope)
• behavior_change_phases
• get_behavior_change_scope(iteration)

Implemented scope-aware behavior in PopulationTrips and StateUpdater:

• FULL_REPLANNING
  • motive, destination, and mode sequences may change
• DESTINATION_REPLANNING
  • motive sequences are fixed
  • destination and dependent mode sequences may change
• MODE_REPLANNING
  • motive and destination sequences are fixed
  • only mode sequences may change

The restriction now applies both:

• when generating candidate states
• when computing reachable from -> to transitions

This means restricted phases do not just limit newly generated states; they also enforce that only allowed transitions are actually reachable.

Stay-home behavior is also defined explicitly:

• stay-home remains available in FULL_REPLANNING
• stay-home is frozen in MODE_REPLANNING and DESTINATION_REPLANNING

Refactored candidate-generation logic out of PopulationTrips.run_model() into a dedicated helper module:

• population_trips_candidates.py

Added tests for:

• phase resolution
• candidate generation under restricted scopes
• transition legality under restricted scopes
• integration of phased behavior changes in a real PopulationTrips run

---

Example

from mobility.choice_models.population_trips_parameters import (
    BehaviorChangePhase,
    BehaviorChangeScope,
    PopulationTripsParameters,
)

parameters = PopulationTripsParameters(
    n_iterations=12,
    behavior_change_phases=[
        BehaviorChangePhase(
            start_iteration=1,
            scope=BehaviorChangeScope.FULL_REPLANNING,
        ),
        BehaviorChangePhase(
            start_iteration=5,
            scope=BehaviorChangeScope.MODE_REPLANNING,
        ),
        BehaviorChangePhase(
            start_iteration=8,
            scope=BehaviorChangeScope.DESTINATION_REPLANNING,
        ),
        BehaviorChangePhase(
            start_iteration=11,
            scope=BehaviorChangeScope.FULL_REPLANNING,
        ),
    ],
)

This means:

• iterations 1-4: full replanning
• iterations 5-7: mode replanning only, from the active states at iteration 4 (no destination changes, no motive sequence changes).
• iterations 8-10: destination + mode replanning, from the active states at iteration 7 (no motive sequence changes).
• iterations 11-12: full replanning again

If behavior_change_phases is omitted, all iterations use by default BehaviorChangeScope.FULL_REPLANNING.

[codecov]

Codecov Report

❌ Patch coverage is 86.72566% with 15 lines in your changes missing coverage. Please review.
✅ Project coverage is 59.54%. Comparing base (db01023) to head (d0dbe83).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
...ility/choice_models/population_trips_candidates.py	75.51%	12 Missing ⚠️
...ility/choice_models/population_trips_parameters.py	93.75%	2 Missing ⚠️
mobility/choice_models/state_updater.py	95.83%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #284      +/-   ##
==========================================
+ Coverage   59.06%   59.54%   +0.47%     
==========================================
  Files         129      130       +1     
  Lines        6738     6845     +107     
==========================================
+ Hits         3980     4076      +96     
- Misses       2758     2769      +11     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.