chore: improve restart logic

Author: zepfred

core/src/main/java/ai/timefold/solver/core/impl/localsearch/decider/acceptor/AcceptorFactory.java

@@ -17,8 +17,8 @@
 import ai.timefold.solver.core.impl.localsearch.decider.acceptor.lateacceptance.LateAcceptanceAcceptor;
 import ai.timefold.solver.core.impl.localsearch.decider.acceptor.simulatedannealing.SimulatedAnnealingAcceptor;
 import ai.timefold.solver.core.impl.localsearch.decider.acceptor.stepcountinghillclimbing.StepCountingHillClimbingAcceptor;
+import ai.timefold.solver.core.impl.localsearch.decider.acceptor.stuckcriterion.DiminishedReturnsStuckCriterion;
 import ai.timefold.solver.core.impl.localsearch.decider.acceptor.stuckcriterion.StuckCriterion;
-import ai.timefold.solver.core.impl.localsearch.decider.acceptor.stuckcriterion.UnimprovedTimeStuckCriterion;
 import ai.timefold.solver.core.impl.localsearch.decider.acceptor.tabu.EntityTabuAcceptor;
 import ai.timefold.solver.core.impl.localsearch.decider.acceptor.tabu.MoveTabuAcceptor;
 import ai.timefold.solver.core.impl.localsearch.decider.acceptor.tabu.ValueTabuAcceptor;
@@ -222,7 +222,7 @@ private Optional<MoveTabuAcceptor<Solution_>> buildMoveTabuAcceptor(HeuristicCon
         if (acceptorTypeListsContainsAcceptorType(AcceptorType.LATE_ACCEPTANCE)
                 || (!acceptorTypeListsContainsAcceptorType(AcceptorType.DIVERSIFIED_LATE_ACCEPTANCE)
                         && acceptorConfig.getLateAcceptanceSize() != null)) {
-            StuckCriterion<Solution_> strategy = new UnimprovedTimeStuckCriterion<>();
+            StuckCriterion<Solution_> strategy = new DiminishedReturnsStuckCriterion<>();
             var acceptor = new LateAcceptanceAcceptor<>(strategy);
             acceptor.setLateAcceptanceSize(Objects.requireNonNullElse(acceptorConfig.getLateAcceptanceSize(), 400));
             return Optional.of(acceptor);

core/src/main/java/ai/timefold/solver/core/impl/localsearch/decider/acceptor/RestartableAcceptor.java

@@ -52,14 +52,29 @@ public void stepEnded(LocalSearchStepScope<Solution_> stepScope) {
     @Override
     public boolean isAccepted(LocalSearchMoveScope<Solution_> moveScope) {
         if (stuckCriterion.isSolverStuck(moveScope)) {
-            moveScope.getStepScope().getPhaseScope().setSolverStuck(true);
-            restartTriggered = true;
-            return true;
+            if (rejectRestartEvent()) {
+                // We need to reset the criterion,
+                // or it will trigger the restart event in the next evaluation
+                stuckCriterion.reset(moveScope.getStepScope());
+            } else {
+                moveScope.getStepScope().getPhaseScope().setSolverStuck(true);
+                restartTriggered = true;
+                return true;
+            }
         }
         return accept(moveScope);
     }
 
     protected abstract boolean accept(LocalSearchMoveScope<Solution_> moveScope);
 
+    /**
+     * The stuck criterion may trigger a restart event, but the acceptor might choose to delay it.
+     * This method rechecks the restart event condition on the acceptor side.
+     */
+    public abstract boolean rejectRestartEvent();
+
+    /**
+     * Run the restart event logic on the acceptor side.
+     */
     public abstract void restart(LocalSearchStepScope<Solution_> stepScope);
 }

core/src/main/java/ai/timefold/solver/core/impl/localsearch/decider/acceptor/lateacceptance/LateAcceptanceAcceptor.java

@@ -125,33 +125,35 @@ public void stepEnded(LocalSearchStepScope<Solution_> stepScope) {
     }
 
     @Override
-    public void restart(LocalSearchStepScope<Solution_> stepScope) {
-        countRestartWithoutImprovement++;
+    public boolean rejectRestartEvent() {
         var distinctElements = Arrays.stream(previousScores).distinct().count();
         var diversity = distinctElements == 1 ? 0 : distinctElements / (double) lateAcceptanceSize;
-        if (coefficient == 0 && (diversity > MIN_DIVERSITY_RATIO || bestScoreQueue.size() == 1)) {
-            // We prefer not to restart until the first event has passed (about 10:30 minutes).
-            // We have observed that this approach works better for more complex datasets.
-            // However, when the diversity is zero, it indicates that the LA may be stuck in a local minimum,
-            // and in such cases, we should restart before the first event.
-            // Additionally, when there is only one best score,
-            // it does not make sense to restart as nothing would change
-            // and the proposed approach requires some diversity to reseed the scores.
+        // We prefer not to restart until the first event has passed (about 10:30 minutes).
+        // We have observed that this approach works better for more complex datasets.
+        // However, when the diversity is zero, it indicates that the LA may be stuck in a local minimum,
+        // and in such cases, we should restart before the first event.
+        // Additionally, when there is only one best score,
+        // it does not make sense to restart as nothing would change
+        // and the proposed approach requires some diversity to reseed the scores.
+        var reject = coefficient == 0 && (diversity > MIN_DIVERSITY_RATIO || bestScoreQueue.size() == 1);
+        if (reject) {
             logger.info(
                     "Restart event delayed. Diversity ({}), Count best scores ({}), Distinct Elements ({}), Restart without Improvement ({})",
-                    bestScoreQueue.size(), diversity, distinctElements, countRestartWithoutImprovement);
-            return;
+                    diversity, bestScoreQueue.size(), distinctElements, countRestartWithoutImprovement);
         }
+        return reject;
+    }
+
+    @Override
+    public void restart(LocalSearchStepScope<Solution_> stepScope) {
+        countRestartWithoutImprovement++;
         coefficient++;
         var newLateAcceptanceSize = defaultLateAcceptanceSize * coefficient * SCALING_FACTOR;
         if (logger.isInfoEnabled()) {
             if (lateAcceptanceSize == newLateAcceptanceSize) {
-                logger.info("Keeping the lateAcceptanceSize as {}. Diversity ({}), Distinct Elements ({})", lateAcceptanceSize,
-                        diversity, distinctElements);
+                logger.info("Keeping the lateAcceptanceSize as {}.", lateAcceptanceSize);
             } else {
-                logger.info(
-                        "Changing the lateAcceptanceSize from {} to {}. Diversity ({}), Distinct Elements ({})",
-                        lateAcceptanceSize, newLateAcceptanceSize, diversity, distinctElements);
+                logger.info("Changing the lateAcceptanceSize from {} to {}.", lateAcceptanceSize, newLateAcceptanceSize);
             }
         }
         rebuildLateElementsList(newLateAcceptanceSize);

core/src/main/java/ai/timefold/solver/core/impl/localsearch/decider/acceptor/stuckcriterion/DiminishedReturnsStuckCriterion.java

@@ -38,16 +38,21 @@ boolean evaluateCriterion(LocalSearchMoveScope<Solution_> moveScope) {
         return triggered;
     }
 
+    @Override
+    public void reset(LocalSearchStepScope<Solution_> stepScope) {
+        // We need to recreate the termination criterion as the time window has changed
+        // After the first restart we use a higher time window
+        setScalingFactor(REGULAR_TIME_WINDOW_MILLIS);
+        diminishedReturnsCriterion = new DiminishedReturnsTermination<>(nextRestart, MINIMAL_IMPROVEMENT);
+        diminishedReturnsCriterion.start(System.nanoTime(), stepScope.getPhaseScope().getBestScore());
+        triggered = false;
+    }
+
     @Override
     public void stepStarted(LocalSearchStepScope<Solution_> stepScope) {
         currentBestScore = stepScope.getPhaseScope().getBestScore();
         if (triggered) {
-            // We need to recreate the termination criterion as the time window has changed
-            // After the first restart we use a higher time window
-            setScalingFactor(REGULAR_TIME_WINDOW_MILLIS);
-            diminishedReturnsCriterion = new DiminishedReturnsTermination<>(nextRestart, MINIMAL_IMPROVEMENT);
-            diminishedReturnsCriterion.start(System.nanoTime(), stepScope.getPhaseScope().getBestScore());
-            triggered = false;
+            reset(stepScope);
         }
     }
 

core/src/main/java/ai/timefold/solver/core/impl/localsearch/decider/acceptor/stuckcriterion/StuckCriterion.java

@@ -3,6 +3,7 @@
 import ai.timefold.solver.core.api.solver.Solver;
 import ai.timefold.solver.core.impl.localsearch.event.LocalSearchPhaseLifecycleListener;
 import ai.timefold.solver.core.impl.localsearch.scope.LocalSearchMoveScope;
+import ai.timefold.solver.core.impl.localsearch.scope.LocalSearchStepScope;
 
 /**
  * Allow defining strategies that identify when the {@link Solver solver} is stuck.
@@ -15,7 +16,8 @@ public interface StuckCriterion<Solution_> extends LocalSearchPhaseLifecycleList
      * Main logic that applies a specific metric to determine if a solver is stuck in a local optimum.
      * 
      * @param moveScope cannot be null
-     * @return
      */
     boolean isSolverStuck(LocalSearchMoveScope<Solution_> moveScope);
+
+    void reset(LocalSearchStepScope<Solution_> stepScope);
 }