chore: improve Neighborhoods design for scalability

Author: triceo

core/src/main/java/ai/timefold/solver/core/impl/bavet/bi/joiner/BiJoinerComber.java

@@ -14,7 +14,7 @@
  */
 public final class BiJoinerComber<A, B> {
 
-    public static <A, B> BiJoinerComber<A, B> comb(BiJoiner<A, B>[] joiners) {
+    public static <A, B> BiJoinerComber<A, B> comb(BiJoiner<A, B>... joiners) {
         List<DefaultBiJoiner<A, B>> defaultJoinerList = new ArrayList<>(joiners.length);
         List<BiPredicate<A, B>> filteringList = new ArrayList<>(joiners.length);
 

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/ComparisonIndexer.java

@@ -11,6 +11,9 @@
 import ai.timefold.solver.core.impl.bavet.common.joiner.JoinerType;
 import ai.timefold.solver.core.impl.util.ElementAwareListEntry;
 
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
 final class ComparisonIndexer<T, Key_ extends Comparable<Key_>>
         implements Indexer<T> {
 

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/EqualsIndexer.java

@@ -8,6 +8,9 @@
 
 import ai.timefold.solver.core.impl.util.ElementAwareListEntry;
 
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
 final class EqualsIndexer<T, Key_> implements Indexer<T> {
 
     private final KeyRetriever<Key_> keyRetriever;

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/Indexer.java

@@ -5,6 +5,8 @@
 import ai.timefold.solver.core.impl.bavet.common.tuple.TupleState;
 import ai.timefold.solver.core.impl.util.ElementAwareListEntry;
 
+import org.jspecify.annotations.NullMarked;
+
 /**
  * An indexer for entity or fact {@code X},
  * maps a property or a combination of properties of {@code X}, denoted by {@code indexKeys},
@@ -20,6 +22,7 @@
  *        For example for {@code from(A).join(B)}, the tuple is {@code UniTuple<A>} xor {@code UniTuple<B>}.
  *        For example for {@code Bi<A, B>.join(C)}, the tuple is {@code BiTuple<A, B>} xor {@code UniTuple<C>}.
  */
+@NullMarked
 public sealed interface Indexer<T> permits ComparisonIndexer, EqualsIndexer, NoneIndexer {
 
     ElementAwareListEntry<T> put(Object indexKeys, T tuple);

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/NoneIndexer.java

@@ -5,6 +5,9 @@
 import ai.timefold.solver.core.impl.util.ElementAwareList;
 import ai.timefold.solver.core.impl.util.ElementAwareListEntry;
 
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
 public final class NoneIndexer<T> implements Indexer<T> {
 
     private final ElementAwareList<T> tupleList = new ElementAwareList<>();

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/joiner/JoinerType.java

@@ -21,18 +21,14 @@ public enum JoinerType {
     }
 
     public JoinerType flip() {
-        switch (this) {
-            case LESS_THAN:
-                return GREATER_THAN;
-            case LESS_THAN_OR_EQUAL:
-                return GREATER_THAN_OR_EQUAL;
-            case GREATER_THAN:
-                return LESS_THAN;
-            case GREATER_THAN_OR_EQUAL:
-                return LESS_THAN_OR_EQUAL;
-            default:
-                throw new IllegalStateException("The joinerType (" + this + ") cannot be flipped.");
-        }
+        return switch (this) {
+            case LESS_THAN -> GREATER_THAN;
+            case LESS_THAN_OR_EQUAL -> GREATER_THAN_OR_EQUAL;
+            case GREATER_THAN -> LESS_THAN;
+            case GREATER_THAN_OR_EQUAL -> LESS_THAN_OR_EQUAL;
+            default -> throw new IllegalStateException("The joinerType (%s) cannot be flipped."
+                    .formatted(this));
+        };
     }
 
     public boolean matches(Object left, Object right) {

core/src/main/java/ai/timefold/solver/core/impl/domain/variable/descriptor/ListVariableDescriptor.java

@@ -15,7 +15,7 @@
 import ai.timefold.solver.core.impl.domain.variable.ListVariableStateDemand;
 import ai.timefold.solver.core.impl.domain.variable.inverserelation.InverseRelationShadowVariableDescriptor;
 import ai.timefold.solver.core.impl.move.director.MoveDirector;
-import ai.timefold.solver.core.impl.neighborhood.maybeapi.stream.enumerating.function.BiEnumeratingFilter;
+import ai.timefold.solver.core.impl.neighborhood.maybeapi.stream.enumerating.function.BiEnumeratingPredicate;
 
 public final class ListVariableDescriptor<Solution_> extends GenuineVariableDescriptor<Solution_> {
 
@@ -24,7 +24,7 @@ public final class ListVariableDescriptor<Solution_> extends GenuineVariableDesc
         var list = getValue(entity);
         return list.contains(element);
     };
-    private final BiEnumeratingFilter<Solution_, Object, Object> entityContainsPinnedValuePredicate =
+    private final BiEnumeratingPredicate<Solution_, Object, Object> entityContainsPinnedValuePredicate =
             (solutionView, value, entity) -> {
                 var moveDirector = (MoveDirector<Solution_, ?>) solutionView;
                 return moveDirector.isPinned(this, value);
@@ -47,8 +47,8 @@ public <A> BiPredicate<A, Object> getInListPredicate() {
     }
 
     @SuppressWarnings("unchecked")
-    public <A, B> BiEnumeratingFilter<Solution_, A, B> getEntityContainsPinnedValuePredicate() {
-        return (BiEnumeratingFilter<Solution_, A, B>) entityContainsPinnedValuePredicate;
+    public <A, B> BiEnumeratingPredicate<Solution_, A, B> getEntityContainsPinnedValuePredicate() {
+        return (BiEnumeratingPredicate<Solution_, A, B>) entityContainsPinnedValuePredicate;
     }
 
     public boolean allowsUnassignedValues() {

core/src/main/java/ai/timefold/solver/core/impl/neighborhood/maybeapi/MoveStreamFactory.java

@@ -5,14 +5,11 @@
 import ai.timefold.solver.core.api.domain.entity.PlanningPinToIndex;
 import ai.timefold.solver.core.api.domain.solution.ProblemFactCollectionProperty;
 import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
-import ai.timefold.solver.core.impl.neighborhood.maybeapi.stream.enumerating.BiEnumeratingStream;
 import ai.timefold.solver.core.impl.neighborhood.maybeapi.stream.enumerating.EnumeratingStream;
 import ai.timefold.solver.core.impl.neighborhood.maybeapi.stream.enumerating.UniEnumeratingStream;
 import ai.timefold.solver.core.impl.neighborhood.maybeapi.stream.enumerating.function.UniEnumeratingFilter;
-import ai.timefold.solver.core.impl.neighborhood.maybeapi.stream.sampling.BiSamplingStream;
 import ai.timefold.solver.core.impl.neighborhood.maybeapi.stream.sampling.UniSamplingStream;
 import ai.timefold.solver.core.preview.api.domain.metamodel.ElementPosition;
-import ai.timefold.solver.core.preview.api.domain.metamodel.GenuineVariableMetaModel;
 import ai.timefold.solver.core.preview.api.domain.metamodel.PlanningListVariableMetaModel;
 import ai.timefold.solver.core.preview.api.domain.metamodel.PlanningSolutionMetaModel;
 import ai.timefold.solver.core.preview.api.domain.metamodel.UnassignedElement;
@@ -61,18 +58,6 @@ public interface MoveStreamFactory<Solution_> {
      */
     <A> UniEnumeratingStream<Solution_, A> forEachUnfiltered(Class<A> sourceClass, boolean includeNull);
 
-    /**
-     * Enumerate possible values for any given entity,
-     * where entities are obtained using {@link #forEach(Class, boolean)},
-     * with the class matching the entity type of the variable.
-     * If the variable allows unassigned values, the resulting stream will include a null value.
-     *
-     * @param variableMetaModel the meta model of the variable to enumerate
-     * @return enumerating stream with all possible values of a given variable
-     */
-    <Entity_, Value_> BiEnumeratingStream<Solution_, Entity_, Value_>
-            forEachEntityValuePair(GenuineVariableMetaModel<Solution_, Entity_, Value_> variableMetaModel);
-
     /**
      * Enumerate all possible positions of a list variable to which a value can be assigned.
      * This will eliminate all positions on {@link PlanningPin pinned entities},
@@ -89,6 +74,4 @@ public interface MoveStreamFactory<Solution_> {
 
     <A> UniSamplingStream<Solution_, A> pick(UniEnumeratingStream<Solution_, A> enumeratingStream);
 
-    <A, B> BiSamplingStream<Solution_, A, B> pick(BiEnumeratingStream<Solution_, A, B> enumeratingStream);
-
 }

core/src/main/java/ai/timefold/solver/core/impl/neighborhood/maybeapi/move/ChangeMoveDefinition.java

@@ -5,6 +5,8 @@
 import ai.timefold.solver.core.impl.neighborhood.maybeapi.MoveDefinition;
 import ai.timefold.solver.core.impl.neighborhood.maybeapi.MoveStream;
 import ai.timefold.solver.core.impl.neighborhood.maybeapi.MoveStreamFactory;
+import ai.timefold.solver.core.impl.neighborhood.maybeapi.stream.enumerating.EnumeratingJoiners;
+import ai.timefold.solver.core.impl.neighborhood.stream.DefaultMoveStreamFactory;
 import ai.timefold.solver.core.preview.api.domain.metamodel.PlanningVariableMetaModel;
 
 import org.jspecify.annotations.NullMarked;
@@ -21,13 +23,12 @@ public ChangeMoveDefinition(PlanningVariableMetaModel<Solution_, Entity_, Value_
 
     @Override
     public MoveStream<Solution_> build(MoveStreamFactory<Solution_> moveStreamFactory) {
-        var enumeratingStream =
-                moveStreamFactory.forEachEntityValuePair(variableMetaModel)
-                        .filter((solutionView, entity, value) -> {
-                            Value_ currentValue = solutionView.getValue(variableMetaModel, Objects.requireNonNull(entity));
-                            return !Objects.equals(currentValue, value);
-                        });
-        return moveStreamFactory.pick(enumeratingStream)
+        var nodeSharingSupportFunctions =
+                ((DefaultMoveStreamFactory<Solution_>) moveStreamFactory).getNodeSharingSupportFunctions(variableMetaModel);
+        return moveStreamFactory.pick(moveStreamFactory.forEach(variableMetaModel.entity().type(), false))
+                .pick(moveStreamFactory.forEach(variableMetaModel.type(), variableMetaModel.allowsUnassigned()),
+                        EnumeratingJoiners.filtering(nodeSharingSupportFunctions.differentValueFilter()),
+                        EnumeratingJoiners.filtering(nodeSharingSupportFunctions.valueInRangeFilter()))
                 .asMove((solution, entity, value) -> Moves.change(Objects.requireNonNull(entity), value, variableMetaModel));
     }
 

core/src/main/java/ai/timefold/solver/core/impl/neighborhood/maybeapi/move/ListChangeMoveDefinition.java

@@ -46,14 +46,10 @@ public ListChangeMoveDefinition(PlanningListVariableMetaModel<Solution_, Entity_
     @Override
     public MoveStream<Solution_> build(MoveStreamFactory<Solution_> moveStreamFactory) {
         var entityValuePairs = moveStreamFactory.forEachAssignablePosition(variableMetaModel);
-        // The stream of these positions is joined with the stream of all existing values,
-        // filtering out those which would not result in a valid move.
-        var enumeratingStream = moveStreamFactory.forEach(variableMetaModel.type(), false)
-                .join(entityValuePairs, EnumeratingJoiners.filtering(this::isValidChange));
-        // When picking from this stream, we decide what kind of move we need to create,
-        // based on whether the value is assigned or unassigned.
-        return moveStreamFactory.pick(enumeratingStream)
-                .asMove((solutionView, value, targetPosition) -> {
+        var availableValues = moveStreamFactory.forEach(variableMetaModel.type(), false);
+        return moveStreamFactory.pick(entityValuePairs)
+                .pick(availableValues, EnumeratingJoiners.filtering(this::isValidChange))
+                .asMove((solutionView, targetPosition, value) -> {
                     var currentPosition = solutionView.getPositionOf(variableMetaModel, Objects.requireNonNull(value));
                     if (targetPosition instanceof UnassignedElement) {
                         var currentElementPosition = currentPosition.ensureAssigned();
@@ -68,7 +64,7 @@ public MoveStream<Solution_> build(MoveStreamFactory<Solution_> moveStreamFactor
                 });
     }
 
-    private boolean isValidChange(SolutionView<Solution_> solutionView, Value_ value, ElementPosition targetPosition) {
+    private boolean isValidChange(SolutionView<Solution_> solutionView, ElementPosition targetPosition, Value_ value) {
         var currentPosition = solutionView.getPositionOf(variableMetaModel, value);
         if (currentPosition.equals(targetPosition)) { // No change needed.
             return false;