docs: document the new moves

TimefoldAI · Aug 14, 2024 · 982f7e0 · 982f7e0
1 parent 8b20241
commit 982f7e0
Showing 1 changed file with 172 additions and 0 deletions.
diff --git a/docs/src/modules/ROOT/pages/optimization-algorithms/move-selector-reference.adoc b/docs/src/modules/ROOT/pages/optimization-algorithms/move-selector-reference.adoc
@@ -26,6 +26,9 @@ The following `MoveSelector` implementations are available out of the box:
 |<<pillarSwapMoveSelector,Pillar swap move>>
 |Swap 2 sets of entities with the same values
 
+|<<ruinRecreateMoveSelector,Ruin and Recreate move>>
+|Take a subset of entities, uninitialize them and run a construction heuristic to put them back
+
 |<<listChangeMoveSelector,List change move>>
 |Move a list element to a different index or to another entity's list variable
 
@@ -41,6 +44,9 @@ The following `MoveSelector` implementations are available out of the box:
 |<<kOptListMoveSelector,k-opt move>>
 |Select an entity, remove k edges from its list variable, add k new edges from the removed endpoints
 
+|<<listRuinRecreateMoveSelector,List Ruin and Recreate move>>
+|Take a subset of values, remove them from their lists, and run a construction heuristic to recreate the lists
+
 |<<tailChainSwapMoveSelector,Tail chain swap move>>
 |Swap 2 tails chains
 
@@ -55,6 +61,9 @@ The following `MoveSelector` implementations are available out of the box:
 [#basicMoveSelectors]
 == Move selectors for basic variables
 
+These moves are applicable to planning variables that are not part of a list or a chain,
+also called xref:using-timefold-solver/modeling-planning-problems.adoc#planningVariable[basic variables].
+
 [#changeMoveSelector]
 === `ChangeMoveSelector`
 
@@ -319,9 +328,91 @@ In this case, the entity being operated on need not be `Comparable`.
 The given `subPillarSequenceComparatorClass` is used to establish the sequence instead.
 Also, the size of the sub-pillars is limited in length of up to 1000 entities.
 
+[#ruinRecreateMoveSelector]
+=== `RuinRecreateMoveSelector`
+
+The `RuinRecreateMove` selects a subset of entities and sets their values to null,
+effectively unassigning them.
+Then it runs a construction heuristic to assign them again.
+If xref:using-timefold-solver/modeling-planning-problems.adoc#planningVariableAllowingUnassigned[unassigned values] are allowed,
+it may leave them unassigned.
+
+This coarse-grained move is useful to help get the solver out of a local optimum.
+It allows the solver to effectively "undo" a number of previous decisions in one step,
+opening up a new part of the solution space.
+
+[NOTE]
+====
+If xref:enterprise-edition/enterprise-edition.adoc#nearbySelection[nearby selection] is enabled,
+the `RuinRecreateMove` is likely to under-perform
+as it won't be able to rebuild the solution using nearby selection.
+This almost always results in worse solutions than those that were originally ruined,
+without a big likelihood of leading to a better solution further down the line.
+We recommend not using this move together with nearby selection.
+====
+
+This move is not enabled by default.
+To enable it, add the following to the `localSearch` section of the solver configuration:
+
+[source,xml,options="nowrap"]
+----
+    <ruinRecreateMoveSelector/>
+----
+
+[IMPORTANT]
+====
+The default values have been determined by extensive benchmarking.
+That said, the optimal values may vary depending on the problem, available solving time, and dataset at hand.
+We recommend that you xref:using-timefold-solver/benchmarking-and-tweaking.adoc#benchmarker[experiment with these values]
+to find the best fit for your problem.
+====
+
+Advanced configuration:
+
+[source,xml,options="nowrap"]
+----
+    <ruinRecreateMoveSelector>
+      <minimumRuinedCount>5</minimumRuinedCount>
+      <maximumRuinedCount>40</maximumRuinedCount>
+    </ruinRecreateMoveSelector>
+----
+
+The `minimumRuinedCount` and `maximumRuinedCount` properties limit the number of entities that are unassigned.
+The default values are `5` and `20` respectively, but for large datasets,
+it may prove beneficial to increase these values.
+
+Since the `RuinRecreateMove` is a coarse-grained move,
+it is expensive and can slow the solver down significantly.
+However, the default local search configuration will attempt to run it at the same frequency
+as the other fine-grained moves.
+For that reason, we recommend that you use xref:optimization-algorithms/overview.adoc#probabilisticSelection[probabilistic selection]
+to control the frequency of this move:
+
+[source,xml,options="nowrap"]
+----
+    <unionMoveSelector>
+        <unionMoveSelector>
+            <fixedProbabilityWeight>100.0</fixedProbabilityWeight>
+            <changeMoveSelector/>
+            <swapMoveSelector/>
+            <pillarChangeMoveSelector/>
+            <pillarSwapMoveSelector/>
+        </unionMoveSelector>
+        <ruinMoveSelector>
+            <fixedProbabilityWeight>1.0</fixedProbabilityWeight>
+        </ruinMoveSelector>
+    </unionMoveSelector>
+----
+
+The above configuration will run the `RuinRecreateMove` once for every 100 fine-grained moves.
+As always, benchmarking is recommended to find the optimal value for your use case.
+
+
 [#listMoveSelectors]
 == Move selectors for list variables
 
+These moves are applicable to xref:using-timefold-solver/modeling-planning-problems.adoc#planningListVariable[list planning variables].
+
 [#listChangeMoveSelector]
 === `ListChangeMoveSelector`
 
@@ -459,9 +550,90 @@ Advanced configuration:
     </kOptListMoveSelector>
 ----
 
+[#listRuinRecreateMoveSelector]
+=== `ListRuinRecreateMoveSelector`
+
+The `ListRuinRecreateMove` selects a subset of values, and removes them from their list variables.
+Then it runs a construction heuristic to assign them again.
+If xref:using-timefold-solver/modeling-planning-problems.adoc#planningListVariableAllowingUnassigned[unassigned values] are allowed,
+it may leave them unassigned.
+
+This coarse-grained move is useful to help get the solver out of a local optimum.
+It allows the solver to effectively "undo" a number of previous decisions in one step,
+opening up a new part of the solution space.
+
+[NOTE]
+====
+If xref:enterprise-edition/enterprise-edition.adoc#nearbySelection[nearby selection] is enabled,
+the `RuinRecreateMove` is likely to under-perform
+as it won't be able to rebuild the solution using nearby selection.
+This almost always results in worse solutions than those that were originally ruined,
+without a big likelihood of leading to a better solution further down the line.
+We recommend not using this move together with nearby selection.
+====
+
+This move is not enabled by default.
+To enable it, add the following to the `localSearch` section of the solver configuration:
+
+[source,xml,options="nowrap"]
+----
+    <listRuinRecreateMoveSelector/>
+----
+
+[IMPORTANT]
+====
+The default values have been determined by extensive benchmarking.
+That said, the optimal values may vary depending on the problem, available solving time, and dataset at hand.
+We recommend that you xref:using-timefold-solver/benchmarking-and-tweaking.adoc#benchmarker[experiment with these values]
+to find the best fit for your problem.
+====
+
+Advanced configuration:
+
+[source,xml,options="nowrap"]
+----
+    <listRuinRecreateMoveSelector>
+      <minimumRuinedCount>5</minimumRuinedCount>
+      <maximumRuinedCount>40</maximumRuinedCount>
+    </listRuinRecreateMoveSelector>
+----
+
+The `minimumRuinedCount` and `maximumRuinedCount` properties limit the number of values that are unassigned.
+The default values are `5` and `20` respectively, but for large datasets,
+it may prove beneficial to increase these values.
+
+Since the `RuinRecreateMove` is a coarse-grained move,
+it is expensive and can slow the solver down significantly.
+However, the default local search configuration will attempt to run it at the same frequency
+as the other fine-grained moves.
+For that reason, we recommend that you use xref:optimization-algorithms/overview.adoc#probabilisticSelection[probabilistic selection]
+to control the frequency of this move:
+
+[source,xml,options="nowrap"]
+----
+    <unionMoveSelector>
+        <unionMoveSelector>
+            <fixedProbabilityWeight>100.0</fixedProbabilityWeight>
+            <changeMoveSelector/>
+            <swapMoveSelector/>
+            <pillarChangeMoveSelector/>
+            <pillarSwapMoveSelector/>
+        </unionMoveSelector>
+        <listRuinMoveSelector>
+            <fixedProbabilityWeight>1.0</fixedProbabilityWeight>
+        </listRuinMoveSelector>
+    </unionMoveSelector>
+----
+
+The above configuration will run the `RuinRecreateMove` once for every 100 fine-grained moves.
+As always, benchmarking is recommended to find the optimal value for your use case.
+
+
 [#chainMoveSelectors]
 == Move selectors for chained variables
 
+These moves are applicable to xref:using-timefold-solver/modeling-planning-problems.adoc#chainedPlanningVariable[chained planning variable].
+
 [#tailChainSwapMoveSelector]
 === `TailChainSwapMoveSelector` or 2-opt