docs: mixed model CH

Author: zepfred

docs/src/modules/ROOT/pages/optimization-algorithms/construction-heuristics.adoc

@@ -702,6 +702,76 @@ is supported too.
 For scaling out, see <<scalingConstructionHeuristics,scaling construction heuristics>>.
 
 
+[#mixedModelConstructionHeuristics]
+== Mixed modeling and construction heuristics
+
+If the model includes both xref:using-timefold-solver/modeling-planning-problems.adoc#planningVariable[basic] and xref:using-timefold-solver/modeling-planning-problems#planningListVariable[list] variables,
+the default behavior of the construction heuristic is
+to use strategies based on the allocation of xref:optimization-algorithms/construction-heuristics.adoc#allocateEntityFromQueue[entities] and xref:optimization-algorithms/construction-heuristics.adoc#allocateToValueFromQueue[values]
+for solving all related variables.
+
+=== Algorithm description
+
+The allocations work like this:
+
+. Put all entities in a queue.
+. Assign the first entity (from that queue) to the best value.
+. Repeat until all entities are assigned.
+. Put all values in a round-robin queue.
+. Assign the best entity to the first value (from that queue).
+. Repeat until all entities are assigned.
+
+[#mixedModelConfiguration]
+=== Configuration
+
+Simple configuration:
+
+[source,xml,options="nowrap"]
+----
+    <constructionHeuristic>
+        <queuedEntityPlacer/>
+    </constructionHeuristic>
+    <constructionHeuristic>
+        <queuedValuePlacer>
+            <valueSelector variableName="variableName"/>
+        </queuedValuePlacer>
+    </constructionHeuristic>
+----
+
+Advanced configuration for a single entity class with a list variable and a single basic variable:
+
+[source,xml,options="nowrap"]
+----
+  <!-- Basic Variable -->
+  <constructionHeuristic>
+    <queuedEntityPlacer>
+      <entitySelector id="placerEntitySelector">
+        <cacheType>PHASE</cacheType>
+        <selectionOrder>SORTED</selectionOrder>
+        <sorterManner>DECREASING_DIFFICULTY</sorterManner>
+      </entitySelector>
+      <changeMoveSelector>
+        <entitySelector mimicSelectorRef="placerEntitySelector"/>
+        <valueSelector>
+          <cacheType>PHASE</cacheType>
+          <selectionOrder>SORTED</selectionOrder>
+          <sorterManner>INCREASING_STRENGTH</sorterManner>
+        </valueSelector>
+      </changeMoveSelector>
+    </queuedEntityPlacer>
+  </constructionHeuristic>
+  <!-- List Variable -->
+  <constructionHeuristic>
+    <queuedValuePlacer>
+      <valueSelector variableName="variableName">
+        <cacheType>PHASE</cacheType>
+        <selectionOrder>SORTED</selectionOrder>
+        <sorterManner>INCREASING_STRENGTH</sorterManner>
+      </valueSelector>
+    </queuedValuePlacer>
+  </constructionHeuristic>
+----
+
 [#scalingConstructionHeuristics]
 == Scaling construction heuristics