feat: support value range sorting in ValueSelectorFactory

Author: zepfred

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/value/FromEntityPropertyValueSelector.java

@@ -8,6 +8,7 @@
 import ai.timefold.solver.core.impl.domain.valuerange.descriptor.ValueRangeDescriptor;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.GenuineVariableDescriptor;
 import ai.timefold.solver.core.impl.heuristic.selector.AbstractDemandEnabledSelector;
+import ai.timefold.solver.core.impl.heuristic.selector.common.decorator.SelectionSorter;
 import ai.timefold.solver.core.impl.phase.scope.AbstractPhaseScope;
 import ai.timefold.solver.core.impl.score.director.InnerScoreDirector;
 import ai.timefold.solver.core.impl.solver.scope.SolverScope;
@@ -22,13 +23,16 @@ public final class FromEntityPropertyValueSelector<Solution_>
         implements ValueSelector<Solution_> {
 
     private final ValueRangeDescriptor<Solution_> valueRangeDescriptor;
+    private final SelectionSorter<Solution_, Object> selectionSorter;
     private final boolean randomSelection;
 
     private CountableValueRange<Object> countableValueRange;
     private InnerScoreDirector<Solution_, ?> scoreDirector;
 
-    public FromEntityPropertyValueSelector(ValueRangeDescriptor<Solution_> valueRangeDescriptor, boolean randomSelection) {
+    public FromEntityPropertyValueSelector(ValueRangeDescriptor<Solution_> valueRangeDescriptor,
+            SelectionSorter<Solution_, Object> selectionSorter, boolean randomSelection) {
         this.valueRangeDescriptor = valueRangeDescriptor;
+        this.selectionSorter = selectionSorter;
         this.randomSelection = randomSelection;
     }
 
@@ -51,7 +55,7 @@ public void solvingEnded(SolverScope<Solution_> solverScope) {
     @Override
     public void phaseStarted(AbstractPhaseScope<Solution_> phaseScope) {
         super.phaseStarted(phaseScope);
-        this.countableValueRange = scoreDirector.getValueRangeManager().getFromSolution(valueRangeDescriptor);
+        this.countableValueRange = scoreDirector.getValueRangeManager().getFromSolution(valueRangeDescriptor, selectionSorter);
     }
 
     @Override
@@ -63,6 +67,9 @@ public void phaseEnded(AbstractPhaseScope<Solution_> phaseScope) {
     // ************************************************************************
     // Worker methods
     // ************************************************************************
+    public SelectionSorter<Solution_, Object> getSelectionSorter() {
+        return selectionSorter;
+    }
 
     @Override
     public GenuineVariableDescriptor<Solution_> getVariableDescriptor() {
@@ -92,7 +99,7 @@ public long getSize(Object entity) {
 
     @Override
     public Iterator<Object> iterator(Object entity) {
-        var valueRange = scoreDirector.getValueRangeManager().getFromEntity(valueRangeDescriptor, entity);
+        var valueRange = scoreDirector.getValueRangeManager().getFromEntity(valueRangeDescriptor, entity, selectionSorter);
         if (!randomSelection) {
             return valueRange.createOriginalIterator();
         } else {
@@ -107,24 +114,22 @@ public Iterator<Object> endingIterator(Object entity) {
             // This logic aligns with the requirements for Nearby in the enterprise repository
             return countableValueRange.createOriginalIterator();
         } else {
-            var valueRange = scoreDirector.getValueRangeManager().getFromEntity(valueRangeDescriptor, entity);
+            var valueRange = scoreDirector.getValueRangeManager().getFromEntity(valueRangeDescriptor, entity, selectionSorter);
             return valueRange.createOriginalIterator();
         }
     }
 
     @Override
     public boolean equals(Object o) {
-        if (this == o)
-            return true;
-        if (o == null || getClass() != o.getClass())
+        if (!(o instanceof FromEntityPropertyValueSelector<?> that))
             return false;
-        FromEntityPropertyValueSelector<?> that = (FromEntityPropertyValueSelector<?>) o;
-        return randomSelection == that.randomSelection && Objects.equals(valueRangeDescriptor, that.valueRangeDescriptor);
+        return randomSelection == that.randomSelection && Objects.equals(valueRangeDescriptor, that.valueRangeDescriptor)
+                && Objects.equals(selectionSorter, that.selectionSorter);
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(valueRangeDescriptor, randomSelection);
+        return Objects.hash(valueRangeDescriptor, selectionSorter, randomSelection);
     }
 
     @Override

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/value/IterableFromSolutionPropertyValueSelector.java

@@ -10,6 +10,7 @@
 import ai.timefold.solver.core.impl.domain.valuerange.descriptor.ValueRangeDescriptor;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.GenuineVariableDescriptor;
 import ai.timefold.solver.core.impl.heuristic.selector.AbstractDemandEnabledSelector;
+import ai.timefold.solver.core.impl.heuristic.selector.common.decorator.SelectionSorter;
 import ai.timefold.solver.core.impl.phase.scope.AbstractPhaseScope;
 import ai.timefold.solver.core.impl.phase.scope.AbstractStepScope;
 
@@ -21,6 +22,7 @@ public final class IterableFromSolutionPropertyValueSelector<Solution_>
         implements IterableValueSelector<Solution_> {
 
     private final ValueRangeDescriptor<Solution_> valueRangeDescriptor;
+    private final SelectionSorter<Solution_, Object> sorter;
     private final SelectionCacheType minimumCacheType;
     private final boolean randomSelection;
     private final boolean valueRangeMightContainEntity;
@@ -30,8 +32,9 @@ public final class IterableFromSolutionPropertyValueSelector<Solution_>
     private boolean cachedEntityListIsDirty = false;
 
     public IterableFromSolutionPropertyValueSelector(ValueRangeDescriptor<Solution_> valueRangeDescriptor,
-            SelectionCacheType minimumCacheType, boolean randomSelection) {
+            SelectionSorter<Solution_, Object> sorter, SelectionCacheType minimumCacheType, boolean randomSelection) {
         this.valueRangeDescriptor = valueRangeDescriptor;
+        this.sorter = sorter;
         this.minimumCacheType = minimumCacheType;
         this.randomSelection = randomSelection;
         valueRangeMightContainEntity = valueRangeDescriptor.mightContainEntity();
@@ -57,7 +60,7 @@ public void phaseStarted(AbstractPhaseScope<Solution_> phaseScope) {
         super.phaseStarted(phaseScope);
         var scoreDirector = phaseScope.getScoreDirector();
         cachedValueRange = scoreDirector.getValueRangeManager().getFromSolution(valueRangeDescriptor,
-                scoreDirector.getWorkingSolution());
+                scoreDirector.getWorkingSolution(), sorter);
         if (valueRangeMightContainEntity) {
             cachedEntityListRevision = scoreDirector.getWorkingEntityListRevision();
             cachedEntityListIsDirty = false;
@@ -74,7 +77,7 @@ public void stepStarted(AbstractStepScope<Solution_> stepScope) {
                     cachedEntityListIsDirty = true;
                 } else {
                     cachedValueRange = scoreDirector.getValueRangeManager().getFromSolution(valueRangeDescriptor,
-                            scoreDirector.getWorkingSolution());
+                            scoreDirector.getWorkingSolution(), sorter);
                     cachedEntityListRevision = scoreDirector.getWorkingEntityListRevision();
                 }
             }
@@ -153,19 +156,16 @@ private void checkCachedEntityListIsDirty() {
     }
 
     @Override
-    public boolean equals(Object other) {
-        if (this == other)
-            return true;
-        if (other == null || getClass() != other.getClass())
+    public boolean equals(Object o) {
+        if (!(o instanceof IterableFromSolutionPropertyValueSelector<?> that))
             return false;
-        var that = (IterableFromSolutionPropertyValueSelector<?>) other;
-        return randomSelection == that.randomSelection &&
-                Objects.equals(valueRangeDescriptor, that.valueRangeDescriptor) && minimumCacheType == that.minimumCacheType;
+        return randomSelection == that.randomSelection && Objects.equals(valueRangeDescriptor, that.valueRangeDescriptor)
+                && Objects.equals(sorter, that.sorter) && minimumCacheType == that.minimumCacheType;
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(valueRangeDescriptor, minimumCacheType, randomSelection);
+        return Objects.hash(valueRangeDescriptor, sorter, minimumCacheType, randomSelection);
     }
 
     @Override

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/value/ValueSelectorFactory.java

@@ -122,10 +122,19 @@ public ValueSelector<Solution_> buildValueSelector(HeuristicConfigPolicy<Solutio
 
         // baseValueSelector and lower should be SelectionOrder.ORIGINAL if they are going to get cached completely
         var randomSelection = determineBaseRandomSelection(variableDescriptor, resolvedCacheType, resolvedSelectionOrder);
-        var valueSelector =
-                buildBaseValueSelector(variableDescriptor, SelectionCacheType.max(minimumCacheType, resolvedCacheType),
-                        randomSelection);
         var instanceCache = configPolicy.getClassInstanceCache();
+        /*
+         * When a filtering value range or nearby are used,
+         * we opt to sort the data using a sorting node selector instead of sorting at the value range level.
+         * This choice is required
+         * because the FilteringValueRangeSelector or the related Nearby selector does not respect the sort order
+         * provided by the child selectors.
+         */
+        var canSortAtValueRangeLevel = entityValueRangeRecorderId == null && nearbySelectionConfig == null;
+        var sorter =
+                canSortAtValueRangeLevel ? determineSorter(variableDescriptor, resolvedSelectionOrder, instanceCache) : null;
+        var valueSelector = buildBaseValueSelector(variableDescriptor, sorter,
+                SelectionCacheType.max(minimumCacheType, resolvedCacheType), randomSelection);
         if (nearbySelectionConfig != null) {
             // TODO Static filtering (such as movableEntitySelectionFilter) should affect nearbySelection too
             valueSelector = applyNearbySelection(configPolicy, entityDescriptor, minimumCacheType,
@@ -141,7 +150,9 @@ public ValueSelector<Solution_> buildValueSelector(HeuristicConfigPolicy<Solutio
         }
         valueSelector = applyFiltering(valueSelector, instanceCache);
         valueSelector = applyInitializedChainedValueFilter(configPolicy, variableDescriptor, valueSelector);
-        valueSelector = applySorting(resolvedCacheType, resolvedSelectionOrder, valueSelector, instanceCache);
+        if (!canSortAtValueRangeLevel) {
+            valueSelector = applySorting(resolvedCacheType, resolvedSelectionOrder, valueSelector, instanceCache);
+        }
         valueSelector = applyProbability(resolvedCacheType, resolvedSelectionOrder, valueSelector, instanceCache);
         valueSelector = applyShuffling(resolvedCacheType, resolvedSelectionOrder, valueSelector);
         valueSelector = applyCaching(resolvedCacheType, resolvedSelectionOrder, valueSelector);
@@ -260,8 +271,45 @@ private static Class<? extends ComparatorFactory> determineComparatorFactoryClas
         }
     }
 
+    private SelectionSorter<Solution_, Object> determineSorter(GenuineVariableDescriptor<Solution_> variableDescriptor,
+            SelectionOrder resolvedSelectionOrder, ClassInstanceCache instanceCache) {
+        SelectionSorter<Solution_, Object> sorter = null;
+        if (resolvedSelectionOrder == ai.timefold.solver.core.config.heuristic.selector.common.SelectionOrder.SORTED) {
+            var sorterManner = config.getSorterManner();
+            var comparatorClass = determineComparatorClass(config);
+            var comparatorFactoryClass = determineComparatorFactoryClass(config);
+            if (sorterManner != null) {
+                if (!ValueSelectorConfig.hasSorter(sorterManner, variableDescriptor)) {
+                    return null;
+                }
+                sorter = ValueSelectorConfig.determineSorter(sorterManner, variableDescriptor);
+            } else if (comparatorClass != null) {
+                Comparator<Object> sorterComparator =
+                        instanceCache.newInstance(config, determineComparatorPropertyName(config), comparatorClass);
+                sorter = new ComparatorSelectionSorter<>(sorterComparator,
+                        SelectionSorterOrder.resolve(config.getSorterOrder()));
+            } else if (comparatorFactoryClass != null) {
+                var comparatorFactory = instanceCache.newInstance(config, determineComparatorFactoryPropertyName(config),
+                        comparatorFactoryClass);
+                sorter = new ComparatorFactorySelectionSorter<>(comparatorFactory,
+                        SelectionSorterOrder.resolve(config.getSorterOrder()));
+            } else if (config.getSorterClass() != null) {
+                sorter = instanceCache.newInstance(config, "sorterClass", config.getSorterClass());
+            } else {
+                throw new IllegalArgumentException("""
+                        The valueSelectorConfig (%s) with resolvedSelectionOrder (%s) needs \
+                        a sorterManner (%s) or a %s (%s) or a %s (%s) \
+                        or a sorterClass (%s)."""
+                        .formatted(config, resolvedSelectionOrder, sorterManner, determineComparatorPropertyName(config),
+                                comparatorClass, determineComparatorFactoryPropertyName(config), comparatorFactoryClass,
+                                config.getSorterClass()));
+            }
+        }
+        return sorter;
+    }
+
     private ValueSelector<Solution_> buildBaseValueSelector(GenuineVariableDescriptor<Solution_> variableDescriptor,
-            SelectionCacheType minimumCacheType, boolean randomSelection) {
+            SelectionSorter<Solution_, Object> sorter, SelectionCacheType minimumCacheType, boolean randomSelection) {
         var valueRangeDescriptor = variableDescriptor.getValueRangeDescriptor();
         // TODO minimumCacheType SOLVER is only a problem if the valueRange includes entities or custom weird cloning
         if (minimumCacheType == SelectionCacheType.SOLVER) {
@@ -271,11 +319,13 @@ private ValueSelector<Solution_> buildBaseValueSelector(GenuineVariableDescripto
                     + ") is not yet supported. Please use " + SelectionCacheType.PHASE + " instead.");
         }
         if (valueRangeDescriptor.canExtractValueRangeFromSolution()) {
-            return new IterableFromSolutionPropertyValueSelector<>(valueRangeDescriptor, minimumCacheType, randomSelection);
+            return new IterableFromSolutionPropertyValueSelector<>(valueRangeDescriptor, sorter, minimumCacheType,
+                    randomSelection);
         } else {
             // TODO Do not allow PHASE cache on FromEntityPropertyValueSelector, except if the moveSelector is PHASE cached too.
-            var fromEntityPropertySelector = new FromEntityPropertyValueSelector<>(valueRangeDescriptor, randomSelection);
-            return new IterableFromEntityPropertyValueSelector<>(fromEntityPropertySelector, randomSelection);
+            var fromEntityPropertySelector =
+                    new FromEntityPropertyValueSelector<>(valueRangeDescriptor, sorter, randomSelection);
+            return new IterableFromEntityPropertyValueSelector<>(fromEntityPropertySelector, minimumCacheType, randomSelection);
         }
     }
 
@@ -372,37 +422,7 @@ private static void assertNotSorterClassAnd(ValueSelectorConfig config, String p
     protected ValueSelector<Solution_> applySorting(SelectionCacheType resolvedCacheType, SelectionOrder resolvedSelectionOrder,
             ValueSelector<Solution_> valueSelector, ClassInstanceCache instanceCache) {
         if (resolvedSelectionOrder == SelectionOrder.SORTED) {
-            SelectionSorter<Solution_, Object> sorter;
-            var sorterManner = config.getSorterManner();
-            var comparatorClass = determineComparatorClass(config);
-            var comparatorFactoryClass = determineComparatorFactoryClass(config);
-            if (sorterManner != null) {
-                var variableDescriptor = valueSelector.getVariableDescriptor();
-                if (!ValueSelectorConfig.hasSorter(sorterManner, variableDescriptor)) {
-                    return valueSelector;
-                }
-                sorter = ValueSelectorConfig.determineSorter(sorterManner, variableDescriptor);
-            } else if (comparatorClass != null) {
-                Comparator<Object> sorterComparator =
-                        instanceCache.newInstance(config, determineComparatorPropertyName(config), comparatorClass);
-                sorter = new ComparatorSelectionSorter<>(sorterComparator,
-                        SelectionSorterOrder.resolve(config.getSorterOrder()));
-            } else if (comparatorFactoryClass != null) {
-                var comparatorFactory = instanceCache.newInstance(config, determineComparatorFactoryPropertyName(config),
-                        comparatorFactoryClass);
-                sorter = new ComparatorFactorySelectionSorter<>(comparatorFactory,
-                        SelectionSorterOrder.resolve(config.getSorterOrder()));
-            } else if (config.getSorterClass() != null) {
-                sorter = instanceCache.newInstance(config, "sorterClass", config.getSorterClass());
-            } else {
-                throw new IllegalArgumentException("""
-                        The valueSelectorConfig (%s) with resolvedSelectionOrder (%s) needs \
-                        a sorterManner (%s) or a %s (%s) or a %s (%s) \
-                        or a sorterClass (%s)."""
-                        .formatted(config, resolvedSelectionOrder, sorterManner, determineComparatorPropertyName(config),
-                                comparatorClass, determineComparatorFactoryPropertyName(config), comparatorFactoryClass,
-                                config.getSorterClass()));
-            }
+            var sorter = determineSorter(valueSelector.getVariableDescriptor(), resolvedSelectionOrder, instanceCache);
             if (!valueSelector.getVariableDescriptor().canExtractValueRangeFromSolution()
                     && resolvedCacheType == SelectionCacheType.STEP) {
                 valueSelector = new FromEntitySortingValueSelector<>(valueSelector, resolvedCacheType, sorter);