fix: reset late list when upper levels of score changed (TimefoldAI#2407)

This has been shown to prevent exceptional situations where the solver would flatline immediately after start for a period of time determined by the LA list size, and in general dominates the previous late acceptor.

Author: zepfred

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

@@ -0,0 +1,73 @@
+package ai.timefold.solver.core.impl.localsearch.decider.acceptor.lateacceptance;
+
+import ai.timefold.solver.core.api.score.IBendableScore;
+import ai.timefold.solver.core.impl.localsearch.scope.LocalSearchStepScope;
+import ai.timefold.solver.core.impl.score.definition.ScoreDefinition;
+import ai.timefold.solver.core.impl.score.director.InnerScore;
+
+/**
+ * Default implementation of {@link LevelScoreState} for scores with more than one level.
+ * <p>
+ * Caches the best-solution step index and the corresponding score level values.
+ * On each step, {@link #update} refreshes the cache when the best solution has changed,
+ * and {@link #isNonDominatedLevelChanged} compares the non-dominated levels
+ * (hard for {@link IBendableScore IBendableScore}, hard and medium for all others)
+ * against the cached values to determine whether the {@link LateAcceptanceScoreBuffer} should be reset.
+ */
+final class DefaultLevelScoreState<Solution_> implements LevelScoreState<Solution_> {
+
+    private final int nonDominatedLevelCount;
+    private long previousBestScoreIndex;
+    private Number[] previousBestScoreLevels;
+
+    @SuppressWarnings("rawtypes")
+    DefaultLevelScoreState(InnerScore initialScore, ScoreDefinition scoreDefinition) {
+        previousBestScoreLevels = initialScore.raw().toLevelNumbers();
+        if (IBendableScore.class.isAssignableFrom(scoreDefinition.getScoreClass())) {
+            // We only evaluate the hard score levels
+            nonDominatedLevelCount = scoreDefinition.getFeasibleLevelsSize();
+        } else {
+            // We only evaluate the hard or medium levels
+            nonDominatedLevelCount = scoreDefinition.getLevelsSize() - 1;
+        }
+    }
+
+    @Override
+    public void update(LocalSearchStepScope<Solution_> stepScope) {
+        var phaseScope = stepScope.getPhaseScope();
+        var bestSolutionStepIndex = phaseScope.getBestSolutionStepIndex();
+        if (previousBestScoreIndex != bestSolutionStepIndex) {
+            // Update the current best score information
+            this.previousBestScoreIndex = bestSolutionStepIndex;
+            this.previousBestScoreLevels = stepScope.getPhaseScope().getBestScore().raw().toLevelNumbers();
+        }
+    }
+
+    /**
+     * If non-dominated levels are updated (hard or medium), it is necessary to reset the late scores.
+     * Failing to do so may cause the solver
+     * to accept poor moves that do not affect the non-dominated scores but degrade the soft scores.
+     * As a result,
+     * any move that does not decrease the hard or medium score
+     * but significantly worsens the soft score may be mistakenly accepted.
+     * This could cause the working solution
+     * to enter a bad region and require many additional steps to escape it.
+     *
+     * @return true if any non-dominated score has changed; otherwise, returns false
+     */
+    @Override
+    public boolean isNonDominatedLevelChanged(LocalSearchStepScope<Solution_> stepScope) {
+        var phaseScope = stepScope.getPhaseScope();
+        var bestSolutionStepIndex = phaseScope.getBestSolutionStepIndex();
+        if (previousBestScoreIndex != bestSolutionStepIndex) {
+            var newBestScore = stepScope.getPhaseScope().getBestScore();
+            var newBestScoreLevels = newBestScore.raw().toLevelNumbers();
+            for (var i = 0; i < nonDominatedLevelCount; i++) {
+                if (!newBestScoreLevels[i].equals(previousBestScoreLevels[i])) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+}

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

@@ -1,7 +1,5 @@
 package ai.timefold.solver.core.impl.localsearch.decider.acceptor.lateacceptance;
 
-import java.util.Arrays;
-
 import ai.timefold.solver.core.api.score.Score;
 import ai.timefold.solver.core.impl.localsearch.decider.acceptor.AbstractAcceptor;
 import ai.timefold.solver.core.impl.localsearch.scope.LocalSearchMoveScope;
@@ -14,8 +12,8 @@ public class LateAcceptanceAcceptor<Solution_> extends AbstractAcceptor<Solution
     protected int lateAcceptanceSize = -1;
     protected boolean hillClimbingEnabled = true;
 
-    protected InnerScore<?>[] previousScores;
-    protected int lateScoreIndex = -1;
+    private LateAcceptanceScoreBuffer scoreBuffer;
+    private LevelScoreState<Solution_> bestScoreState;
 
     public void setLateAcceptanceSize(int lateAcceptanceSize) {
         this.lateAcceptanceSize = lateAcceptanceSize;
@@ -33,10 +31,11 @@ public void setHillClimbingEnabled(boolean hillClimbingEnabled) {
     public void phaseStarted(LocalSearchPhaseScope<Solution_> phaseScope) {
         super.phaseStarted(phaseScope);
         validate();
-        previousScores = new InnerScore[lateAcceptanceSize];
         var initialScore = phaseScope.getBestScore();
-        Arrays.fill(previousScores, initialScore);
-        lateScoreIndex = 0;
+        scoreBuffer = new LateAcceptanceScoreBuffer(lateAcceptanceSize, initialScore);
+        var scoreDefinition = phaseScope.getSolverScope().getScoreDefinition();
+        bestScoreState = scoreDefinition.getLevelsSize() > 1 ? new DefaultLevelScoreState<>(initialScore, scoreDefinition)
+                : new NoOpLevelScoreState<>();
     }
 
     private void validate() {
@@ -50,7 +49,7 @@ private void validate() {
     @Override
     public boolean isAccepted(LocalSearchMoveScope<Solution_> moveScope) {
         var moveScore = (InnerScore) moveScope.getScore();
-        var lateScore = getPreviousScore(lateScoreIndex);
+        var lateScore = scoreBuffer.getCurrent();
         if (moveScore.compareTo(lateScore) >= 0) {
             return true;
         }
@@ -62,23 +61,30 @@ public boolean isAccepted(LocalSearchMoveScope<Solution_> moveScope) {
         return false;
     }
 
-    @SuppressWarnings("unchecked")
-    private <Score_ extends Score<Score_>> InnerScore<Score_> getPreviousScore(int lateScoreIndex) {
-        return (InnerScore<Score_>) previousScores[lateScoreIndex];
+    @Override
+    public void stepStarted(LocalSearchStepScope<Solution_> stepScope) {
+        super.stepStarted(stepScope);
+        bestScoreState.update(stepScope);
     }
 
     @Override
     public void stepEnded(LocalSearchStepScope<Solution_> stepScope) {
         super.stepEnded(stepScope);
-        previousScores[lateScoreIndex] = stepScope.getScore();
-        lateScoreIndex = (lateScoreIndex + 1) % lateAcceptanceSize;
+        scoreBuffer.update(stepScope.getScore());
+        if (bestScoreState.isNonDominatedLevelChanged(stepScope)) {
+            scoreBuffer.tryReset(stepScope.getPhaseScope().getBestScore());
+        }
     }
 
     @Override
     public void phaseEnded(LocalSearchPhaseScope<Solution_> phaseScope) {
         super.phaseEnded(phaseScope);
-        previousScores = null;
-        lateScoreIndex = -1;
+        scoreBuffer = null;
+        bestScoreState = null;
+    }
+
+    protected <Score_ extends Score<Score_>> InnerScore<Score_> getScore(int i) {
+        return scoreBuffer.get(i);
     }
 
 }

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

@@ -0,0 +1,78 @@
+package ai.timefold.solver.core.impl.localsearch.decider.acceptor.lateacceptance;
+
+import java.util.Arrays;
+import java.util.Objects;
+
+import ai.timefold.solver.core.api.score.Score;
+import ai.timefold.solver.core.impl.score.director.InnerScore;
+
+/**
+ * Circular buffer implementation for managing late scores,
+ * enabling simpler reset logic.
+ * When {@link #tryReset} is called,
+ * instead of filling all slots,
+ * an epoch counter is incremented,
+ * allowing the action to avoid reloading the score array with the new score.
+ */
+final class LateAcceptanceScoreBuffer {
+
+    // Late score fields
+    private final InnerScore<?>[] scores;
+    private int currentIndex = 0;
+    private final int size;
+    // All required epoch fields
+    private final long[] slotEpoch;
+    private long resetEpoch = 0;
+    private InnerScore<?> resetScore = null;
+    private boolean writtenSinceReset = false;
+
+    LateAcceptanceScoreBuffer(int size, InnerScore<?> initialScore) {
+        this.scores = new InnerScore[size];
+        Arrays.fill(scores, initialScore);
+        this.size = size;
+        // By default,
+        // the score is set to zero,
+        // and it means all scores will be read initially.
+        this.slotEpoch = new long[size];
+    }
+
+    <Score_ extends Score<Score_>> InnerScore<Score_> getCurrent() {
+        return get(currentIndex);
+    }
+
+    @SuppressWarnings("unchecked")
+    <Score_ extends Score<Score_>> InnerScore<Score_> get(int index) {
+        if (slotEpoch[index] < resetEpoch) {
+            return (InnerScore<Score_>) resetScore;
+        }
+        return (InnerScore<Score_>) scores[index];
+    }
+
+    /**
+     * Update the score and advance the current late index.
+     * 
+     * @param score the score to be added to the buffer
+     */
+    void update(InnerScore<?> score) {
+        scores[currentIndex] = score;
+        slotEpoch[currentIndex] = resetEpoch;
+        writtenSinceReset = true;
+        currentIndex = (currentIndex + 1) % size;
+    }
+
+    /**
+     * Lazily resets all slots to {@code newScore}.
+     * Updating the score array is unnecessary since the related counter ensures the new score is returned if no changes have
+     * occurred.
+     *
+     * @param newScore the score to be used to reset the buffer
+     */
+    void tryReset(InnerScore<?> newScore) {
+        // Skips the reset action when no slot has been written since the last reset and the score is unchanged
+        if (writtenSinceReset || !Objects.equals(newScore, resetScore)) {
+            resetScore = newScore;
+            resetEpoch++;
+            writtenSinceReset = false;
+        }
+    }
+}

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

@@ -0,0 +1,21 @@
+package ai.timefold.solver.core.impl.localsearch.decider.acceptor.lateacceptance;
+
+import ai.timefold.solver.core.impl.localsearch.scope.LocalSearchStepScope;
+
+/**
+ * Tracks whether the non-dominated score levels (hard or medium) have changed,
+ * so {@link LateAcceptanceAcceptor} can decide when to reset the {@link LateAcceptanceScoreBuffer}.
+ * <p>
+ * {@link DefaultLevelScoreState} is used when the score has more than one level and non-dominated
+ * level tracking is meaningful.
+ * {@link NoOpLevelScoreState} is used for single-level scores, where no reset is ever needed.
+ * 
+ * @see DefaultLevelScoreState
+ * @see NoOpLevelScoreState
+ */
+sealed interface LevelScoreState<Solution_> permits DefaultLevelScoreState, NoOpLevelScoreState {
+
+    void update(LocalSearchStepScope<Solution_> stepScope);
+
+    boolean isNonDominatedLevelChanged(LocalSearchStepScope<Solution_> stepScope);
+}

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

@@ -0,0 +1,16 @@
+package ai.timefold.solver.core.impl.localsearch.decider.acceptor.lateacceptance;
+
+import ai.timefold.solver.core.impl.localsearch.scope.LocalSearchStepScope;
+
+record NoOpLevelScoreState<Solution_>() implements LevelScoreState<Solution_> {
+
+    @Override
+    public void update(LocalSearchStepScope<Solution_> stepScope) {
+        // Do nothing
+    }
+
+    @Override
+    public boolean isNonDominatedLevelChanged(LocalSearchStepScope<Solution_> stepScope) {
+        return false;
+    }
+}