feat: introduce a Ruin And Recreate move (#1010)

Introduces a Ruin and Recreate move for both basic and list variable. (Not chained.) Also introduces a largely refactored "Optimization algorithms" section of the documentation. It moves away from "everything on a single page" approach, and breaks the content down by topic - just as we already do for many other topics. --------- Co-authored-by: Christopher Chianelli <[email protected]> Co-authored-by: Frederico Gonçalves <[email protected]>
TimefoldAI · Aug 27, 2024 · 85e6812 · 85e6812
1 parent ff6ae02
commit 85e6812
Show file tree

Hide file tree

Showing 136 changed files with 6,720 additions and 4,851 deletions.
diff --git a/benchmark/src/main/resources/benchmark.xsd b/benchmark/src/main/resources/benchmark.xsd
@@ -1100,6 +1100,12 @@
             <xs:element name="pillarSwapMoveSelector" type="tns:pillarSwapMoveSelectorConfig"/>
 
 
+            <xs:element name="ruinRecreateMoveSelector" type="tns:ruinRecreateMoveSelectorConfig"/>
+
+
+            <xs:element name="listRuinRecreateMoveSelector" type="tns:listRuinRecreateMoveSelectorConfig"/>
+
+
             <xs:element name="subChainChangeMoveSelector" type="tns:subChainChangeMoveSelectorConfig"/>
 
 
@@ -1553,6 +1559,78 @@
   </xs:complexType>
 
 
+  <xs:complexType name="ruinRecreateMoveSelectorConfig">
+
+
+    <xs:complexContent>
+
+
+      <xs:extension base="tns:moveSelectorConfig">
+
+
+        <xs:sequence>
+
+
+          <xs:element minOccurs="0" name="minimumRuinedCount" type="xs:int"/>
+
+
+          <xs:element minOccurs="0" name="maximumRuinedCount" type="xs:int"/>
+
+
+          <xs:element minOccurs="0" name="minimumRuinedPercentage" type="xs:double"/>
+
+
+          <xs:element minOccurs="0" name="maximumRuinedPercentage" type="xs:double"/>
+
+
+        </xs:sequence>
+
+
+      </xs:extension>
+
+
+    </xs:complexContent>
+
+
+  </xs:complexType>
+
+
+  <xs:complexType name="listRuinRecreateMoveSelectorConfig">
+
+
+    <xs:complexContent>
+
+
+      <xs:extension base="tns:moveSelectorConfig">
+
+
+        <xs:sequence>
+
+
+          <xs:element minOccurs="0" name="minimumRuinedCount" type="xs:int"/>
+
+
+          <xs:element minOccurs="0" name="maximumRuinedCount" type="xs:int"/>
+
+
+          <xs:element minOccurs="0" name="minimumRuinedPercentage" type="xs:double"/>
+
+
+          <xs:element minOccurs="0" name="maximumRuinedPercentage" type="xs:double"/>
+
+
+        </xs:sequence>
+
+
+      </xs:extension>
+
+
+    </xs:complexContent>
+
+
+  </xs:complexType>
+
+
   <xs:complexType name="subChainChangeMoveSelectorConfig">
 
 
@@ -1859,6 +1937,12 @@
             <xs:element name="pillarSwapMoveSelector" type="tns:pillarSwapMoveSelectorConfig"/>
 
 
+            <xs:element name="ruinRecreateMoveSelector" type="tns:ruinRecreateMoveSelectorConfig"/>
+
+
+            <xs:element name="listRuinRecreateMoveSelector" type="tns:listRuinRecreateMoveSelectorConfig"/>
+
+
             <xs:element name="subChainChangeMoveSelector" type="tns:subChainChangeMoveSelectorConfig"/>
 
 
@@ -2207,6 +2291,12 @@
             <xs:element name="pillarSwapMoveSelector" type="tns:pillarSwapMoveSelectorConfig"/>
 
 
+            <xs:element name="ruinRecreateMoveSelector" type="tns:ruinRecreateMoveSelectorConfig"/>
+
+
+            <xs:element name="listRuinRecreateMoveSelector" type="tns:listRuinRecreateMoveSelectorConfig"/>
+
+
             <xs:element name="subChainChangeMoveSelector" type="tns:subChainChangeMoveSelectorConfig"/>
 
 

diff --git a/core/src/build/revapi-differences.json b/core/src/build/revapi-differences.json
@@ -24,6 +24,28 @@
           "oldValue": "{\"easyScoreCalculatorClass\", \"easyScoreCalculatorCustomProperties\", \"constraintProviderClass\", \"constraintProviderCustomProperties\", \"constraintStreamImplType\", \"incrementalScoreCalculatorClass\", \"incrementalScoreCalculatorCustomProperties\", \"scoreDrlList\", \"initializingScoreTrend\", \"assertionScoreDirectorFactory\"}",
           "newValue": "{\"easyScoreCalculatorClass\", \"easyScoreCalculatorCustomProperties\", \"constraintProviderClass\", \"constraintProviderCustomProperties\", \"constraintStreamImplType\", \"constraintStreamAutomaticNodeSharing\", \"incrementalScoreCalculatorClass\", \"incrementalScoreCalculatorCustomProperties\", \"scoreDrlList\", \"initializingScoreTrend\", \"assertionScoreDirectorFactory\"}",
           "justification": "Add support for automatic constraint stream node sharing outside of Quarkus for Timefold Solver Enterprise edition users."
+        },
+        {
+          "ignore": true,
+          "code": "java.annotation.attributeValueChanged",
+          "old": "class ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_ extends ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_>>",
+          "new": "class ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_ extends ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_>>",
+          "annotationType": "jakarta.xml.bind.annotation.XmlSeeAlso",
+          "attribute": "value",
+          "oldValue": "{ai.timefold.solver.core.config.heuristic.selector.move.composite.CartesianProductMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.ChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.kopt.KOptListMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.ListChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.ListSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.factory.MoveIteratorFactoryConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.factory.MoveListFactoryConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.PillarChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.PillarSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.SubChainChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.SubChainSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.SubListChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.SubListSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.SwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.TailChainSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.composite.UnionMoveSelectorConfig.class}",
+          "newValue": "{ai.timefold.solver.core.config.heuristic.selector.move.composite.CartesianProductMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.ChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.kopt.KOptListMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.ListChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.ListSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.factory.MoveIteratorFactoryConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.factory.MoveListFactoryConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.PillarChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.PillarSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.RuinRecreateMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.SubChainChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.SubChainSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.SubListChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.SubListSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.SwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.TailChainSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.composite.UnionMoveSelectorConfig.class}",
+          "justification": "Add support for ruin moves"
+        },
+        {
+          "ignore": true,
+          "code": "java.annotation.attributeValueChanged",
+          "old": "class ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_ extends ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_>>",
+          "new": "class ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_ extends ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_>>",
+          "annotationType": "jakarta.xml.bind.annotation.XmlSeeAlso",
+          "attribute": "value",
+          "oldValue": "{ai.timefold.solver.core.config.heuristic.selector.move.composite.CartesianProductMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.ChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.kopt.KOptListMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.ListChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.ListSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.factory.MoveIteratorFactoryConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.factory.MoveListFactoryConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.PillarChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.PillarSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.SubChainChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.SubChainSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.SubListChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.SubListSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.SwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.TailChainSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.composite.UnionMoveSelectorConfig.class}",
+          "newValue": "{ai.timefold.solver.core.config.heuristic.selector.move.composite.CartesianProductMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.ChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.kopt.KOptListMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.ListChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.ListSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.factory.MoveIteratorFactoryConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.factory.MoveListFactoryConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.PillarChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.PillarSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.RuinRecreateMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.ListRuinRecreateMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.SubChainChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.SubChainSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.SubListChangeMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.list.SubListSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.SwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.TailChainSwapMoveSelectorConfig.class, ai.timefold.solver.core.config.heuristic.selector.move.composite.UnionMoveSelectorConfig.class}",
+          "justification": "Add support for list ruin moves"
         }
       ]
     }

diff --git a/.../main/java/ai/timefold/solver/core/config/heuristic/selector/move/MoveSelectorConfig.java b/.../main/java/ai/timefold/solver/core/config/heuristic/selector/move/MoveSelectorConfig.java
@@ -18,11 +18,13 @@
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.ChangeMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.PillarChangeMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.PillarSwapMoveSelectorConfig;
+import ai.timefold.solver.core.config.heuristic.selector.move.generic.RuinRecreateMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.SwapMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.SubChainChangeMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.SubChainSwapMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.TailChainSwapMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.list.ListChangeMoveSelectorConfig;
+import ai.timefold.solver.core.config.heuristic.selector.move.generic.list.ListRuinRecreateMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.list.ListSwapMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.list.SubListChangeMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.list.SubListSwapMoveSelectorConfig;
@@ -47,6 +49,8 @@
         MoveListFactoryConfig.class,
         PillarChangeMoveSelectorConfig.class,
         PillarSwapMoveSelectorConfig.class,
+        RuinRecreateMoveSelectorConfig.class,
+        ListRuinRecreateMoveSelectorConfig.class,
         SubChainChangeMoveSelectorConfig.class,
         SubChainSwapMoveSelectorConfig.class,
         SubListChangeMoveSelectorConfig.class,

diff --git a/...ver/core/config/heuristic/selector/move/composite/CartesianProductMoveSelectorConfig.java b/...ver/core/config/heuristic/selector/move/composite/CartesianProductMoveSelectorConfig.java
@@ -14,11 +14,13 @@
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.ChangeMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.PillarChangeMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.PillarSwapMoveSelectorConfig;
+import ai.timefold.solver.core.config.heuristic.selector.move.generic.RuinRecreateMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.SwapMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.SubChainChangeMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.SubChainSwapMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.TailChainSwapMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.list.ListChangeMoveSelectorConfig;
+import ai.timefold.solver.core.config.heuristic.selector.move.generic.list.ListRuinRecreateMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.list.ListSwapMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.list.SubListChangeMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.list.SubListSwapMoveSelectorConfig;
@@ -45,6 +47,10 @@ public class CartesianProductMoveSelectorConfig extends MoveSelectorConfig<Carte
             @XmlElement(name = PillarChangeMoveSelectorConfig.XML_ELEMENT_NAME,
                     type = PillarChangeMoveSelectorConfig.class),
             @XmlElement(name = PillarSwapMoveSelectorConfig.XML_ELEMENT_NAME, type = PillarSwapMoveSelectorConfig.class),
+            @XmlElement(name = RuinRecreateMoveSelectorConfig.XML_ELEMENT_NAME,
+                    type = RuinRecreateMoveSelectorConfig.class),
+            @XmlElement(name = ListRuinRecreateMoveSelectorConfig.XML_ELEMENT_NAME,
+                    type = ListRuinRecreateMoveSelectorConfig.class),
             @XmlElement(name = SubChainChangeMoveSelectorConfig.XML_ELEMENT_NAME,
                     type = SubChainChangeMoveSelectorConfig.class),
             @XmlElement(name = SubChainSwapMoveSelectorConfig.XML_ELEMENT_NAME,

diff --git a/...imefold/solver/core/config/heuristic/selector/move/composite/UnionMoveSelectorConfig.java b/...imefold/solver/core/config/heuristic/selector/move/composite/UnionMoveSelectorConfig.java
@@ -17,11 +17,13 @@
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.ChangeMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.PillarChangeMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.PillarSwapMoveSelectorConfig;
+import ai.timefold.solver.core.config.heuristic.selector.move.generic.RuinRecreateMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.SwapMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.SubChainChangeMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.SubChainSwapMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.TailChainSwapMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.list.ListChangeMoveSelectorConfig;
+import ai.timefold.solver.core.config.heuristic.selector.move.generic.list.ListRuinRecreateMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.list.ListSwapMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.list.SubListChangeMoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.list.SubListSwapMoveSelectorConfig;
@@ -52,6 +54,10 @@ public class UnionMoveSelectorConfig
             @XmlElement(name = PillarChangeMoveSelectorConfig.XML_ELEMENT_NAME,
                     type = PillarChangeMoveSelectorConfig.class),
             @XmlElement(name = PillarSwapMoveSelectorConfig.XML_ELEMENT_NAME, type = PillarSwapMoveSelectorConfig.class),
+            @XmlElement(name = RuinRecreateMoveSelectorConfig.XML_ELEMENT_NAME,
+                    type = RuinRecreateMoveSelectorConfig.class),
+            @XmlElement(name = ListRuinRecreateMoveSelectorConfig.XML_ELEMENT_NAME,
+                    type = ListRuinRecreateMoveSelectorConfig.class),
             @XmlElement(name = SubChainChangeMoveSelectorConfig.XML_ELEMENT_NAME,
                     type = SubChainChangeMoveSelectorConfig.class),
             @XmlElement(name = SubChainSwapMoveSelectorConfig.XML_ELEMENT_NAME,