perf: add ability to ignore inconsistent solutions (#2396)

Author: Christopher-Chianelli

core/src/main/java/ai/timefold/solver/core/enterprise/TimefoldSolverEnterpriseService.java

@@ -178,7 +178,7 @@ static <T> T loadOrDefault(Function<TimefoldSolverEnterpriseService, T> builder,
         }
     }
 
-    TopologicalOrderGraph buildTopologyGraph(int size);
+    TopologicalOrderGraph buildTopologyGraph(int size, boolean ignoreInconsistentSolutions);
 
     /**
      * Will create new classes that apply node-sharing to the given {@link ConstraintProvider}.

core/src/main/java/ai/timefold/solver/core/impl/domain/solution/descriptor/SolutionDescriptor.java

@@ -57,6 +57,7 @@
 import ai.timefold.solver.core.impl.domain.solution.cloner.gizmo.GizmoSolutionCloner;
 import ai.timefold.solver.core.impl.domain.solution.cloner.gizmo.GizmoSolutionClonerFactory;
 import ai.timefold.solver.core.impl.domain.variable.declarative.DeclarativeShadowVariableDescriptor;
+import ai.timefold.solver.core.impl.domain.variable.declarative.ShadowVariablesInconsistentVariableDescriptor;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.BasicVariableDescriptor;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.GenuineVariableDescriptor;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.ListVariableDescriptor;
@@ -986,6 +987,13 @@ public List<DeclarativeShadowVariableDescriptor<Solution_>> getDeclarativeShadow
         return declarativeShadowVariableDescriptorList;
     }
 
+    public boolean hasAnyShadowVariablesInconsistentMember() {
+        return entityDescriptorMap.values().stream()
+                .flatMap(entityDescriptor -> entityDescriptor.getShadowVariableDescriptors().stream())
+                .anyMatch(
+                        shadowVariableDescriptor -> shadowVariableDescriptor instanceof ShadowVariablesInconsistentVariableDescriptor<Solution_>);
+    }
+
     public Stream<Object> extractAllEntitiesStream(Solution_ solution) {
         var stream = Stream.empty();
         for (var memberAccessor : entityMemberAccessorMap.values()) {
@@ -1051,5 +1059,4 @@ public <Score_ extends Score<Score_>> void setScore(Solution_ solution, Score_ s
     public String toString() {
         return "%s(%s)".formatted(getClass().getSimpleName(), solutionClass.getName());
     }
-
 }

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

@@ -71,6 +71,7 @@ public static <Solution_> ShadowVariableSupport<Solution_> create(InnerScoreDire
     private final List<ListVariableChangeHandler<Solution_>> listVariableChangeHandlerList;
 
     private boolean dirty = false;
+    private boolean updateSuccessful = true;
     @Nullable
     private DefaultShadowVariableSession<Solution_> shadowVariableSession = null;
     private ConsistencyTracker<Solution_> consistencyTracker = new ConsistencyTracker<>();
@@ -392,12 +393,12 @@ public void afterListVariableChanged(ListVariableDescriptor<Solution_> variableD
         return scoreDirector;
     }
 
-    public void updateShadowVariables() {
+    public boolean updateShadowVariables() {
         if (!dirty) {
             // Shortcut in case the trigger is called multiple times in a row,
             // without any notifications inbetween.
             // This is better than trying to ensure that the situation never ever occurs.
-            return;
+            return updateSuccessful;
         }
         if (listVariableDescriptor != null) {
             // If there is no cascade, skip the whole thing.
@@ -409,7 +410,11 @@ public void updateShadowVariables() {
             listVariableChangeList.clear();
         }
         if (shadowVariableSession != null) {
-            shadowVariableSession.updateVariables();
+            if (!shadowVariableSession.updateVariables()) {
+                updateSuccessful = false;
+                notificationQueuesAreEmpty = true;
+                return false;
+            }
         }
         dirty = false;
     }
@@ -490,9 +495,9 @@ private void cascadeUnassignedValues(
      *
      * @param workingSolution working solution
      */
-    public void forceUpdateAllShadowVariables(Solution_ workingSolution) {
+    public boolean forceUpdateAllShadowVariables(Solution_ workingSolution) {
         scoreDirector.getSolutionDescriptor().visitAllEntities(workingSolution, this::simulateGenuineVariableChange);
-        updateShadowVariables();
+        return updateShadowVariables();
     }
 
     /**

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

@@ -73,7 +73,7 @@ public void updateShadowVariables(Class<Solution_> solutionClass, Object... enti
                 SolutionDescriptor.buildSolutionDescriptor(Objects.requireNonNull(solutionClass),
                         entityClassList.toArray(new Class<?>[0]));
         // No solution, we trigger all supported events manually
-        var session = InternalShadowVariableSession.build(solutionDescriptor, entities);
+        var session = InternalShadowVariableSession.build(solutionDescriptor, false, entities);
         // Update all built-in shadow variables
         var listVariableDescriptor = solutionDescriptor.getListVariableDescriptor();
         if (listVariableDescriptor == null) {
@@ -90,12 +90,14 @@ private record InternalShadowVariableSession<Solution_>(SolutionDescriptor<Solut
 
         public static <Solution_> InternalShadowVariableSession<Solution_> build(
                 SolutionDescriptor<Solution_> solutionDescriptor,
+                boolean ignoreInconsistentSolutions,
                 Object... entities) {
             return new InternalShadowVariableSession<>(solutionDescriptor,
                     DefaultShadowVariableSessionFactory.buildGraph(
                             new DefaultShadowVariableSessionFactory.GraphDescriptor<>(solutionDescriptor,
                                     ChangedVariableNotifier.empty(), entities)
-                                    .assertingNoReferencedMissingEntities()));
+                                    .assertingNoReferencedMissingEntities(),
+                            ignoreInconsistentSolutions));
         }
 
         /**
@@ -298,7 +300,7 @@ public void setWorkingSolutionWithoutUpdatingShadows(Solution_ workingSolution)
         }
 
         @Override
-        public InnerScore<Score_> calculateScore() {
+        public InnerScore<Score_> innerCalculateScore() {
             throw new UnsupportedOperationException();
         }
 

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

@@ -86,7 +86,7 @@ public abstract sealed class AbstractVariableReferenceGraph<Solution_, ChangeTra
      *           and {@link #afterVariableChanged(VariableMetaModel, Object)}
      *           can short circuit.
      */
-    abstract void innerUpdateChanged();
+    abstract boolean innerUpdateChanged();
 
     /**
      * Called when any non-declarative source variable for the
@@ -97,10 +97,11 @@ public abstract sealed class AbstractVariableReferenceGraph<Solution_, ChangeTra
     abstract void markChanged(GraphNode<Solution_> changed);
 
     @Override
-    public final void updateChanged() {
+    public final boolean updateChanged() {
         isUpdating = true;
-        innerUpdateChanged();
+        var success = innerUpdateChanged();
         isUpdating = false;
+        return success;
     }
 
     private BaseTopologicalOrderGraph.NodeTopologicalOrder[] buildNodeTopologicalOrderArray(BaseTopologicalOrderGraph graph,

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

@@ -21,12 +21,15 @@ final class AffectedEntitiesUpdater<Solution_>
     // Internal state; expensive to create, therefore we reuse.
     private final LoopedTracker loopedTracker;
     private final BitSet visited;
+    private final boolean ignoreInconsistentSolutions;
     private final PriorityQueue<BaseTopologicalOrderGraph.NodeTopologicalOrder> changeQueue;
+    private boolean consistencyProcessed;
 
     AffectedEntitiesUpdater(BaseTopologicalOrderGraph graph, List<GraphNode<Solution_>> nodeList,
             BaseTopologicalOrderGraph.NodeTopologicalOrder[] nodeTopologicalOrders,
             Function<Object, List<GraphNode<Solution_>>> entityToContainingNode,
-            int entityCount, ChangedVariableNotifier<Solution_> changedVariableNotifier) {
+            int entityCount, ChangedVariableNotifier<Solution_> changedVariableNotifier,
+            boolean ignoreInconsistentSolutions) {
         this.graph = graph;
         this.nodeList = nodeList;
         this.nodeTopologicalOrders = nodeTopologicalOrders;
@@ -36,6 +39,8 @@ final class AffectedEntitiesUpdater<Solution_>
                 createNodeToEntityNodes(entityCount, nodeList, entityToContainingNode));
         this.visited = new BitSet(instanceCount);
         this.changeQueue = new PriorityQueue<>(instanceCount);
+        this.ignoreInconsistentSolutions = ignoreInconsistentSolutions;
+        this.consistencyProcessed = false;
     }
 
     static <Solution_> int[][] createNodeToEntityNodes(int entityCount,
@@ -98,6 +103,7 @@ public void accept(BitSet changed) {
 
         // Prepare for the next time updateChanged() is called.
         // No need to clear changeQueue, as that already finishes empty.
+        consistencyProcessed = true;
         loopedTracker.clear();
         visited.clear();
     }
@@ -129,19 +135,22 @@ private boolean updateEntityShadowVariables(GraphNode<Solution_> entityVariable,
 
         // Do not need to update anyChanged here; the graph already marked
         // all nodes whose looped status changed for us
-        var groupEntities = shadowVariableReferences.get(0).groupEntities();
-        var groupEntityIds = entityVariable.groupEntityIds();
 
-        if (groupEntities != null) {
-            for (var i = 0; i < groupEntityIds.length; i++) {
-                var groupEntity = groupEntities[i];
-                var groupEntityId = groupEntityIds[i];
+        if (!ignoreInconsistentSolutions || !consistencyProcessed) {
+            var groupEntities = shadowVariableReferences.get(0).groupEntities();
+            var groupEntityIds = entityVariable.groupEntityIds();
+
+            if (groupEntities != null) {
+                for (var i = 0; i < groupEntityIds.length; i++) {
+                    var groupEntity = groupEntities[i];
+                    var groupEntityId = groupEntityIds[i];
+                    anyChanged |=
+                            updateLoopedStatusOfEntity(groupEntity, groupEntityId, entityConsistencyState);
+                }
+            } else {
                 anyChanged |=
-                        updateLoopedStatusOfEntity(groupEntity, groupEntityId, entityConsistencyState);
+                        updateLoopedStatusOfEntity(entity, entityVariable.entityId(), entityConsistencyState);
             }
-        } else {
-            anyChanged |=
-                    updateLoopedStatusOfEntity(entity, entityVariable.entityId(), entityConsistencyState);
         }
 
         for (var shadowVariableReference : shadowVariableReferences) {

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

@@ -23,9 +23,11 @@ private ConsistencyTracker(boolean isFrozen) {
     }
 
     public static <Solution_> ConsistencyTracker<Solution_> frozen(SolutionDescriptor<Solution_> solutionDescriptor,
+            boolean ignoreInconsistentSolutions,
             Object[] entityOrFacts) {
         var out = new ConsistencyTracker<Solution_>(true);
-        out.setUnknownConsistencyFromEntityShadowVariablesInconsistent(solutionDescriptor, entityOrFacts);
+        out.setUnknownConsistencyFromEntityShadowVariablesInconsistent(solutionDescriptor, ignoreInconsistentSolutions,
+                entityOrFacts);
         return out;
     }
 
@@ -46,6 +48,7 @@ public static <Solution_> ConsistencyTracker<Solution_> frozen(SolutionDescripto
      * (regardless of its actual consistency in the graph).
      */
     void setUnknownConsistencyFromEntityShadowVariablesInconsistent(SolutionDescriptor<Solution_> solutionDescriptor,
+            boolean ignoreInconsistentSolutions,
             Object[] entityOrFacts) { // Not private so DefaultVariableReferenceGraph javadoc can reference it.
         var entities = Arrays.stream(entityOrFacts)
                 .filter(maybeEntity -> solutionDescriptor.hasEntityDescriptor(maybeEntity.getClass()))
@@ -60,7 +63,8 @@ void setUnknownConsistencyFromEntityShadowVariablesInconsistent(SolutionDescript
                         new DefaultShadowVariableSessionFactory.GraphDescriptor<>(solutionDescriptor,
                                 ChangedVariableNotifier.empty(), entities)
                                 .withConsistencyTracker(this)
-                                .assertingNoReferencedMissingEntities());
+                                .assertingNoReferencedMissingEntities(),
+                        ignoreInconsistentSolutions);
 
         // Graph will either be DefaultVariableReferenceGraph or EmptyVariableReferenceGraph
         // If it is empty, we don't need to do anything.
@@ -71,7 +75,7 @@ void setUnknownConsistencyFromEntityShadowVariablesInconsistent(SolutionDescript
 
     /**
      * If true, consistency and shadow variables are frozen and should not be updated.
-     * ConstraintVerifier creates a frozen instance via {@link #frozen(SolutionDescriptor, Object[])}.
+     * ConstraintVerifier creates a frozen instance via {@link #frozen(SolutionDescriptor, boolean, Object[])}.
      * 
      * @return true if consistency and shadow variables are frozen and should not be updated
      */

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

@@ -47,7 +47,7 @@ public void afterListVariableChanged(ListVariableDescriptor<Solution_> variableD
                 variableDescriptor.getValue(entity), fromIndex, toIndex);
     }
 
-    public void updateVariables() {
-        graph.updateChanged();
+    public boolean updateVariables() {
+        return graph.updateChanged();
     }
 }