Add time varying parameters

[FlxPo]

Motivations

This PR adds support for iteration-based time-varying parameter values.
See #281.

Changes

• Add iteration-based profile utilities in mobility.runtime.parameter_profiles:
  • ParameterProfile as the shared base class
  • ScalarParameterProfile for scalar parameters with step or linear evolution
  • ListParameterProfile for step-wise list-valued parameters
  • SimulationStep to identify the current iteration
• Move shared validated scalar aliases to mobility.runtime.validation_types.
• Allow activity parameters such as value_of_time, value_of_time_stay_home, and radiation_lambda to accept either constant scalar values or ScalarParameterProfile values.
• Add Activity.get_parameters_at_step(step) and a shared per-iteration activity-parameter resolution path so activity parameters are resolved once per iteration and then reused downstream.
• Update GroupDayTrips to use step-specific activity parameters when computing:
  • destination utilities
  • radiation-model destination probabilities
  • initial stay-home utility
  • per-step activity utilities
  • home-time utility
  • opportunity saturation parameters
• Allow PublicTransportRoutingParameters.additional_gtfs_files to accept either a constant list[str] or a ListParameterProfile.
• Resolve time-varying public transport routing parameters once per iteration at the GroupDayTrips run boundary through an iteration-scoped resolved transport-cost aggregator.
• Add a first-class GTFS builder in mobility.transport.modes.public_transport.gtfs_builder to generate synthetic GTFS feeds from simplified declarative inputs.
• Remove stale Motive / MotiveParameters references introduced by the older implementation path and align the feature with the current Activity / GroupDayTrips architecture from the refactor branch.

Examples

The API to make the value of time for the work activity change from 4 €/h to 8 €/h at iteration 3 is:

mobility.Work(
    value_of_time=mobility.ScalarParameterProfile(
        mode="step",
        points={
            1: 4.0,
            3: 8.0,
        },
    )
)

It is also possible to get a gradual change with linear interpolation. Here the value of time will be 4, 6, and 8 at iterations 1, 2, and 3:

mobility.Work(
    value_of_time=mobility.ScalarParameterProfile(
        mode="linear",
        points={
            1: 4.0,
            3: 8.0,
        },
    )
)

The existing API still works for constant parameters:

mobility.Work(
    value_of_time=4.0
)

Step-wise list-valued parameters are currently supported for PublicTransportRoutingParameters.additional_gtfs_files. For example, to switch the additional GTFS files used by public transport routing at iteration 2:

mobility.PublicTransportRoutingParameters(
    additional_gtfs_files=mobility.ListParameterProfile(
        points={
            1: ["slow_subway.zip"],
            2: ["fast_subway.zip"],
        }
    )
)

[codecov]

Codecov Report

❌ Patch coverage is 84.17419% with 298 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.10%. Comparing base (79769a7) to head (e92ebfd).

Files with missing lines	Patch %	Lines
mobility/trips/group_day_trips/core/results.py	43.96%	144 Missing ⚠️
...ips/group_day_trips/iterations/iteration_assets.py	80.80%	19 Missing ⚠️
.../carpool/detailed/detailed_carpool_travel_costs.py	33.33%	18 Missing ⚠️
...ity/trips/group_day_trips/iterations/iterations.py	81.81%	16 Missing ⚠️
...lity/trips/group_day_trips/core/group_day_trips.py	81.53%	12 Missing ⚠️
...ips/group_day_trips/plans/destination_sequences.py	88.23%	12 Missing ⚠️
...detailed/detailed_carpool_travel_costs_snapshot.py	55.00%	9 Missing ⚠️
...bility/trips/group_day_trips/plans/plan_updater.py	89.77%	9 Missing ⚠️
...lity/transport/costs/transport_costs_aggregator.py	93.06%	7 Missing ⚠️
...y/transport/modes/public_transport/gtfs_builder.py	93.57%	7 Missing ⚠️
... and 17 more

Additional details and impacted files

@@             Coverage Diff             @@
##             main     #282       +/-   ##
===========================================
+ Coverage   59.06%   74.10%   +15.03%     
===========================================
  Files         129      146       +17     
  Lines        6738     6291      -447     
===========================================
+ Hits         3980     4662      +682     
+ Misses       2758     1629     -1129     

☔ 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.