From 982f7e033b36f92a077aae329504f4b87060c5e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luk=C3=A1=C5=A1=20Petrovick=C3=BD?= Date: Wed, 14 Aug 2024 08:35:38 +0200 Subject: [PATCH] docs: document the new moves --- .../move-selector-reference.adoc | 172 ++++++++++++++++++ 1 file changed, 172 insertions(+) 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 index 72e8bdabbf..093dc3f6c3 100644 --- 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: |<> |Swap 2 sets of entities with the same values +|<> +|Take a subset of entities, uninitialize them and run a construction heuristic to put them back + |<> |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: |<> |Select an entity, remove k edges from its list variable, add k new edges from the removed endpoints +|<> +|Take a subset of values, remove them from their lists, and run a construction heuristic to recreate the lists + |<> |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"] +---- + +---- + +[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"] +---- + + 5 + 40 + +---- + +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"] +---- + + + 100.0 + + + + + + + 1.0 + + +---- + +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: ---- +[#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"] +---- + +---- + +[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"] +---- + + 5 + 40 + +---- + +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"] +---- + + + 100.0 + + + + + + + 1.0 + + +---- + +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