test(objectives): add tests for prefer-early-tours objective

vrp-core unit tests covering the delay charged for opening a shift, that a
shift already in use costs nothing however late it starts, the fitness sum
over shifts in use, empty routes scoring nothing, and the first-job arrival
floor fallback used when out-of-hours depot travel relaxes the shift start
bound.

vrp-pragmatic round-trip plus behavioural tests: a baseline asserting the
solver picks the cheaper later shift when no objective is set, so the paired
test that it picks the earliest shift cannot pass vacuously, and a case
covering the out-of-hours depot travel interaction.

E1608 validation tests covering the unguarded goal, both accepted guards, a
guard ranked below the objective, a guard sharing a tier with it, a guard in
a higher multi-objective tier, and a goal that never mentions the objective.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: hutchinsp01

vrp-core/src/construction/features/early_tours.rs

@@ -39,6 +39,10 @@
 //!
 //! Objective only - no constraint or state.
 
+#[cfg(test)]
+#[path = "../../../tests/unit/construction/features/early_tours_test.rs"]
+mod early_tours_test;
+
 use super::*;
 use crate::construction::enablers::FirstJobArrivalFloorDimension;
 use crate::models::solution::Route;

vrp-core/tests/unit/construction/features/early_tours_test.rs

@@ -0,0 +1,152 @@
+use super::*;
+use crate::construction::enablers::FirstJobArrivalFloorDimension;
+use crate::helpers::construction::heuristics::TestInsertionContextBuilder;
+use crate::helpers::models::problem::*;
+use crate::helpers::models::solution::*;
+use crate::models::common::TimeInterval;
+use crate::models::problem::{VehicleDetail, VehiclePlace};
+
+const DAY: Timestamp = 86400.;
+
+/// Builds a fleet where vehicle `i` is a shift starting on day `i`, mimicking a multi-day plan.
+fn create_fleet(days: usize) -> Fleet {
+    (0..days)
+        .fold(FleetBuilder::default().add_driver(test_driver()), |builder, day| {
+            builder.add_vehicle(
+                TestVehicleBuilder::default()
+                    .id(format!("day_{day}").as_str())
+                    .details(vec![VehicleDetail {
+                        start: Some(VehiclePlace {
+                            location: 0,
+                            time: TimeInterval { earliest: Some(day as Timestamp * DAY), latest: None },
+                        }),
+                        end: None,
+                    }])
+                    .build(),
+            )
+        })
+        .build()
+}
+
+fn create_objective(fleet: &Fleet) -> Arc<dyn FeatureObjective> {
+    create_prefer_early_tours_feature("prefer_early_tours", get_earliest_shift_start(fleet)).unwrap().objective.unwrap()
+}
+
+/// Creates a route on the given day's shift with `job_count` jobs in its tour.
+fn create_route_ctx(fleet: &Fleet, day: usize, job_count: usize) -> RouteContext {
+    let route = RouteBuilder::default()
+        .with_vehicle(fleet, format!("day_{day}").as_str())
+        .add_activities((0..job_count).map(|idx| ActivityBuilder::with_location(idx + 1).build()))
+        .build();
+
+    RouteContextBuilder::default().with_route(route).build()
+}
+
+parameterized_test! {can_estimate_delay_of_opening_a_shift, (day, expected), {
+    can_estimate_delay_of_opening_a_shift_impl(day, expected);
+}}
+
+can_estimate_delay_of_opening_a_shift! {
+    case_01_earliest_shift_is_free: (0, 0.),
+    case_02_next_day: (1, DAY),
+    case_03_last_day: (4, 4. * DAY),
+}
+
+fn can_estimate_delay_of_opening_a_shift_impl(day: usize, expected: Cost) {
+    let fleet = create_fleet(5);
+    let objective = create_objective(&fleet);
+    let route_ctx = create_route_ctx(&fleet, day, 0);
+    let solution_ctx = TestInsertionContextBuilder::default().build().solution;
+    let job = TestSingleBuilder::default().location(Some(1)).build_as_job_ref();
+
+    let result = objective.estimate(&MoveContext::route(&solution_ctx, &route_ctx, &job));
+
+    assert_eq!(result, expected);
+}
+
+parameterized_test! {can_estimate_nothing_for_a_shift_already_in_use, day, {
+    can_estimate_nothing_for_a_shift_already_in_use_impl(day);
+}}
+
+can_estimate_nothing_for_a_shift_already_in_use! {
+    case_01_earliest_shift: 0,
+    case_02_last_day: 4,
+}
+
+fn can_estimate_nothing_for_a_shift_already_in_use_impl(day: usize) {
+    let fleet = create_fleet(5);
+    let objective = create_objective(&fleet);
+    let route_ctx = create_route_ctx(&fleet, day, 2);
+    let solution_ctx = TestInsertionContextBuilder::default().build().solution;
+    let job = TestSingleBuilder::default().location(Some(1)).build_as_job_ref();
+
+    let result = objective.estimate(&MoveContext::route(&solution_ctx, &route_ctx, &job));
+
+    assert_eq!(result, 0.);
+}
+
+#[test]
+fn can_ignore_activity_position_within_tour() {
+    let fleet = create_fleet(5);
+    let objective = create_objective(&fleet);
+    let route_ctx = create_route_ctx(&fleet, 4, 2);
+    let solution_ctx = TestInsertionContextBuilder::default().build().solution;
+
+    let result = objective.estimate(&MoveContext::activity(
+        &solution_ctx,
+        &route_ctx,
+        &ActivityContext {
+            index: 0,
+            prev: &ActivityBuilder::with_location(1).build(),
+            target: &ActivityBuilder::with_location(2).build(),
+            next: None,
+        },
+    ));
+
+    assert_eq!(result, 0.);
+}
+
+parameterized_test! {can_estimate_fitness, (days_with_jobs, expected), {
+    can_estimate_fitness_impl(days_with_jobs, expected);
+}}
+
+can_estimate_fitness! {
+    case_01_all_work_in_first_shift: (vec![(0, 4)], 0.),
+    case_02_front_loaded: (vec![(0, 2), (1, 2)], DAY),
+    case_03_back_loaded: (vec![(3, 2), (4, 2)], 7. * DAY),
+    // the same two days cost the same however the work is split between them: the objective picks
+    // which days are worked, not what goes on each
+    case_04_split_does_not_matter: (vec![(0, 1), (1, 3)], DAY),
+    case_05_empty_late_route_is_free: (vec![(0, 4), (4, 0)], 0.),
+}
+
+fn can_estimate_fitness_impl(days_with_jobs: Vec<(usize, usize)>, expected: Cost) {
+    let fleet = create_fleet(5);
+    let objective = create_objective(&fleet);
+    let routes = days_with_jobs.iter().map(|&(day, jobs)| create_route_ctx(&fleet, day, jobs)).collect();
+    let insertion_ctx = TestInsertionContextBuilder::default().with_routes(routes).build();
+
+    let result = objective.fitness(&insertion_ctx);
+
+    assert_eq!(result, expected);
+}
+
+#[test]
+fn can_use_first_job_arrival_floor_when_shift_start_is_relaxed() {
+    // `allow_out_of_hours_depot_travel` relaxes the shift's start bound, so `detail.time.start`
+    // collapses to zero and the floor carries the real shift start.
+    let vehicle = {
+        let mut builder = TestVehicleBuilder::default();
+        builder.id("relaxed").details(vec![VehicleDetail {
+            start: Some(VehiclePlace { location: 0, time: TimeInterval { earliest: None, latest: None } }),
+            end: None,
+        }]);
+        builder.dimens_mut().set_first_job_arrival_floor(3. * DAY);
+        builder.build()
+    };
+    let fleet = FleetBuilder::default().add_driver(test_driver()).add_vehicle(vehicle).build();
+    let actor = get_test_actor_from_fleet(&fleet, "relaxed");
+
+    assert_eq!(actor.detail.time.start, 0.);
+    assert_eq!(get_shift_start(actor.as_ref()), 3. * DAY);
+}

vrp-pragmatic/tests/features/objectives/mod.rs

@@ -1 +1,2 @@
 mod minimize_depot_travel_time;
+mod prefer_early_tours;

vrp-pragmatic/tests/features/objectives/prefer_early_tours.rs

@@ -0,0 +1,90 @@
+use crate::format::problem::Objective::*;
+use crate::format::problem::*;
+use crate::format_time;
+use crate::helpers::*;
+
+#[test]
+fn can_round_trip_prefer_early_tours_objective() {
+    let json = r#"{"type":"prefer-early-tours"}"#;
+
+    let objective: Objective = serde_json::from_str(json).expect("cannot deserialize objective");
+    assert!(matches!(objective, PreferEarlyTours));
+
+    let serialized = serde_json::to_string(&objective).expect("cannot serialize objective");
+    assert_eq!(serialized, json);
+}
+
+/// Builds a problem with one job and two single-shift vehicles: `early` starts first but its depot
+/// is far from the job, `late` starts a day later but is parked on top of it. Cost alone therefore
+/// prefers `late`.
+fn create_problem(objectives: Option<Vec<Objective>>, out_of_hours_travel: bool) -> Problem {
+    let shift = |earliest: f64, latest: f64, location: (f64, f64)| VehicleShift {
+        start: ShiftStart { earliest: format_time(earliest), latest: None, location: location.to_loc() },
+        end: Some(ShiftEnd { earliest: None, latest: format_time(latest), location: location.to_loc() }),
+        ..create_default_vehicle_shift()
+    };
+
+    let limits = || {
+        out_of_hours_travel.then_some(VehicleLimits {
+            max_distance: None,
+            max_duration: None,
+            tour_size: None,
+            allow_out_of_hours_depot_travel: Some(true),
+        })
+    };
+
+    Problem {
+        plan: Plan { jobs: vec![create_delivery_job("job1", (100., 0.))], ..create_empty_plan() },
+        fleet: Fleet {
+            vehicles: vec![
+                VehicleType {
+                    shifts: vec![shift(0., 1000., (0., 0.))],
+                    limits: limits(),
+                    ..create_default_vehicle("early")
+                },
+                VehicleType {
+                    shifts: vec![shift(10000., 11000., (100., 0.))],
+                    limits: limits(),
+                    ..create_default_vehicle("late")
+                },
+            ],
+            ..create_default_fleet()
+        },
+        objectives,
+    }
+}
+
+fn solve(objectives: Option<Vec<Objective>>, out_of_hours_travel: bool) -> String {
+    let problem = create_problem(objectives, out_of_hours_travel);
+    let matrix = create_matrix_from_problem(&problem);
+
+    let solution = solve_with_metaheuristic(problem, Some(vec![matrix]));
+
+    solution.tours.first().expect("no tours in solution").vehicle_id.clone()
+}
+
+#[test]
+fn can_prefer_cheaper_later_shift_without_objective() {
+    assert_eq!(solve(None, false), "late_1");
+}
+
+#[test]
+fn can_prefer_earliest_shift_over_cost() {
+    let vehicle_id = solve(objectives(), false);
+
+    assert_eq!(vehicle_id, "early_1");
+}
+
+#[test]
+fn can_prefer_earliest_shift_with_out_of_hours_depot_travel() {
+    // `allow_out_of_hours_depot_travel` relaxes the shift's start bound to `None`, so the actor's
+    // start time collapses to zero and every shift would look equally early. The objective reads
+    // the first job arrival floor instead, which keeps the real shift start.
+    let vehicle_id = solve(objectives(), true);
+
+    assert_eq!(vehicle_id, "early_1");
+}
+
+fn objectives() -> Option<Vec<Objective>> {
+    Some(vec![MinimizeUnassigned { breaks: None }, MinimizeTours, PreferEarlyTours, MinimizeCost])
+}

vrp-pragmatic/tests/unit/validation/objectives_test.rs

@@ -207,3 +207,51 @@ fn can_detect_missing_value_objective_impl(objectives: Option<Vec<Objective>>, e
 
     assert_eq!(result.err().map(|e| e.code), expected);
 }
+
+parameterized_test! {can_detect_unguarded_prefer_early_tours, (objectives, expected), {
+    can_detect_unguarded_prefer_early_tours_impl(objectives, expected);
+}}
+
+can_detect_unguarded_prefer_early_tours! {
+    case01_no_guard: (vec![PreferEarlyTours, MinimizeTours, MinimizeDuration], Some("E1608".to_string())),
+    case02_guarded_by_unassigned: (
+        vec![MinimizeUnassigned { breaks: None }, PreferEarlyTours, MinimizeDuration], None),
+    case03_guarded_by_value: (
+        vec![MaximizeValue { breaks: None }, PreferEarlyTours, MinimizeDuration], None),
+    // a guard ranked below never gets consulted: the first differing layer decides
+    case04_guard_below_is_not_a_guard: (
+        vec![PreferEarlyTours, MinimizeUnassigned { breaks: None }, MinimizeDuration],
+        Some("E1608".to_string())),
+    // the same tier is not "above": neither outranks the other inside one layer
+    case05_guard_in_same_tier: (
+        vec![
+            MultiObjective {
+                strategy: MultiStrategy::Sum,
+                objectives: vec![MinimizeUnassigned { breaks: None }, PreferEarlyTours],
+            },
+            MinimizeDuration,
+        ],
+        Some("E1608".to_string())),
+    case06_guard_in_higher_tier: (
+        vec![
+            MultiObjective {
+                strategy: MultiStrategy::Sum,
+                objectives: vec![MinimizeUnassigned { breaks: None }, MinimizeTours],
+            },
+            PreferEarlyTours,
+            MinimizeDuration,
+        ],
+        None),
+    case07_objective_absent: (vec![MinimizeTours, MinimizeDuration], None),
+}
+
+fn can_detect_unguarded_prefer_early_tours_impl(objectives: Vec<Objective>, expected: Option<String>) {
+    let problem = Problem { objectives: Some(objectives), ..create_empty_problem() };
+    let coord_index = CoordIndex::new(&problem);
+    let ctx = ValidationContext::new(&problem, None, &coord_index);
+    let objectives = get_objectives(&ctx).unwrap();
+
+    let result = check_e1608_unguarded_prefer_early_tours(&objectives);
+
+    assert_eq!(result.err().map(|err| err.code), expected);
+}