Support <forager><breakTieRandomly>false</></> to for QA testing purp…

…oses

optaplanner-core/src/main/java/org/optaplanner/core/config/localsearch/decider/forager/LocalSearchForagerConfig.java

@@ -21,8 +21,6 @@
 import org.optaplanner.core.config.util.ConfigUtils;
 import org.optaplanner.core.impl.localsearch.decider.forager.AcceptedForager;
 import org.optaplanner.core.impl.localsearch.decider.forager.Forager;
-import org.optaplanner.core.impl.localsearch.decider.forager.finalist.FinalistPodium;
-import org.optaplanner.core.impl.localsearch.decider.forager.finalist.HighestScoreFinalistPodium;
 
 import static org.apache.commons.lang3.ObjectUtils.defaultIfNull;
 
@@ -34,6 +32,7 @@ public class LocalSearchForagerConfig {
     protected LocalSearchPickEarlyType pickEarlyType = null;
     protected Integer acceptedCountLimit = null;
     protected FinalistPodiumType finalistPodiumType = null;
+    protected Boolean breakTieRandomly = null;
 
     public Class<? extends Forager> getForagerClass() {
         return foragerClass;
@@ -67,6 +66,14 @@ public void setFinalistPodiumType(FinalistPodiumType finalistPodiumType) {
         this.finalistPodiumType = finalistPodiumType;
     }
 
+    public Boolean getBreakTieRandomly() {
+        return breakTieRandomly;
+    }
+
+    public void setBreakTieRandomly(Boolean breakTieRandomly) {
+        this.breakTieRandomly = breakTieRandomly;
+    }
+
     // ************************************************************************
     // Builder methods
     // ************************************************************************
@@ -84,7 +91,9 @@ public Forager buildForager(HeuristicConfigPolicy configPolicy) {
         LocalSearchPickEarlyType pickEarlyType_ = defaultIfNull(pickEarlyType, LocalSearchPickEarlyType.NEVER);
         int acceptedCountLimit_ = defaultIfNull(acceptedCountLimit, Integer.MAX_VALUE);
         FinalistPodiumType finalistPodiumType_ = defaultIfNull(finalistPodiumType, FinalistPodiumType.HIGHEST_SCORE);
-        return new AcceptedForager(finalistPodiumType_.buildFinalistPodium(), pickEarlyType_, acceptedCountLimit_);
+        // Breaking ties randomly leads statistically to much better results
+        boolean breakTieRandomly_  = defaultIfNull(breakTieRandomly, true);
+        return new AcceptedForager(finalistPodiumType_.buildFinalistPodium(), pickEarlyType_, acceptedCountLimit_, breakTieRandomly_);
     }
 
     public void inherit(LocalSearchForagerConfig inheritedConfig) {
@@ -96,6 +105,8 @@ public void inherit(LocalSearchForagerConfig inheritedConfig) {
                 inheritedConfig.getAcceptedCountLimit());
         finalistPodiumType = ConfigUtils.inheritOverwritableProperty(finalistPodiumType,
                 inheritedConfig.getFinalistPodiumType());
+        breakTieRandomly = ConfigUtils.inheritOverwritableProperty(breakTieRandomly,
+                inheritedConfig.getBreakTieRandomly());
     }
 
 }

optaplanner-core/src/main/java/org/optaplanner/core/impl/localsearch/decider/forager/AcceptedForager.java

@@ -16,6 +16,8 @@
 
 package org.optaplanner.core.impl.localsearch.decider.forager;
 
+import java.util.List;
+
 import org.optaplanner.core.api.score.Score;
 import org.optaplanner.core.config.localsearch.decider.forager.LocalSearchPickEarlyType;
 import org.optaplanner.core.impl.localsearch.decider.acceptor.Acceptor;
@@ -35,21 +37,23 @@ public class AcceptedForager extends AbstractForager {
     protected final FinalistPodium finalistPodium;
     protected final LocalSearchPickEarlyType pickEarlyType;
     protected final int acceptedCountLimit;
+    protected final boolean breakTieRandomly;
 
     protected long selectedMoveCount;
     protected long acceptedMoveCount;
 
     protected LocalSearchMoveScope earlyPickedMoveScope;
 
     public AcceptedForager(FinalistPodium finalistPodium,
-            LocalSearchPickEarlyType pickEarlyType, int acceptedCountLimit) {
+            LocalSearchPickEarlyType pickEarlyType, int acceptedCountLimit, boolean breakTieRandomly) {
         this.finalistPodium = finalistPodium;
         this.pickEarlyType = pickEarlyType;
         this.acceptedCountLimit = acceptedCountLimit;
         if (acceptedCountLimit < 1) {
             throw new IllegalArgumentException("The acceptedCountLimit (" + acceptedCountLimit
                     + ") cannot be negative or zero.");
         }
+        this.breakTieRandomly = breakTieRandomly;
     }
 
     // ************************************************************************
@@ -123,7 +127,15 @@ public LocalSearchMoveScope pickMove(LocalSearchStepScope stepScope) {
         if (earlyPickedMoveScope != null) {
             return earlyPickedMoveScope;
         }
-        return finalistPodium.pickMove(stepScope);
+        List<LocalSearchMoveScope> finalistList = finalistPodium.getFinalistList();
+        if (finalistList.isEmpty()) {
+            return null;
+        }
+        if (finalistList.size() == 1 || !breakTieRandomly) {
+            return finalistList.get(0);
+        }
+        int randomIndex = stepScope.getWorkingRandom().nextInt(finalistList.size());
+        return finalistList.get(randomIndex);
     }
 
     @Override

optaplanner-core/src/main/java/org/optaplanner/core/impl/localsearch/decider/forager/finalist/AbstractFinalistPodium.java

@@ -44,15 +44,8 @@ public void stepStarted(LocalSearchStepScope stepScope) {
         finalistList = new ArrayList<LocalSearchMoveScope>(1024);
     }
 
-    public LocalSearchMoveScope pickMove(LocalSearchStepScope stepScope) {
-        if (finalistList.isEmpty()) {
-            return null;
-        }
-        if (finalistList.size() == 1) {
-            return finalistList.get(0);
-        }
-        int randomIndex = stepScope.getWorkingRandom().nextInt(finalistList.size());
-        return finalistList.get(randomIndex);
+    public List<LocalSearchMoveScope> getFinalistList() {
+        return finalistList;
     }
 
     @Override

optaplanner-core/src/main/java/org/optaplanner/core/impl/localsearch/decider/forager/finalist/FinalistPodium.java

@@ -16,6 +16,8 @@
 
 package org.optaplanner.core.impl.localsearch.decider.forager.finalist;
 
+import java.util.List;
+
 import org.optaplanner.core.impl.localsearch.decider.forager.Forager;
 import org.optaplanner.core.impl.localsearch.event.LocalSearchPhaseLifecycleListener;
 import org.optaplanner.core.impl.localsearch.scope.LocalSearchMoveScope;
@@ -35,10 +37,9 @@ public interface FinalistPodium extends LocalSearchPhaseLifecycleListener {
     void addMove(LocalSearchMoveScope moveScope);
 
     /**
-     * See {@link Forager#pickMove(LocalSearchStepScope)}.
-     * @param stepScope never null
-     * @return sometimes null, for example if no move is selected
+     *
+     * @return never null, sometimes empty
      */
-    LocalSearchMoveScope pickMove(LocalSearchStepScope stepScope);
+    List<LocalSearchMoveScope> getFinalistList();
 
 }

optaplanner-core/src/test/java/org/optaplanner/core/impl/localsearch/decider/forager/AcceptedForagerTest.java

@@ -41,7 +41,7 @@ public class AcceptedForagerTest {
     public void pickMoveMaxScoreAccepted() {
         // Setup
         Forager forager = new AcceptedForager(new HighestScoreFinalistPodium(),
-                LocalSearchPickEarlyType.NEVER, Integer.MAX_VALUE);
+                LocalSearchPickEarlyType.NEVER, Integer.MAX_VALUE, true);
         LocalSearchPhaseScope phaseScope = createPhaseScope();
         forager.phaseStarted(phaseScope);
         LocalSearchStepScope stepScope = createStepScope(phaseScope);
@@ -73,7 +73,7 @@ public void pickMoveMaxScoreAccepted() {
     public void pickMoveMaxScoreUnaccepted() {
         // Setup
         Forager forager = new AcceptedForager(new HighestScoreFinalistPodium(),
-                LocalSearchPickEarlyType.NEVER, Integer.MAX_VALUE);
+                LocalSearchPickEarlyType.NEVER, Integer.MAX_VALUE, true);
         LocalSearchPhaseScope phaseScope = createPhaseScope();
         forager.phaseStarted(phaseScope);
         LocalSearchStepScope stepScope = createStepScope(phaseScope);
@@ -105,7 +105,7 @@ public void pickMoveMaxScoreUnaccepted() {
     public void pickMoveFirstBestScoreImproving() {
         // Setup
         Forager forager = new AcceptedForager(new HighestScoreFinalistPodium(),
-                LocalSearchPickEarlyType.FIRST_BEST_SCORE_IMPROVING, Integer.MAX_VALUE);
+                LocalSearchPickEarlyType.FIRST_BEST_SCORE_IMPROVING, Integer.MAX_VALUE, true);
         LocalSearchPhaseScope phaseScope = createPhaseScope();
         forager.phaseStarted(phaseScope);
         LocalSearchStepScope stepScope = createStepScope(phaseScope);
@@ -134,7 +134,7 @@ public void pickMoveFirstBestScoreImproving() {
     public void pickMoveFirstLastStepScoreImproving() {
         // Setup
         Forager forager = new AcceptedForager(new HighestScoreFinalistPodium(),
-                LocalSearchPickEarlyType.FIRST_LAST_STEP_SCORE_IMPROVING, Integer.MAX_VALUE);
+                LocalSearchPickEarlyType.FIRST_LAST_STEP_SCORE_IMPROVING, Integer.MAX_VALUE, true);
         LocalSearchPhaseScope phaseScope = createPhaseScope();
         forager.phaseStarted(phaseScope);
         LocalSearchStepScope stepScope = createStepScope(phaseScope);
@@ -160,10 +160,10 @@ public void pickMoveFirstLastStepScoreImproving() {
     }
 
     @Test
-    public void pickMoveAcceptedRandomly() {
+    public void pickMoveAcceptedBreakTieRandomly() {
         // Setup
         Forager forager = new AcceptedForager(new HighestScoreFinalistPodium(),
-                LocalSearchPickEarlyType.NEVER, 3);
+                LocalSearchPickEarlyType.NEVER, 4, true);
         LocalSearchPhaseScope phaseScope = createPhaseScope();
         forager.phaseStarted(phaseScope);
         LocalSearchStepScope stepScope = createStepScope(phaseScope);
@@ -173,6 +173,7 @@ public void pickMoveAcceptedRandomly() {
         LocalSearchMoveScope b = createMoveScope(stepScope, SimpleScore.valueOf(-1), true);
         LocalSearchMoveScope c = createMoveScope(stepScope, SimpleScore.valueOf(-1), true);
         LocalSearchMoveScope d = createMoveScope(stepScope, SimpleScore.valueOf(-20), true);
+        LocalSearchMoveScope e = createMoveScope(stepScope, SimpleScore.valueOf(-1), true);
         // Do stuff
         forager.addMove(a);
         assertFalse(forager.isQuitEarly());
@@ -181,6 +182,40 @@ public void pickMoveAcceptedRandomly() {
         forager.addMove(c);
         assertFalse(forager.isQuitEarly());
         forager.addMove(d);
+        assertFalse(forager.isQuitEarly());
+        forager.addMove(e);
+        assertTrue(forager.isQuitEarly());
+        // Post conditions
+        LocalSearchMoveScope pickedScope = forager.pickMove(stepScope);
+        assertSame(c, pickedScope);
+        forager.phaseEnded(phaseScope);
+    }
+
+    @Test
+    public void pickMoveAcceptedBreakTieFirst() {
+        // Setup
+        Forager forager = new AcceptedForager(new HighestScoreFinalistPodium(),
+                LocalSearchPickEarlyType.NEVER, 4, false);
+        LocalSearchPhaseScope phaseScope = createPhaseScope();
+        forager.phaseStarted(phaseScope);
+        LocalSearchStepScope stepScope = createStepScope(phaseScope);
+        forager.stepStarted(stepScope);
+        // Pre conditions
+        LocalSearchMoveScope a = createMoveScope(stepScope, SimpleScore.valueOf(-20), false);
+        LocalSearchMoveScope b = createMoveScope(stepScope, SimpleScore.valueOf(-1), true);
+        LocalSearchMoveScope c = createMoveScope(stepScope, SimpleScore.valueOf(-1), true);
+        LocalSearchMoveScope d = createMoveScope(stepScope, SimpleScore.valueOf(-20), true);
+        LocalSearchMoveScope e = createMoveScope(stepScope, SimpleScore.valueOf(-1), true);
+        // Do stuff
+        forager.addMove(a);
+        assertFalse(forager.isQuitEarly());
+        forager.addMove(b);
+        assertFalse(forager.isQuitEarly());
+        forager.addMove(c);
+        assertFalse(forager.isQuitEarly());
+        forager.addMove(d);
+        assertFalse(forager.isQuitEarly());
+        forager.addMove(e);
         assertTrue(forager.isQuitEarly());
         // Post conditions
         LocalSearchMoveScope pickedScope = forager.pickMove(stepScope);
@@ -196,7 +231,7 @@ private LocalSearchPhaseScope createPhaseScope() {
         when(scoreDirector.getScoreDefinition()).thenReturn(new SimpleScoreDefinition());
         solverScope.setScoreDirector(scoreDirector);
         Random workingRandom = mock(Random.class);
-        when(workingRandom.nextInt(2)).thenReturn(0);
+        when(workingRandom.nextInt(3)).thenReturn(1);
         solverScope.setWorkingRandom(workingRandom);
         solverScope.setBestScore(SimpleScore.valueOf(-10));
         LocalSearchStepScope lastLocalSearchStepScope = new LocalSearchStepScope(phaseScope);

optaplanner-core/src/test/java/org/optaplanner/core/impl/localsearch/decider/forager/finalist/StrategicOscillationByLevelFinalistPodiumTest.java

@@ -27,6 +27,7 @@
 
 import static org.junit.Assert.*;
 import static org.mockito.Mockito.*;
+import static org.optaplanner.core.impl.testdata.util.PlannerAssert.extractSingleton;
 
 public class StrategicOscillationByLevelFinalistPodiumTest {
 
@@ -49,7 +50,7 @@ public void referenceLastStepScore() {
         finalistPodium.addMove(moveScope0);
         finalistPodium.addMove(buildMoveScope(stepScope0, -100, -7100));
         finalistPodium.addMove(buildMoveScope(stepScope0, -200, -1000));
-        assertSame(moveScope0, finalistPodium.pickMove(stepScope0));
+        assertSame(moveScope0, extractSingleton(finalistPodium.getFinalistList()));
         stepScope0.setScore(moveScope0.getScore());
         finalistPodium.stepEnded(stepScope0);
         phaseScope.setLastCompletedStepScope(stepScope0);
@@ -63,7 +64,7 @@ public void referenceLastStepScore() {
         finalistPodium.addMove(moveScope1);
         finalistPodium.addMove(buildMoveScope(stepScope1, -150, -2000));
         finalistPodium.addMove(buildMoveScope(stepScope1, -200, -1000));
-        assertSame(moveScope1, finalistPodium.pickMove(stepScope1));
+        assertSame(moveScope1, extractSingleton(finalistPodium.getFinalistList()));
         stepScope1.setScore(moveScope1.getScore());
         finalistPodium.stepEnded(stepScope1);
         phaseScope.setLastCompletedStepScope(stepScope1);
@@ -77,7 +78,7 @@ public void referenceLastStepScore() {
         finalistPodium.addMove(moveScope2);
         finalistPodium.addMove(buildMoveScope(stepScope2, -150, -2000));
         finalistPodium.addMove(buildMoveScope(stepScope2, -160, -500));
-        assertSame(moveScope2, finalistPodium.pickMove(stepScope2));
+        assertSame(moveScope2, extractSingleton(finalistPodium.getFinalistList()));
         stepScope2.setScore(moveScope2.getScore());
         finalistPodium.stepEnded(stepScope2);
         phaseScope.setLastCompletedStepScope(stepScope2);
@@ -102,7 +103,7 @@ public void referenceBestScore() {
         finalistPodium.addMove(moveScope0);
         finalistPodium.addMove(buildMoveScope(stepScope0, -100, -7100));
         finalistPodium.addMove(buildMoveScope(stepScope0, -200, -1000));
-        assertSame(moveScope0, finalistPodium.pickMove(stepScope0));
+        assertSame(moveScope0, extractSingleton(finalistPodium.getFinalistList()));
         stepScope0.setScore(moveScope0.getScore());
         finalistPodium.stepEnded(stepScope0);
         phaseScope.setLastCompletedStepScope(stepScope0);
@@ -117,7 +118,7 @@ public void referenceBestScore() {
         finalistPodium.addMove(moveScope1);
         finalistPodium.addMove(buildMoveScope(stepScope1, -150, -2000));
         finalistPodium.addMove(buildMoveScope(stepScope1, -200, -1000));
-        assertSame(moveScope1, finalistPodium.pickMove(stepScope1));
+        assertSame(moveScope1, extractSingleton(finalistPodium.getFinalistList()));
         stepScope1.setScore(moveScope1.getScore());
         finalistPodium.stepEnded(stepScope1);
         phaseScope.setLastCompletedStepScope(stepScope1);
@@ -132,7 +133,7 @@ public void referenceBestScore() {
         finalistPodium.addMove(moveScope2);
         finalistPodium.addMove(buildMoveScope(stepScope2, -150, -2000));
         finalistPodium.addMove(buildMoveScope(stepScope2, -160, -500));
-        assertSame(moveScope2, finalistPodium.pickMove(stepScope2));
+        assertSame(moveScope2, extractSingleton(finalistPodium.getFinalistList()));
         stepScope2.setScore(moveScope2.getScore());
         finalistPodium.stepEnded(stepScope2);
         phaseScope.setLastCompletedStepScope(stepScope2);
@@ -167,7 +168,7 @@ public void referenceLastStepScore3Levels() {
         finalistPodium.addMove(moveScope0);
         finalistPodium.addMove(buildMoveScope(stepScope0, -100, -7100, -5));
         finalistPodium.addMove(buildMoveScope(stepScope0, -200, -1000, -10));
-        assertSame(moveScope0, finalistPodium.pickMove(stepScope0));
+        assertSame(moveScope0, extractSingleton(finalistPodium.getFinalistList()));
         stepScope0.setScore(moveScope0.getScore());
         finalistPodium.stepEnded(stepScope0);
         phaseScope.setLastCompletedStepScope(stepScope0);
@@ -181,7 +182,7 @@ public void referenceLastStepScore3Levels() {
         finalistPodium.addMove(moveScope1);
         finalistPodium.addMove(buildMoveScope(stepScope1, -150, -2000, -10));
         finalistPodium.addMove(buildMoveScope(stepScope1, -200, -1000, -10));
-        assertSame(moveScope1, finalistPodium.pickMove(stepScope1));
+        assertSame(moveScope1, extractSingleton(finalistPodium.getFinalistList()));
         stepScope1.setScore(moveScope1.getScore());
         finalistPodium.stepEnded(stepScope1);
         phaseScope.setLastCompletedStepScope(stepScope1);
@@ -195,7 +196,7 @@ public void referenceLastStepScore3Levels() {
         finalistPodium.addMove(moveScope2);
         finalistPodium.addMove(buildMoveScope(stepScope2, -150, -2000, -10));
         finalistPodium.addMove(buildMoveScope(stepScope2, -160, -500, -10));
-        assertSame(moveScope2, finalistPodium.pickMove(stepScope2));
+        assertSame(moveScope2, extractSingleton(finalistPodium.getFinalistList()));
         stepScope2.setScore(moveScope2.getScore());
         finalistPodium.stepEnded(stepScope2);
         phaseScope.setLastCompletedStepScope(stepScope2);

optaplanner-core/src/test/java/org/optaplanner/core/impl/testdata/util/PlannerAssert.java

@@ -380,6 +380,11 @@ public static void assertAllCodesOfSubChainSelector(SubChainSelector subChainSel
         }
     }
 
+    public static <E> E extractSingleton(List<E> singletonList) {
+        assertEquals(1, singletonList.size());
+        return singletonList.get(0);
+    }
+
     private PlannerAssert() {
     }