Add complete destination-plan search

[FlxPo]

Motivation

Mobility currently samples destinations one activity at a time. A destination can be plausible for one trip while producing an implausible complete day when combined with the other destinations.

For example:

home → work → shopping → home

The work and shopping locations may each appear reasonable on their own, while the travel between them leaves no meaningful time for shopping—or makes the schedule impossible. These candidates consume destination and mode sampling work before being corrected or discarded later.

This PR adds a destination search that evaluates the complete daily chain. It considers all consecutive trips, representative OD travel times, and minimum activity durations before returning a plan. This reduces wasted candidates and gives the model several coherent destination alternatives for the same activity schedule.

It also improves tour-level destination choice: each location is evaluated through its effect on the complete chain, including both the trip used to reach it and the following trip.

Feasibility at this stage uses representative travel times. A specific mode selected later may still make a plan infeasible; mode-specific feasibility remains a separate modelling step.

Changes

• Add complete destination-plan search behind use_destination_plan_search.
• Generate up to k_destination_sequences high-scoring destination chains for each activity schedule.
• Reject chains that do not leave enough time for their planned activities.
• Rank complete chains using:
  • destination opportunities;
  • travel costs;
  • activity values;
  • destination saturation and shadow prices;
  • country-specific destination values.
• Deduplicate identical search inputs before running the search, then restore results for each demand group.
• Preserve Mobility’s existing destination-sequence output for the mode and plan stages.
• Use the model-wide plan-choice scale for destination ranking.
• Report activity schedules for which no feasible destination chain is found.
• Include all search inputs in cache invalidation.
• Add user documentation, unit tests, a Grand Genève snapshot test, and a reproducible comparison script under experiments/.

Example

from mobility import (
    GroupDayTripsDestinationSequenceParameters,
    GroupDayTripsParameters,
)

parameters = GroupDayTripsParameters(
    destination_sequences=GroupDayTripsDestinationSequenceParameters(
        use_destination_plan_search=True,
        k_destination_sequences=3,
    ),
)

The step-by-step destination sampler remains the default.

AI-assisted contribution

• No AI assistance
• AI used for minor help only (e.g. autocomplete, small refactors)
• AI used for substantial parts of this PR

If substantial, briefly describe:

• Scope of AI-assisted content: destination-search integration, tests, documentation, and comparison tooling.
• What you reviewed or changed: search inputs, timing feasibility, result conversion, public parameters, caching, and documentation.
• How you validated it: focused unit tests, dependency checks, and a Grand Genève snapshot test using real model inputs.

Checklist

• I have reviewed all code in this PR
• I understand the code and can maintain it
• I added or ran appropriate tests/checks for the changed behavior

[codecov]

Codecov Report

❌ Patch coverage is 91.04478% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.99%. Comparing base (a193347) to head (3fcda2f).

Files with missing lines	Patch %	Lines
...ips/group_day_trips/plans/destination_sequences.py	68.75%	5 Missing ⚠️
...s/group_day_trips/plans/destination_plan_search.py	98.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #404      +/-   ##
==========================================
+ Coverage   82.97%   82.99%   +0.02%     
==========================================
  Files         232      233       +1     
  Lines       15978    16039      +61     
==========================================
+ Hits        13257    13312      +55     
- Misses       2721     2727       +6     

☔ View full report in Codecov by Harness.
📢 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.