Merge branch 'main' into deep-planning-clone-class

Author: luxaritas

build/build-parent/pom.xml

@@ -20,15 +20,15 @@
     <!-- ************************************************************************ -->
     <!-- Dependencies -->
     <!-- ************************************************************************ -->
-    <version.ch.qos.logback>1.5.12</version.ch.qos.logback>
-    <version.io.quarkus>3.17.3</version.io.quarkus>
+    <version.ch.qos.logback>1.5.16</version.ch.qos.logback>
+    <version.io.quarkus>3.17.5</version.io.quarkus>
     <version.org.apache.commons.math3>3.6.1</version.org.apache.commons.math3>
-    <version.org.apache.logging.log4j>2.24.2</version.org.apache.logging.log4j>
-    <version.org.assertj>3.26.3</version.org.assertj>
-    <version.org.freemarker>2.3.33</version.org.freemarker>
+    <version.org.apache.logging.log4j>2.24.3</version.org.apache.logging.log4j>
+    <version.org.assertj>3.27.2</version.org.assertj>
+    <version.org.freemarker>2.3.34</version.org.freemarker>
     <version.org.jspecify>1.0.0</version.org.jspecify>
-    <version.org.openrewrite.recipe>2.23.1</version.org.openrewrite.recipe>
-    <version.org.springframework.boot>3.4.0</version.org.springframework.boot>
+    <version.org.openrewrite.recipe>2.23.2</version.org.openrewrite.recipe>
+    <version.org.springframework.boot>3.4.1</version.org.springframework.boot>
     <version.ow2.asm>9.7.1</version.ow2.asm>
 
     <!-- ************************************************************************ -->

core/src/main/java/ai/timefold/solver/core/api/function/QuadConsumer.java

@@ -0,0 +1,45 @@
+package ai.timefold.solver.core.api.function;
+
+import java.util.Objects;
+import java.util.function.Consumer;
+import java.util.function.Function;
+
+import org.jspecify.annotations.NonNull;
+
+/**
+ * Represents a function that accepts four arguments and returns no result.
+ * This is the three-arity specialization of {@link Consumer}.
+ *
+ * <p>
+ * This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #accept(Object, Object, Object, Object)}.
+ *
+ * @param <A> the type of the first argument to the function
+ * @param <B> the type of the second argument to the function
+ * @param <C> the type of the third argument to the function
+ * @param <D> the type of the fourth argument to the function
+ *
+ * @see Function
+ */
+@FunctionalInterface
+public interface QuadConsumer<A, B, C, D> {
+
+    /**
+     * Performs this operation on the given arguments.
+     *
+     * @param a the first function argument
+     * @param b the second function argument
+     * @param c the third function argument
+     * @param d the fourth function argument
+     */
+    void accept(A a, B b, C c, D d);
+
+    default @NonNull QuadConsumer<A, B, C, D> andThen(@NonNull QuadConsumer<? super A, ? super B, ? super C, ? super D> after) {
+        Objects.requireNonNull(after);
+        return (a, b, c, d) -> {
+            accept(a, b, c, d);
+            after.accept(a, b, c, d);
+        };
+    }
+
+}

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

@@ -2,7 +2,6 @@
 
 import java.util.List;
 import java.util.Map;
-import java.util.Objects;
 
 import ai.timefold.solver.core.impl.domain.variable.descriptor.ListVariableDescriptor;
 import ai.timefold.solver.core.impl.domain.variable.index.IndexShadowVariableDescriptor;
@@ -26,7 +25,7 @@ final class ListVariableState<Solution_> {
     private boolean requiresLocationMap = true;
     private InnerScoreDirector<Solution_, ?> scoreDirector;
     private int unassignedCount = 0;
-    private Map<Object, LocationInList> elementLocationMap;
+    private Map<Object, MutableLocationInList> elementLocationMap;
 
     public ListVariableState(ListVariableDescriptor<Solution_> sourceVariableDescriptor) {
         this.sourceVariableDescriptor = sourceVariableDescriptor;
@@ -69,8 +68,7 @@ public void initialize(InnerScoreDirector<Solution_, ?> scoreDirector, int initi
 
     public void addElement(Object entity, List<Object> elements, Object element, int index) {
         if (requiresLocationMap) {
-            var location = ElementLocation.of(entity, index);
-            var oldLocation = elementLocationMap.put(element, location);
+            var oldLocation = elementLocationMap.put(element, new MutableLocationInList(entity, index));
             if (oldLocation != null) {
                 throw new IllegalStateException(
                         "The supply for list variable (%s) is corrupted, because the element (%s) at index (%d) already exists (%s)."
@@ -100,7 +98,7 @@ public void removeElement(Object entity, Object element, int index) {
                         "The supply for list variable (%s) is corrupted, because the element (%s) at index (%d) was already unassigned (%s)."
                                 .formatted(sourceVariableDescriptor, element, index, oldElementLocation));
             }
-            var oldIndex = oldElementLocation.index();
+            var oldIndex = oldElementLocation.getIndex();
             if (oldIndex != index) {
                 throw new IllegalStateException(
                         "The supply for list variable (%s) is corrupted, because the element (%s) at index (%d) had an old index (%d) which is not the current index (%d)."
@@ -168,13 +166,22 @@ public boolean changeElement(Object entity, List<Object> elements, int index) {
 
     private ChangeType processElementLocation(Object entity, Object element, int index) {
         if (requiresLocationMap) { // Update the location and figure out if it is different from previous.
-            var newLocation = ElementLocation.of(entity, index);
-            var oldLocation = elementLocationMap.put(element, newLocation);
+            var oldLocation = elementLocationMap.get(element);
             if (oldLocation == null) {
+                elementLocationMap.put(element, new MutableLocationInList(entity, index));
                 unassignedCount--;
                 return ChangeType.BOTH;
             }
-            return compareLocations(entity, oldLocation.entity(), index, oldLocation.index());
+            var changeType = compareLocations(entity, oldLocation.getEntity(), index, oldLocation.getIndex());
+            if (changeType.anythingChanged) { // Replace the map value in-place, to avoid a put() on the hot path.
+                if (changeType.entityChanged) {
+                    oldLocation.setEntity(entity);
+                }
+                if (changeType.indexChanged) {
+                    oldLocation.setIndex(index);
+                }
+            }
+            return changeType;
         } else { // Read the location and figure out if it is different from previous.
             var oldEntity = getInverseSingleton(element);
             if (oldEntity == null) {
@@ -199,27 +206,13 @@ private static ChangeType compareLocations(Object entity, Object otherEntity, in
         }
     }
 
-    private enum ChangeType {
-
-        BOTH(true, true),
-        INDEX(false, true),
-        NEITHER(false, false);
-
-        final boolean anythingChanged;
-        final boolean entityChanged;
-        final boolean indexChanged;
-
-        ChangeType(boolean entityChanged, boolean indexChanged) {
-            this.anythingChanged = entityChanged || indexChanged;
-            this.entityChanged = entityChanged;
-            this.indexChanged = indexChanged;
-        }
-
-    }
-
     public ElementLocation getLocationInList(Object planningValue) {
         if (requiresLocationMap) {
-            return Objects.requireNonNullElse(elementLocationMap.get(planningValue), ElementLocation.unassigned());
+            var mutableLocationInList = elementLocationMap.get(planningValue);
+            if (mutableLocationInList == null) {
+                return ElementLocation.unassigned();
+            }
+            return mutableLocationInList.getLocationInList();
         } else { // At this point, both inverse and index are externalized.
             var inverse = externalizedInverseProcessor.getInverseSingleton(planningValue);
             if (inverse == null) {
@@ -235,7 +228,7 @@ public Integer getIndex(Object planningValue) {
             if (elementLocation == null) {
                 return null;
             }
-            return elementLocation.index();
+            return elementLocation.getIndex();
         }
         return externalizedIndexProcessor.getIndex(planningValue);
     }
@@ -246,34 +239,35 @@ public Object getInverseSingleton(Object planningValue) {
             if (elementLocation == null) {
                 return null;
             }
-            return elementLocation.entity();
+            return elementLocation.getEntity();
         }
         return externalizedInverseProcessor.getInverseSingleton(planningValue);
     }
 
     public Object getPreviousElement(Object element) {
         if (externalizedPreviousElementProcessor == null) {
-            var elementLocation = getLocationInList(element);
-            if (!(elementLocation instanceof LocationInList locationInList)) {
+            var mutableLocationInList = elementLocationMap.get(element);
+            if (mutableLocationInList == null) {
                 return null;
             }
-            var index = locationInList.index();
+            var index = mutableLocationInList.getIndex();
             if (index == 0) {
                 return null;
             }
-            return sourceVariableDescriptor.getValue(locationInList.entity()).get(index - 1);
+            return sourceVariableDescriptor.getValue(mutableLocationInList.getEntity())
+                    .get(index - 1);
         }
         return externalizedPreviousElementProcessor.getElement(element);
     }
 
     public Object getNextElement(Object element) {
         if (externalizedNextElementProcessor == null) {
-            var elementLocation = getLocationInList(element);
-            if (!(elementLocation instanceof LocationInList locationInList)) {
+            var mutableLocationInList = elementLocationMap.get(element);
+            if (mutableLocationInList == null) {
                 return null;
             }
-            var list = sourceVariableDescriptor.getValue(locationInList.entity());
-            var index = locationInList.index();
+            var list = sourceVariableDescriptor.getValue(mutableLocationInList.getEntity());
+            var index = mutableLocationInList.getIndex();
             if (index == list.size() - 1) {
                 return null;
             }
@@ -286,4 +280,66 @@ public int getUnassignedCount() {
         return unassignedCount;
     }
 
+    private enum ChangeType {
+
+        BOTH(true, true),
+        INDEX(false, true),
+        NEITHER(false, false);
+
+        final boolean anythingChanged;
+        final boolean entityChanged;
+        final boolean indexChanged;
+
+        ChangeType(boolean entityChanged, boolean indexChanged) {
+            this.anythingChanged = entityChanged || indexChanged;
+            this.entityChanged = entityChanged;
+            this.indexChanged = indexChanged;
+        }
+
+    }
+
+    /**
+     * This class is used to avoid creating a new {@link LocationInList} object every time we need to return a location.
+     * The actual value is held in a map and can be updated without doing a put() operation, which is more efficient.
+     * The {@link LocationInList} object is only created when it is actually requested,
+     * and stored until the next time the mutable state is updated and therefore the cache invalidated.
+     */
+    private static final class MutableLocationInList {
+
+        private Object entity;
+        private int index;
+        private LocationInList locationInList;
+
+        public MutableLocationInList(Object entity, int index) {
+            this.entity = entity;
+            this.index = index;
+        }
+
+        public Object getEntity() {
+            return entity;
+        }
+
+        public void setEntity(Object entity) {
+            this.entity = entity;
+            this.locationInList = null;
+        }
+
+        public int getIndex() {
+            return index;
+        }
+
+        public void setIndex(int index) {
+            this.index = index;
+            this.locationInList = null;
+        }
+
+        public LocationInList getLocationInList() {
+            if (locationInList == null) {
+                locationInList = ElementLocation.of(entity, index);
+            }
+            return locationInList;
+        }
+
+    }
+
 }

core/src/main/java/ai/timefold/solver/core/impl/score/director/stream/BavetConstraintStreamScoreDirectorFactory.java

@@ -1,6 +1,7 @@
 package ai.timefold.solver.core.impl.score.director.stream;
 
 import java.util.Arrays;
+import java.util.function.Consumer;
 
 import ai.timefold.solver.core.api.score.Score;
 import ai.timefold.solver.core.api.score.stream.ConstraintMetaModel;
@@ -56,8 +57,7 @@ public BavetConstraintStreamScoreDirectorFactory(SolutionDescriptor<Solution_> s
             ConstraintProvider constraintProvider, EnvironmentMode environmentMode) {
         super(solutionDescriptor);
         var constraintFactory = new BavetConstraintFactory<>(solutionDescriptor, environmentMode);
-        constraintMetaModel =
-                DefaultConstraintMetaModel.of(constraintFactory.buildConstraints(constraintProvider));
+        constraintMetaModel = DefaultConstraintMetaModel.of(constraintFactory.buildConstraints(constraintProvider));
         constraintSessionFactory = new BavetConstraintSessionFactory<>(solutionDescriptor, constraintMetaModel);
     }
 
@@ -76,7 +76,13 @@ public InnerScoreDirector<Solution_, Score_> buildDerivedScoreDirector(boolean l
 
     public BavetConstraintSession<Score_> newSession(Solution_ workingSolution, ConstraintMatchPolicy constraintMatchPolicy,
             boolean scoreDirectorDerived) {
-        return constraintSessionFactory.buildSession(workingSolution, constraintMatchPolicy, scoreDirectorDerived);
+        return newSession(workingSolution, constraintMatchPolicy, scoreDirectorDerived, null);
+    }
+
+    public BavetConstraintSession<Score_> newSession(Solution_ workingSolution, ConstraintMatchPolicy constraintMatchPolicy,
+            boolean scoreDirectorDerived, Consumer<String> nodeNetworkVisualizationConsumer) {
+        return constraintSessionFactory.buildSession(workingSolution, constraintMatchPolicy, scoreDirectorDerived,
+                nodeNetworkVisualizationConsumer);
     }
 
     @Override

core/src/main/java/ai/timefold/solver/core/impl/score/stream/bavet/BavetConstraint.java

@@ -23,9 +23,9 @@ public BavetConstraint(BavetConstraintFactory<Solution_> constraintFactory, Cons
         this.scoringConstraintStream = scoringConstraintStream;
     }
 
-    // ************************************************************************
-    // Node creation
-    // ************************************************************************
+    public BavetScoringConstraintStream<Solution_> getScoringConstraintStream() {
+        return scoringConstraintStream;
+    }
 
     @Override
     public String toString() {