chore: prepare for list var value range on entity

This pull request introduces the ability to define value ranges for list variables in the entities. The proposed approach in the CH phase involves creating a new descriptor and selector that can read all values from the entities, serving as a single source of truth. This unique list of elements is required for the queued value placer to function correctly. Additionally, a new cache tier for value range elements is implemented to enable faster access to value ranges values.

For the LS phase, the changes follow the same strategy used for basic variables, generating valid and invalid moves through the respective move generators. However, the logic for list moves in isMoveDoable has been updated to ensure that moves are valid when using entity value ranges. This approach makes the logic simpler and more performant in some cases, as generating only valid moves would require more complex changes than just ensuring it is doable.

The list var-related code is hidden behind fail fasts. It may still be refactored before getting enabled, pending performance regression tests under various conditions.

Author: zepfred

core/src/main/java/ai/timefold/solver/core/config/heuristic/selector/move/NearbyUtil.java

@@ -162,7 +162,7 @@ private static ValueSelectorConfig configureSecondaryValueSelector(ValueSelector
                 .withValueSelectorConfig(valueConfig);
     }
 
-    private static String addRandomSuffix(String name, Random random) {
+    public static String addRandomSuffix(String name, Random random) {
         var value = new StringBuilder(name);
         value.append("-");
         random.ints(97, 122) // ['a', 'z']

core/src/main/java/ai/timefold/solver/core/config/util/ConfigUtils.java

@@ -1,6 +1,7 @@
 package ai.timefold.solver.core.config.util;
 
 import static ai.timefold.solver.core.impl.domain.common.accessor.MemberAccessorFactory.MemberAccessorType.FIELD_OR_READ_METHOD;
+import static ai.timefold.solver.core.impl.domain.solution.cloner.DeepCloningUtils.IMMUTABLE_CLASSES;
 
 import java.lang.annotation.Annotation;
 import java.lang.reflect.AnnotatedElement;
@@ -449,6 +450,17 @@ Maybe the member (%s) should return a parameterized %s."""
                                 memberName, type, memberName, type.getSimpleName())));
     }
 
+    /**
+     * @param type the class type
+     * @return true if it is immutable; otherwise false
+     */
+    public static boolean isGenericTypeImmutable(Class<?> type) {
+        if (type == null) {
+            return false;
+        }
+        return type.isRecord() || IMMUTABLE_CLASSES.contains(type);
+    }
+
     public static Optional<Class<?>> extractGenericTypeParameter(@NonNull String parentClassConcept,
             @NonNull Class<?> parentClass, @NonNull Class<?> type, @NonNull Type genericType,
             @Nullable Class<? extends Annotation> annotationClass, @NonNull String memberName) {

core/src/main/java/ai/timefold/solver/core/impl/constructionheuristic/DefaultConstructionHeuristicPhase.java

@@ -64,7 +64,8 @@ public void solve(SolverScope<Solution_> solverScope) {
             // (When it exhausts all values, it will start over from the beginning.)
             // To prevent that, we need to limit the number of steps to the number of unassigned values.
             var workingSolution = phaseScope.getWorkingSolution();
-            maxStepCount = solutionDescriptor.getListVariableDescriptor().countUnassigned(workingSolution);
+            maxStepCount = solutionDescriptor.getListVariableDescriptor().countUnassigned(workingSolution,
+                    solverScope.getValueRangeManager());
         }
 
         TerminationStatus earlyTerminationStatus = null;

core/src/main/java/ai/timefold/solver/core/impl/constructionheuristic/placer/AbstractEntityPlacerFactory.java

@@ -28,7 +28,7 @@ protected ChangeMoveSelectorConfig buildChangeMoveSelectorConfig(HeuristicConfig
                 .withVariableName(variableDescriptor.getVariableName());
         if (ValueSelectorConfig.hasSorter(configPolicy.getValueSorterManner(), variableDescriptor)) {
             changeValueSelectorConfig = changeValueSelectorConfig
-                    .withCacheType(variableDescriptor.isValueRangeEntityIndependent() ? PHASE : STEP)
+                    .withCacheType(variableDescriptor.canExtractValueRangeFromSolution() ? PHASE : STEP)
                     .withSelectionOrder(SelectionOrder.SORTED)
                     .withSorterManner(configPolicy.getValueSorterManner());
         }

core/src/main/java/ai/timefold/solver/core/impl/constructionheuristic/placer/QueuedValuePlacer.java

@@ -9,17 +9,17 @@
 import ai.timefold.solver.core.impl.heuristic.selector.move.MoveSelector;
 import ai.timefold.solver.core.impl.heuristic.selector.move.factory.MoveIteratorFactory;
 import ai.timefold.solver.core.impl.heuristic.selector.move.generic.list.ListChangeMoveSelector;
-import ai.timefold.solver.core.impl.heuristic.selector.value.EntityIndependentValueSelector;
-import ai.timefold.solver.core.impl.heuristic.selector.value.decorator.EntityIndependentFilteringValueSelector;
+import ai.timefold.solver.core.impl.heuristic.selector.value.IterableValueSelector;
 import ai.timefold.solver.core.impl.heuristic.selector.value.decorator.FilteringValueSelector;
+import ai.timefold.solver.core.impl.heuristic.selector.value.decorator.IterableFilteringValueSelector;
 
 public class QueuedValuePlacer<Solution_> extends AbstractEntityPlacer<Solution_> implements EntityPlacer<Solution_> {
 
-    protected final EntityIndependentValueSelector<Solution_> valueSelector;
+    protected final IterableValueSelector<Solution_> valueSelector;
     protected final MoveSelector<Solution_> moveSelector;
 
     public QueuedValuePlacer(EntityPlacerFactory<Solution_> factory, HeuristicConfigPolicy<Solution_> configPolicy,
-            EntityIndependentValueSelector<Solution_> valueSelector, MoveSelector<Solution_> moveSelector) {
+            IterableValueSelector<Solution_> valueSelector, MoveSelector<Solution_> moveSelector) {
         super(factory, configPolicy);
         this.valueSelector = valueSelector;
         this.moveSelector = moveSelector;
@@ -67,7 +67,7 @@ protected Placement<Solution_> createUpcomingSelection() {
     @Override
     public EntityPlacer<Solution_> rebuildWithFilter(SelectionFilter<Solution_, Object> filter) {
         return new QueuedValuePlacer<>(factory, configPolicy,
-                (EntityIndependentFilteringValueSelector<Solution_>) FilteringValueSelector.of(valueSelector, filter),
+                (IterableFilteringValueSelector<Solution_>) FilteringValueSelector.of(valueSelector, filter),
                 moveSelector);
     }
 

core/src/main/java/ai/timefold/solver/core/impl/constructionheuristic/placer/QueuedValuePlacerFactory.java

@@ -15,16 +15,17 @@
 import ai.timefold.solver.core.impl.heuristic.HeuristicConfigPolicy;
 import ai.timefold.solver.core.impl.heuristic.selector.move.MoveSelector;
 import ai.timefold.solver.core.impl.heuristic.selector.move.MoveSelectorFactory;
-import ai.timefold.solver.core.impl.heuristic.selector.value.EntityIndependentValueSelector;
+import ai.timefold.solver.core.impl.heuristic.selector.value.IterableValueSelector;
 import ai.timefold.solver.core.impl.heuristic.selector.value.ValueSelector;
 import ai.timefold.solver.core.impl.heuristic.selector.value.ValueSelectorFactory;
 
 public class QueuedValuePlacerFactory<Solution_>
         extends AbstractEntityPlacerFactory<Solution_, QueuedValuePlacerConfig> {
 
     public static QueuedValuePlacerConfig unfoldNew(MoveSelectorConfig templateMoveSelectorConfig) {
-        throw new UnsupportedOperationException("The <constructionHeuristic> contains a moveSelector ("
-                + templateMoveSelectorConfig + ") and the <queuedValuePlacer> does not support unfolding those yet.");
+        throw new UnsupportedOperationException(
+                "The <constructionHeuristic> contains a moveSelector (%s) and the <queuedValuePlacer> does not support unfolding those yet."
+                        .formatted(templateMoveSelectorConfig));
     }
 
     public QueuedValuePlacerFactory(QueuedValuePlacerConfig placerConfig) {
@@ -48,15 +49,14 @@ public QueuedValuePlacer<Solution_> buildEntityPlacer(HeuristicConfigPolicy<Solu
 
         MoveSelector<Solution_> moveSelector = MoveSelectorFactory.<Solution_> create(moveSelectorConfig_)
                 .buildMoveSelector(configPolicy, SelectionCacheType.JUST_IN_TIME, SelectionOrder.ORIGINAL, false);
-        if (!(valueSelector instanceof EntityIndependentValueSelector)) {
-            throw new IllegalArgumentException("The queuedValuePlacer (" + this
-                    + ") needs to be based on an "
-                    + EntityIndependentValueSelector.class.getSimpleName() + " (" + valueSelector + ")."
-                    + " Check your @" + ValueRangeProvider.class.getSimpleName() + " annotations.");
+        if (!(valueSelector instanceof IterableValueSelector<Solution_> iterableValueSelector)) {
+            throw new IllegalArgumentException(
+                    "The queuedValuePlacer (%s) needs to be based on an %s (%s). Check your @%s annotations.".formatted(this,
+                            IterableValueSelector.class.getSimpleName(), valueSelector,
+                            ValueRangeProvider.class.getSimpleName()));
 
         }
-        return new QueuedValuePlacer<>(this, configPolicy, (EntityIndependentValueSelector<Solution_>) valueSelector,
-                moveSelector);
+        return new QueuedValuePlacer<>(this, configPolicy, iterableValueSelector, moveSelector);
     }
 
     private ValueSelectorConfig buildValueSelectorConfig(HeuristicConfigPolicy<Solution_> configPolicy,

core/src/main/java/ai/timefold/solver/core/impl/domain/entity/descriptor/EntityDescriptor.java

@@ -27,8 +27,6 @@
 import ai.timefold.solver.core.api.domain.entity.PlanningPin;
 import ai.timefold.solver.core.api.domain.entity.PlanningPinToIndex;
 import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
-import ai.timefold.solver.core.api.domain.valuerange.CountableValueRange;
-import ai.timefold.solver.core.api.domain.valuerange.ValueRange;
 import ai.timefold.solver.core.api.domain.valuerange.ValueRangeProvider;
 import ai.timefold.solver.core.api.domain.variable.AnchorShadowVariable;
 import ai.timefold.solver.core.api.domain.variable.CascadingUpdateShadowVariable;
@@ -67,6 +65,7 @@
 import ai.timefold.solver.core.impl.heuristic.selector.common.decorator.ComparatorSelectionSorter;
 import ai.timefold.solver.core.impl.heuristic.selector.common.decorator.SelectionSorter;
 import ai.timefold.solver.core.impl.heuristic.selector.common.decorator.WeightFactorySelectionSorter;
+import ai.timefold.solver.core.impl.score.director.ValueRangeManager;
 import ai.timefold.solver.core.impl.util.CollectionUtils;
 import ai.timefold.solver.core.impl.util.MutableInt;
 import ai.timefold.solver.core.preview.api.domain.metamodel.PlanningEntityMetaModel;
@@ -859,18 +858,31 @@ public PlanningPinToIndexReader getEffectivePlanningPinToIndexReader() {
         return effectivePlanningPinToIndexReader;
     }
 
-    public long getMaximumValueCount(Solution_ solution, Object entity) {
+    public long getMaximumValueCount(Solution_ solution, Object entity, ValueRangeManager<Solution_> valueRangeManager) {
         var maximumValueCount = 0L;
         for (var variableDescriptor : effectiveGenuineVariableDescriptorList) {
-            maximumValueCount = Math.max(maximumValueCount, variableDescriptor.getValueRangeSize(solution, entity));
+            if (variableDescriptor.canExtractValueRangeFromSolution()) {
+                maximumValueCount = Math.max(maximumValueCount,
+                        valueRangeManager.countOnSolution(variableDescriptor.getValueRangeDescriptor(),
+                                solution));
+            } else {
+                maximumValueCount = Math.max(maximumValueCount,
+                        valueRangeManager.countOnEntity(variableDescriptor.getValueRangeDescriptor(),
+                                entity));
+
+            }
         }
         return maximumValueCount;
 
     }
 
-    public void processProblemScale(Solution_ solution, Object entity, ProblemScaleTracker tracker) {
+    public void processProblemScale(Solution_ solution, Object entity, ProblemScaleTracker tracker,
+            ValueRangeManager<Solution_> valueRangeManager) {
         for (var variableDescriptor : effectiveGenuineVariableDescriptorList) {
-            var valueCount = variableDescriptor.getValueRangeSize(solution, entity);
+            var valueCount = variableDescriptor.canExtractValueRangeFromSolution()
+                    ? valueRangeManager.countOnSolution(variableDescriptor.getValueRangeDescriptor(),
+                            solution)
+                    : valueRangeManager.countOnEntity(variableDescriptor.getValueRangeDescriptor(), entity);
             // TODO: When minimum Java supported is 21, this can be replaced with a sealed interface switch
             if (variableDescriptor instanceof BasicVariableDescriptor<Solution_> basicVariableDescriptor) {
                 if (basicVariableDescriptor.isChained()) {
@@ -880,34 +892,34 @@ public void processProblemScale(Solution_ solution, Object entity, ProblemScaleT
                         tracker.addPinnedListValueCount(1);
                     }
                     // Anchors are entities
-                    var valueRange = variableDescriptor.getValueRangeDescriptor().extractValueRange(solution, entity);
-                    if (valueRange instanceof CountableValueRange<?> countableValueRange) {
-                        var valueIterator = countableValueRange.createOriginalIterator();
-                        while (valueIterator.hasNext()) {
-                            var value = valueIterator.next();
-                            if (variableDescriptor.isValuePotentialAnchor(value)) {
-                                if (tracker.isAnchorVisited(value)) {
-                                    continue;
-                                }
-                                // Assumes anchors are not pinned
-                                tracker.incrementListEntityCount(true);
+                    var valueRange = variableDescriptor.canExtractValueRangeFromSolution()
+                            ? valueRangeManager.getFromSolution(variableDescriptor.getValueRangeDescriptor(),
+                                    solution)
+                            : valueRangeManager.getFromEntity(variableDescriptor.getValueRangeDescriptor(),
+                                    entity);
+                    var valueIterator = valueRange.createOriginalIterator();
+                    while (valueIterator.hasNext()) {
+                        var value = valueIterator.next();
+                        if (variableDescriptor.isValuePotentialAnchor(value)) {
+                            if (tracker.isAnchorVisited(value)) {
+                                continue;
                             }
+                            // Assumes anchors are not pinned
+                            tracker.incrementListEntityCount(true);
                         }
-                    } else {
-                        throw new IllegalStateException("""
-                                The value range (%s) for variable (%s) is not countable.
-                                Verify that a @%s does not return a %s when it can return %s or %s.
-                                """.formatted(valueRange, variableDescriptor.getSimpleEntityAndVariableName(),
-                                ValueRangeProvider.class.getSimpleName(), ValueRange.class.getSimpleName(),
-                                CountableValueRange.class.getSimpleName(), Collection.class.getSimpleName()));
                     }
                 } else {
                     if (isMovable(solution, entity)) {
                         tracker.addBasicProblemScale(valueCount);
                     }
                 }
             } else if (variableDescriptor instanceof ListVariableDescriptor<Solution_> listVariableDescriptor) {
-                tracker.setListTotalValueCount((int) listVariableDescriptor.getValueRangeSize(solution, entity));
+                var size = variableDescriptor.canExtractValueRangeFromSolution()
+                        ? valueRangeManager.countOnSolution(listVariableDescriptor.getValueRangeDescriptor(),
+                                solution)
+                        : valueRangeManager.countOnEntity(listVariableDescriptor.getValueRangeDescriptor(),
+                                entity);
+                tracker.setListTotalValueCount((int) size);
                 if (isMovable(solution, entity)) {
                     tracker.incrementListEntityCount(true);
                     tracker.addPinnedListValueCount(listVariableDescriptor.getFirstUnpinnedIndex(entity));

core/src/main/java/ai/timefold/solver/core/impl/domain/solution/cloner/DeepCloningUtils.java

@@ -39,7 +39,7 @@
 public final class DeepCloningUtils {
 
     // Instances of these JDK classes will never be deep-cloned.
-    private static final Set<Class<?>> IMMUTABLE_CLASSES = Set.of(
+    public static final Set<Class<?>> IMMUTABLE_CLASSES = Set.of(
             // Numbers
             Byte.class, Short.class, Integer.class, Long.class, Float.class, Double.class, BigInteger.class, BigDecimal.class,
             // Optional