Skip to content

Commit

Permalink
docs: restucture multi-threaded section
Browse files Browse the repository at this point in the history
  • Loading branch information
triceo committed Dec 10, 2024
1 parent 3a1ef62 commit 45523c3
Show file tree
Hide file tree
Showing 7 changed files with 39 additions and 34 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -154,7 +154,7 @@ as shown in the following table:
The following features are only available in Timefold Solver Enterprise Edition:

* <<nearbySelection,Nearby selection>>,
* <<multithreadedSolving,multi-threaded solving>>,
* <<multithreadedIncrementalSolving,multi-threaded incremental solving>>,
* <<partitionedSearch,partitioned search>>,
* <<automaticNodeSharing,automatic node sharing>>,
* and <<throttlingBestSolutionEvents, throttling best solution events>>.
Expand Down Expand Up @@ -457,42 +457,26 @@ only set the distribution type (so without a `distributionSizeMaximum` parameter
----


[#multithreadedSolving]
[#enterpriseMultithreadedSolving]
=== Multi-threaded solving

[NOTE]
====
This feature is a commercial feature of Timefold Solver Enterprise Edition.
It is not available in the Community Edition.
====

There are several ways of doing multi-threaded solving:
Multi-threaded solving is a term
which encapsulates several features that allow Timefold Solver to run on multi-core machines.
Timefold Solver Enterprise Edition makes multi-threaded solving more powerful by introducing
<<multithreadedIncrementalSolving,multi-threaded incremental solving>> and
<<partitionedSearch,partitioned search>>.

* *<<multithreadedIncrementalSolving,Multi-threaded incremental solving>>*:
Solve 1 dataset with multiple threads without sacrificing xref:constraints-and-score/performance.adoc#incrementalScoreCalculationPerformance[incremental score calculation].
** Donate a portion of your CPU cores to Timefold Solver to scale up the move evaluation speed and get the same results in fraction of the time.
* *<<partitionedSearch,Partitioned Search>>*:
Split 1 dataset in multiple parts and solve them independently.
* *Multi bet solving*: solve 1 dataset with multiple, isolated solvers and take the best result.
** Not recommended: This is a marginal gain for a high cost of hardware resources.
** Use the xref:using-timefold-solver/benchmarking-and-tweaking.adoc#benchmarker[Benchmarker] during development to determine the algorithm that is the most appropriate on average.
* *Multitenancy*: solve different datasets in parallel.
** The xref:using-timefold-solver/running-the-solver.adoc#solverManager[`SolverManager`] can help with that.
For a primer on multi-threaded solving in general, see xref:using-timefold-solver/running-the-solver.adoc#multithreadedSolving[Multi-threaded solving].

image::enterprise-edition/multiThreadingStrategies.png[align="center"]

In this section, we will focus on multi-threaded incremental solving and partitioned search.
[#multithreadedIncrementalSolving]
==== Multi-threaded incremental solving

[NOTE]
====
A xref:using-timefold-solver/running-the-solver.adoc#logging[logging level] of `debug` or `trace` might cause congestion
and slow down the xref:constraints-and-score/performance.adoc#moveEvaluationSpeed[move evaluation speed].
This feature is a commercial feature of Timefold Solver Enterprise Edition.
It is not available in the Community Edition.
====


[#multithreadedIncrementalSolving]
==== Multi-threaded incremental solving

With this feature, the solver can run significantly faster,
getting you the right solution earlier.
It has been designed to speed up the solver in cases where move evaluation is the bottleneck.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -319,7 +319,7 @@ see xref:enterprise-edition/enterprise-edition.adoc#switchToEnterpriseEdition[th
.icon:info-circle[role=yellow] `LookupStrategyType` deprecated for removal
[%collapsible%open]
====
`LookupStrategyType` is used in xref:enterprise-edition/enterprise-edition.adoc#multithreadedSolving[multi-threaded solving]
`LookupStrategyType` is used in xref:enterprise-edition/enterprise-edition.adoc#multithreadedIncrementalSolving[multi-threaded incremental solving]
to specify how the solver should match entities and facts between parent and child score directors.
The default value is `PLANNING_ID_OR_NONE`, which means
that the solver will look up entities by their xref:using-timefold-solver/modeling-planning-problems.adoc#planningId[planning ID].
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1086,7 +1086,8 @@ for example when running benchmarks on an application server or a cloud platform
[NOTE]
====
This feature is independent of xref:enterprise-edition/enterprise-edition.adoc#multithreadedSolving[multithreaded solving].
This feature is independent of xref:enterprise-edition/enterprise-edition.adoc#multithreadedIncrementalSolving[multi-threaded incremental solving] (an enterprise feature),
and can be used in Timefold Solver Community Edition as well.
====
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,7 @@ Alternatively, you can sometimes also introduce <<cachedProblemFact,_a cached pr
=== `@PlanningId`

For some functionality
(such as xref:enterprise-edition/enterprise-edition.adoc#multithreadedSolving[multi-threaded solving]
(such as xref:enterprise-edition/enterprise-edition.adoc#multithreadedIncrementalSolving[multi-threaded incremental solving]
and xref:responding-to-change/responding-to-change.adoc#realTimePlanning[real-time planning]),
Timefold Solver needs to map problem facts and planning entities to an ID.
Timefold Solver uses that ID to _rebase_ a move from one thread's solution state to another's.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,25 @@ The solution instance given to the `solve(Solution)` method does not need to be
It can be partially or fully initialized, which is often the case in xref:responding-to-change/responding-to-change.adoc[repeated planning].
====

[#multithreadedSolving]
=== Multi-threaded solving

There are several ways of running the solver in parallel:

* *xref:enterprise-edition/enterprise-edition.adoc#multithreadedIncrementalSolving[Multi-threaded incremental solving]*:
Solve 1 dataset with multiple threads without sacrificing xref:constraints-and-score/performance.adoc#incrementalScoreCalculationPerformance[incremental score calculation].
This is an exclusive feature of the xref:enterprise-edition/enterprise-edition.adoc[Enterprise Edition].
* *xref:enterprise-edition/enterprise-edition.adoc#partitionedSearch[Partitioned search]*:
Split 1 dataset in multiple parts and solve them independently.
This is an exclusive feature of the xref:enterprise-edition/enterprise-edition.adoc[Enterprise Edition].
* *Multi bet solving*: solve 1 dataset with multiple, isolated solvers and take the best result.
** Not recommended: This is a marginal gain for a high cost of hardware resources.
** Use the xref:using-timefold-solver/benchmarking-and-tweaking.adoc#benchmarker[Benchmarker] during development to determine the algorithm that is the most appropriate on average.
* *Multitenancy*: solve different datasets in parallel.
** The xref:using-timefold-solver/running-the-solver.adoc#solverManager[`SolverManager`] can help with that.
image::using-timefold-solver/running-the-solver/multiThreadingStrategies.png[align="center"]

[#environmentMode]
== Environment mode: are there bugs in my code?
Expand Down Expand Up @@ -262,7 +281,8 @@ Even `debug` logging can slow down performance considerably for fast stepping al
(such as Late Acceptance and Simulated Annealing),
but not for slow stepping algorithms (such as Tabu Search).
Both cause congestion in xref:enterprise-edition/enterprise-edition.adoc#multithreadedSolving[multi-threaded solving] with most appenders, see below.
Both cause congestion in xref:using-timefold-solver/running-the.solver.adoc#multithreadedSolving[multi-threaded solving] with most appenders,
see below.
In Eclipse, `debug` logging to the console tends to cause congestion with move evaluation speeds above 10 000 per second.
Nor IntelliJ, nor the Maven command line suffer from this problem.
Expand Down Expand Up @@ -371,7 +391,7 @@ logging.config.fileConfig('logging.conf')
[NOTE]
====
When running multiple solvers or a xref:enterprise-edition/enterprise-edition.adoc#multithreadedSolving[multi-threaded solver],
When running multiple solvers or a xref:using-timefold-solver/running-the.solver.adoc#multithreadedSolving[multi-threaded solver],
most appenders (including the console) cause congestion with `debug` and `trace` logging.
Switch to an async appender to avoid this problem or turn off `debug` logging.
====
Expand Down Expand Up @@ -645,7 +665,7 @@ For example, if set to `4`, submitting five problems
has four problems solving immediately, and the fifth one starts when another one ends.
If those problems solve for 5 minutes each, the fifth problem takes 10 minutes to finish.
By default, `parallelSolverCount` is set to `AUTO`, which resolves to half the CPU cores,
regardless of the xref:enterprise-edition/enterprise-edition.adoc#multithreadedSolving[`moveThreadCount`] of the solvers.
regardless of the xref:enterprise-edition/enterprise-edition.adoc#enterpriseMultithreadedSolving[`moveThreadCount`] of the solvers.
To retrieve the best solution, after solving terminates normally, use `SolverJob.getFinalBestSolution()`:
Expand Down

0 comments on commit 45523c3

Please sign in to comment.