Timefold Solver

https://docs.timefold.ai/timefold-solver/latest/
Admin
Timefold Solver is an AI-powered constraint solver designed to optimize planning and scheduling...
Tokens:187,900
Snippets:2,304
Trust Score:8.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### Clone the Timefold Quickstarts Repository

Source: https://docs.timefold.ai/timefold-solver/latest/quickstart/hello-world/hello-world-quickstart

Use this command to download the example projects from GitHub.

```shell
$ git clone https://github.com/TimefoldAI/timefold-quickstarts
```

--------------------------------

### Install Java via SDKMAN

Source: https://docs.timefold.ai/timefold-solver/latest/quickstart/spring-boot/spring-boot-quickstart

Commands to install the Java Development Kit using the SDKMAN tool.

```shell
$ curl -s "https://get.sdkman.io" | bash
$ sdk install java
```

--------------------------------

### Solver Execution Logs

Source: https://docs.timefold.ai/timefold-solver/latest/quickstart/spring-boot/spring-boot-quickstart

Example output from the server-side logs showing solver progress.

```text
... Solving started: time spent (33), best score (0hard/0soft), environment mode (PHASE_ASSERT), random (JDK with seed 0).
... Construction Heuristic phase (0) ended: time spent (73), best score (0hard/0soft), move evaluation speed (459/sec), step total (4).
... Local Search phase (1) ended: time spent (5000), best score (0hard/0soft), move evaluation speed (28949/sec), step total (28398).
... Solving ended: time spent (5000), best score (0hard/0soft), move evaluation speed (28524/sec), phase total (2), environment mode (PHASE_ASSERT).
```

--------------------------------

### MoveListFactory Configuration

Source: https://docs.timefold.ai/timefold-solver/latest/optimization-algorithms/move-selector-reference

XML configuration examples for MoveListFactory, including simple and advanced setups with custom properties.

```xml
    <moveListFactory>
      <moveListFactoryClass>...MyMoveFactory</moveListFactoryClass>
    </moveListFactory>
```

```xml
    <moveListFactory>
      ... <!-- Normal moveSelector properties -->
      <moveListFactoryClass>...MyMoveFactory</moveListFactoryClass>
      <moveListFactoryCustomProperties>
        ...<!-- Custom properties -->
      </moveListFactoryCustomProperties>
    </moveListFactory>
```

--------------------------------

### Configure Variable Neighborhood Descent

Source: https://docs.timefold.ai/timefold-solver/latest/optimization-algorithms/local-search

Provides XML configuration examples for setting up the VND algorithm, ranging from a basic implementation to an advanced setup with custom move selectors and acceptors.

```xml
  <localSearch>
    <localSearchType>VARIABLE_NEIGHBORHOOD_DESCENT</localSearchType>
  </localSearch>
```

```xml
  <localSearch>
    <unionMoveSelector>
      <selectionOrder>ORIGINAL</selectionOrder>
      <changeMoveSelector/>
      <swapMoveSelector/>
      ...
    </unionMoveSelector>
    <acceptor>
      <acceptorType>HILL_CLIMBING</acceptorType>
    </acceptor>
    <forager>
      <pickEarlyType>FIRST_LAST_STEP_SCORE_IMPROVING</pickEarlyType>
    </forager>
  </localSearch>
```

--------------------------------

### Verify Application Startup Log

Source: https://docs.timefold.ai/timefold-solver/latest/quickstart/service/getting-started

Expected log output confirming the application has started and is listening on the local port.

```text
getting-started-school-timetabling <version> on JVM (powered by Quarkus {quarkus-version}) started in 1.552s. Listening on: http://localhost:8080
```

--------------------------------

### Initialize MoveTester

Source: https://docs.timefold.ai/timefold-solver/latest/optimization-algorithms/neighborhoods

Basic setup for the MoveTester using the solution and entity classes.

```java
// Timetable is the solution class, Lesson is a planning entity class.
var solutionMetaModel = PlanningSolutionMetaModel.of(Timetable.class, Lesson.class);
var tester = MoveTester.build(solutionMetaModel);
var context = tester.using(solution);
var move = ...; // Move you wish to test.
context.execute(move);
```

--------------------------------

### View solver step logs

Source: https://docs.timefold.ai/timefold-solver/latest/quickstart/spring-boot/spring-boot-quickstart

Example output when debug logging is enabled to show solver steps.

```text
... Solving started: time spent (67), best score (0hard/0soft), environment mode (PHASE_ASSERT), random (JDK with seed 0).
...     CH step (0), time spent (128), score (0hard/0soft), selected move count (15), picked move ([Math(101) {null -> Room A}, Math(101) {null -> MONDAY 08:30}]).
...     CH step (1), time spent (145), score (0hard/0soft), selected move count (15), picked move ([Physics(102) {null -> Room A}, Physics(102) {null -> MONDAY 09:30}]).
...
```

--------------------------------

### Start application in dev mode

Source: https://docs.timefold.ai/timefold-solver/latest/quickstart/quarkus/quarkus-quickstart

Commands to launch the Quarkus application using Maven or Gradle.

```shell
$ mvn compile quarkus:dev
```

```shell
$ gradle --console=plain quarkusDev
```

--------------------------------

### Start the application in development mode

Source: https://docs.timefold.ai/timefold-solver/latest/quickstart/quarkus-vehicle-routing/quarkus-vehicle-routing-quickstart

Launch the Quarkus application using the Maven development profile.

```shell
$ mvn compile quarkus:dev
```

--------------------------------

### Configure Strongest Fit

Source: https://docs.timefold.ai/timefold-solver/latest/optimization-algorithms/construction-heuristics

Provides simple and advanced XML configuration examples for the Strongest Fit construction heuristic.

```xml
  <constructionHeuristic>
    <constructionHeuristicType>STRONGEST_FIT</constructionHeuristicType>
  </constructionHeuristic>
```

```xml
  <constructionHeuristic>
    <constructionHeuristicType>STRONGEST_FIT</constructionHeuristicType>
    <...MoveSelector/>
    <...MoveSelector/>
    ...
  </constructionHeuristic>
```

--------------------------------

### Solver Metrics and KPIs

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/service/consumer-guide

Example of input metrics and KPIs provided in the response for assessing problem size and solution quality.

```json
{
  "inputMetrics": {
    "lessons": 200,
    "timeslots": 50
  },
  "kpis": {
    "unassignedLessons": 0,
    "maxConsecutiveLessons": 3
  }
}
```

--------------------------------

### Initialize Application Lessons

Source: https://docs.timefold.ai/timefold-solver/latest/quickstart/hello-world/hello-world-quickstart

Populates a list of Lesson objects with specific attributes and returns a new Timetable instance.

```kotlin
        val lessons: MutableList<Lesson> = ArrayList()
        var nextLessonId = 0L
        lessons.add(Lesson(nextLessonId++.toString(), "Math", "A. Turing", "9th grade"))
        lessons.add(Lesson(nextLessonId++.toString(), "Math", "A. Turing", "9th grade"))
        lessons.add(Lesson(nextLessonId++.toString(), "Physics", "M. Curie", "9th grade"))
        lessons.add(Lesson(nextLessonId++.toString(), "Chemistry", "M. Curie", "9th grade"))
        lessons.add(Lesson(nextLessonId++.toString(), "Biology", "C. Darwin", "9th grade"))
        lessons.add(Lesson(nextLessonId++.toString(), "History", "I. Jones", "9th grade"))
        lessons.add(Lesson(nextLessonId++.toString(), "English", "I. Jones", "9th grade"))
        lessons.add(Lesson(nextLessonId++.toString(), "English", "I. Jones", "9th grade"))
        lessons.add(Lesson(nextLessonId++.toString(), "Spanish", "P. Cruz", "9th grade"))
        lessons.add(Lesson(nextLessonId++.toString(), "Spanish", "P. Cruz", "9th grade"))

        lessons.add(Lesson(nextLessonId++.toString(), "Math", "A. Turing", "10th grade"))
        lessons.add(Lesson(nextLessonId++.toString(), "Math", "A. Turing", "10th grade"))
        lessons.add(Lesson(nextLessonId++.toString(), "Math", "A. Turing", "10th grade"))
        lessons.add(Lesson(nextLessonId++.toString(), "Physics", "M. Curie", "10th grade"))
        lessons.add(Lesson(nextLessonId++.toString(), "Chemistry", "M. Curie", "10th grade"))
        lessons.add(Lesson(nextLessonId++.toString(), "French", "M. Curie", "10th grade"))
        lessons.add(Lesson(nextLessonId++.toString(), "Geography", "C. Darwin", "10th grade"))
        lessons.add(Lesson(nextLessonId++.toString(), "History", "I. Jones", "10th grade"))
        lessons.add(Lesson(nextLessonId++.toString(), "English", "P. Cruz", "10th grade"))
        lessons.add(Lesson(nextLessonId.toString(), "Spanish", "P. Cruz", "10th grade"))

        return Timetable(timeslots, rooms, lessons)
    }
```

--------------------------------

### Example Solver Debug Log Output

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/solver-diagnostics

Sample output showing solver progress, including phase transitions, step timing, and score updates.

```text
INFO  Solving started: time spent (31), best score (0hard/0soft), environment mode (PHASE_ASSERT), move thread count (NONE), random (JDK with seed 0).
INFO  Problem scale: entity count (4), variable count (8), approximate value count (4), approximate problem scale (256).
DEBUG     CH step (0), time spent (47), score (0hard/0soft), selected move count (4), picked move ([Math(0) {null -> Room A}, Math(0) {null -> MONDAY 08:30}]).
DEBUG     CH step (1), time spent (50), score (0hard/0soft), selected move count (4), picked move ([Physics(1) {null -> Room A}, Physics(1) {null -> MONDAY 09:30}]).
DEBUG     CH step (2), time spent (51), score (-1hard/-1soft), selected move count (4), picked move ([Chemistry(2) {null -> Room B}, Chemistry(2) {null -> MONDAY 08:30}]).
DEBUG     CH step (3), time spent (52), score (-2hard/-1soft), selected move count (4), picked move ([Biology(3) {null -> Room A}, Biology(3) {null -> MONDAY 08:30}]).
INFO  Construction Heuristic phase (0) ended: time spent (53), best score (-2hard/-1soft), move evaluation speed (1066/sec), step total (4).
DEBUG     LS step (0), time spent (56), score (-2hard/0soft), new best score (-2hard/0soft), accepted/selected move count (1/1), picked move (Chemistry(2) {Room B, MONDAY 08:30} <-> Physics(1) {Room A, MONDAY 09:30}).
DEBUG     LS step (1), time spent (60), score (-2hard/1soft), new best score (-2hard/1soft), accepted/selected move count (1/2), picked move (Math(0) {Room A, MONDAY 08:30} <-> Physics(1) {Room B, MONDAY 08:30}).
DEBUG     LS step (2), time spent (60), score (-2hard/0soft),     best score (-2hard/1soft), accepted/selected move count (1/1), picked move (Math(0) {Room B, MONDAY 08:30} <-> Physics(1) {Room A, MONDAY 08:30}).
...
INFO  Local Search phase (1) ended: time spent (100), best score (0hard/1soft), move evaluation speed (2021/sec), step total (59).
INFO  Solving ended: time spent (100), best score (0hard/1soft), move evaluation speed (1100/sec), phase total (2), environment mode (PHASE_ASSERT), move thread count (NONE).
```

--------------------------------

### Run a Simple Benchmark

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/benchmarking-and-tweaking

Initialize a PlannerBenchmarkFactory from a solver configuration and execute benchmarks across multiple datasets.

```java
PlannerBenchmarkFactory benchmarkFactory = PlannerBenchmarkFactory.createFromSolverConfigXmlResource(
        "org/acme/vehiclerouting/solverConfig.xml");

VehicleRoutePlan dataset1 = ...;
VehicleRoutePlan dataset2 = ...;
VehicleRoutePlan dataset3 = ...;
PlannerBenchmark benchmark = benchmarkFactory.buildPlannerBenchmark(dataset1, dataset2, dataset3);
benchmark.benchmark();
```

--------------------------------

### REST Service Response Example

Source: https://docs.timefold.ai/timefold-solver/latest/quickstart/spring-boot/spring-boot-quickstart

Example of the JSON response returned by the solver after the termination limit is reached.

```json
HTTP/1.1 200
Content-Type: application/json
...

{"timeslots":...,"rooms":...,"lessons":[{"id":1,"subject":"Math","teacher":"A. Turing","studentGroup":"9th grade","timeslot":{"dayOfWeek":"MONDAY","startTime":"08:30:00","endTime":"09:30:00"},"room":{"name":"Room A"}},{"id":2,"subject":"Chemistry","teacher":"M. Curie","studentGroup":"9th grade","timeslot":{"dayOfWeek":"MONDAY","startTime":"09:30:00","endTime":"10:30:00"},"room":{"name":"Room A"}},{"id":3,"subject":"French","teacher":"M. Curie","studentGroup":"10th grade","timeslot":{"dayOfWeek":"MONDAY","startTime":"08:30:00","endTime":"09:30:00"},"room":{"name":"Room B"}},{"id":4,"subject":"History","teacher":"I. Jones","studentGroup":"10th grade","timeslot":{"dayOfWeek":"MONDAY","startTime":"09:30:00","endTime":"10:30:00"},"room":{"name":"Room B"}}],"score":"0hard/0soft"}
```

--------------------------------

### Example Score Explanation Output

Source: https://docs.timefold.ai/timefold-solver/latest/constraints-and-score/understanding-the-score

An example of the output generated by the score summary, showing constraint matches and justifications.

```text
Explanation of score (0hard/-10343soft):
    Constraint matches:
        -10343soft: constraint (minimizeTravelTime) has 6 matches:
            -2335soft: justified with (MinimizeTravelTimeJustification[vehicleName=1, totalDrivingTimeSeconds=2335, description=Vehicle '1' total travel time is 0 hours 39 minutes.])
            ... [2 more displayed constraint matches]
            ... and 3 more matches
        ...
```

--------------------------------

### Run a PlannerBenchmark from XML

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/benchmarking-and-tweaking

Initialize and execute a benchmark using a configuration file located on the classpath.

```java
PlannerBenchmarkFactory benchmarkFactory = PlannerBenchmarkFactory.createFromXmlResource(
        "org/acme/vehiclerouting/benchmarkConfig.xml");
PlannerBenchmark benchmark = benchmarkFactory.buildPlannerBenchmark();
benchmark.benchmark();
```

--------------------------------

### JPMS Access Error Example

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/library/library-integration

Example of an error message encountered when packages are not correctly exported or opened in the module configuration.

```text
class org.acme.schooltimetabling.domain.Timetable$Timefold$MemberAccessor$Field$lessons (in unnamed module @0x273444fe)
cannot access class org.acme.schooltimetabling.domain.Timetable (in module hello.world.school.timetabling)
because module hello.world.school.timetabling does not export org.acme.schooltimetabling.domain to unnamed module @0x273444fe
```

--------------------------------

### Enable Output Solution Writing

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/benchmarking-and-tweaking

Configure the benchmark to save the best solution found during each run to the benchmark directory.

```xml
    <problemBenchmarks>
      ...
      <writeOutputSolutionEnabled>true</writeOutputSolutionEnabled>
      ...
    </problemBenchmarks>
```

--------------------------------

### Invalid Precomputed Stream Example

Source: https://docs.timefold.ai/timefold-solver/latest/constraints-and-score/score-calculation

An example of an invalid precomputed stream that causes score corruption by referencing a planning variable.

```Java
TriConstraintStream<Shift, Shift, Integer> overlappingShifts(PrecomputeFactory precomputeFactory) {
    // This references Shift::getEmployee, which depends
    // on a planning variable and thus is not valid to
    // use in a precomputed stream
    return precomputeFactory.forEachUnfilteredUniquePair(Shift.class,
            Joiners.overlapping(Shift::getStart, Shift::getEnd),
            Joiners.equal(Shift::getEmployee))
        .expand((shift1, shift2) -> shift1.getOverlap(shift2));
}

Constraint noOverlappingShifts(ConstraintFactory constraintFactory) {
    return constraintFactory.precompute(this::overlappingShifts)
        .penalize(HardSoftScore.ONE_HARD, (shift1, shift2, overlap) -> overlap)
        .asConstraint("No overlapping shifts");
}
```

--------------------------------

### Implement Input and Output Metrics in SolverModel

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/service/exposing-metrics

Shows how to implement both metrics interfaces on a planning solution class.

```java
@PlanningSolution
public class Timetable implements SolverModel<HardMediumSoftScore>,
        InputMetricsAware<TimetableInputMetrics>,
        OutputMetricsAware<TimetableOutputMetrics> {

    // fields, getInputMetrics(), getOutputMetrics() excluded

}
```

```kotlin
@PlanningSolution
class Timetable : SolverModel<HardMediumSoftScore>,
        InputMetricsAware<TimetableInputMetrics>,
        OutputMetricsAware<TimetableOutputMetrics> {

    // fields, getInputMetrics(), getOutputMetrics() excluded

}
```

--------------------------------

### GET /<root>

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/service/rest-api

Retrieve all registered optimization datasets.

```APIDOC
## GET /<root>

### Description
Retrieve all registered optimization datasets.

### Method
GET

### Endpoint
/<root>
```

--------------------------------

### Generate demo data for a planning solution

Source: https://docs.timefold.ai/timefold-solver/latest/domain-modeling/modeling-planning-problems

Initialize a planning solution by creating instances of problem facts and setting planning variables to null.

```java
    public static Timetable generateDemoData(DemoData demoData) {
        List<Timeslot> timeslots = new ArrayList<>(10);
        long nextTimeslotId = 0L;
        timeslots.add(new Timeslot(Long.toString(nextTimeslotId++), DayOfWeek.MONDAY, LocalTime.of(8, 30), LocalTime.of(9, 30)));
        timeslots.add(new Timeslot(Long.toString(nextTimeslotId++), DayOfWeek.MONDAY, LocalTime.of(9, 30), LocalTime.of(10, 30)));
        timeslots.add(new Timeslot(Long.toString(nextTimeslotId++), DayOfWeek.MONDAY, LocalTime.of(10, 30), LocalTime.of(11, 30)));
```

--------------------------------

### POST /<root>

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/service/rest-api

Create a new optimization dataset.

```APIDOC
## POST /<root>

### Description
Create a new optimization dataset.

### Method
POST

### Endpoint
/<root>
```

--------------------------------

### BendableScore JSON representation

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/library/jpa-jaxb-json-integration

Example of a serialized BendableScore object.

```json
{
   "score":"0hard/-200soft"
   ...
}
```

--------------------------------

### UniConstraintStream Example

Source: https://docs.timefold.ai/timefold-solver/latest/constraints-and-score/score-calculation

Demonstrates a basic constraint stream with a cardinality of 1.

```java
    private Constraint doNotAssignAnn(ConstraintFactory factory) {
        return factory.forEach(Shift.class) // Returns UniStream<Shift>.
                ...
    }
```

--------------------------------

### Adjust collector results

Source: https://docs.timefold.ai/timefold-solver/latest/constraints-and-score/score-calculation

Examples of using collectAndThen to transform collector output.

```java
ConstraintCollectors.average(...)
```

```java
ConstraintCollectors.collectAndThen(
    ConstraintCollectors.average(...),
    doubleValue -> (int) Math.round(doubleValue))
```

--------------------------------

### Build PlannerBenchmarkFactory

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/benchmarking-and-tweaking

Initialize the benchmark factory from a FreeMarker XML resource.

```java
        PlannerBenchmarkFactory benchmarkFactory = PlannerBenchmarkFactory.createFromFreemarkerXmlResource(
                "org/acme/vehiclerouting/solverConfig.xml");
        PlannerBenchmark benchmark = benchmarkFactory.buildPlannerBenchmark();
```

--------------------------------

### Polymorphic Score JSON representation

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/library/jpa-jaxb-json-integration

Example of a serialized polymorphic Score object.

```json
{
   "score":{"HardSoftScore":"0hard/-200soft"}
   ...
}
```

--------------------------------

### GET /v<version>/demo-data

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/service/rest-api

Retrieve all available demo dataset ids.

```APIDOC
## GET /v<version>/demo-data

### Description
Retrieve all available demo dataset ids.

### Method
GET

### Endpoint
/v<version>/demo-data
```

--------------------------------

### Configure Allocate to Value from Queue

Source: https://docs.timefold.ai/timefold-solver/latest/optimization-algorithms/construction-heuristics

Provides basic and verbose XML configuration examples for the Allocate to Value from Queue heuristic.

```xml
  <constructionHeuristic>
    <constructionHeuristicType>ALLOCATE_TO_VALUE_FROM_QUEUE</constructionHeuristicType>
  </constructionHeuristic>
```

```xml
  <constructionHeuristic>
    <constructionHeuristicType>ALLOCATE_TO_VALUE_FROM_QUEUE</constructionHeuristicType>
    <entitySorterManner>DESCENDING_IF_AVAILABLE</entitySorterManner>
    <valueSorterManner>ASCENDING_IF_AVAILABLE</valueSorterManner>
  </constructionHeuristic>
```

--------------------------------

### GET /<root>/{id}/score-analysis

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/service/rest-api

Retrieve score analysis of an optimization dataset.

```APIDOC
## GET /<root>/{id}/score-analysis

### Description
Retrieve score analysis of an optimization dataset.

### Method
GET

### Endpoint
/<root>/{id}/score-analysis

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier of the optimization dataset.
```

--------------------------------

### Build and Deploy Model

Source: https://docs.timefold.ai/timefold-solver/latest/deploying-to-platform/guide

Execute the build and deployment process using the required Enterprise Edition flag.

```bash
mvn clean package -Denterprise=true timefold:deploy
```

--------------------------------

### GET /<root>/{id}

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/service/rest-api

Retrieve the (intermediate) result of a dataset optimization run.

```APIDOC
## GET /<root>/{id}

### Description
Retrieve the (intermediate) result of a dataset optimization run.

### Method
GET

### Endpoint
/<root>/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier of the optimization dataset.
```

--------------------------------

### Start Application in Development Mode

Source: https://docs.timefold.ai/timefold-solver/latest/quickstart/service/getting-started

Execute this command to run the model in development mode. Note that performance is reduced in this mode due to disabled JVM optimizations.

```bash
mvn quarkus:dev
```

--------------------------------

### Run Gradle migration tool

Source: https://docs.timefold.ai/timefold-solver/latest/upgrading-timefold-solver/upgrade-from-v1

Execute the OpenRewrite migration recipe for Gradle projects using an init script.

```shell
curl https://raw.githubusercontent.com/TimefoldAI/timefold-solver/refs/tags/v2.5.0/tools/migration/upgrade-timefold.gradle > upgrade-timefold.gradle ; gradle -Dorg.gradle.jvmargs=-Xmx2G --init-script upgrade-timefold.gradle rewriteRun -DtimefoldSolverVersion=2.5.0 ; rm upgrade-timefold.gradle
```

--------------------------------

### Implement Move Selection Filter

Source: https://docs.timefold.ai/timefold-solver/latest/optimization-algorithms/move-selector-reference

Example of a filter that prevents swapping lectures from the same course.

```java
public class DifferentCourseSwapMoveFilter
    implements SelectionFilter<CourseSchedule, SelectorBasedSwapMove<CourseSchedule, Lecture>> {

    @Override
    public boolean accept(ScoreDirector<CourseSchedule> scoreDirector,
            SelectorBasedSwapMove<CourseSchedule, Lecture> move) {
        var leftLecture = (Lecture) move.getLeftEntity();
        var rightLecture = (Lecture) move.getRightEntity();
        return !leftLecture.getCourse().equals(rightLecture.getCourse());
    }

}
```

--------------------------------

### Create SolverConfig Templates for Concurrent Requests

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/library/configuration

Shows how to initialize a template SolverConfig and use a copy constructor to safely create unique configurations for concurrent user requests.

```java
    private SolverConfig template;

    public void init() {
        template = SolverConfig.createFromXmlResource("org/acme/schooltimetabling/solverConfig.xml");
        template.setTerminationConfig(new TerminationConfig());
    }

    // Called concurrently from different threads
    public void userRequest(..., long userInput) {
        SolverConfig solverConfig = new SolverConfig(template); // Copy it
        solverConfig.getTerminationConfig().setMinutesSpentLimit(userInput);
        SolverFactory<Timetable> solverFactory = SolverFactory.create(solverConfig);
        Solver<Timetable> solver = solverFactory.buildSolver();
        ...
```

--------------------------------

### Prepare Test Data

Source: https://docs.timefold.ai/timefold-solver/latest/constraints-and-score/score-calculation

Example of creating test objects for the constraint stream verification.

```Java
        Vehicle vehicleA = new Vehicle("1", 100, LOCATION_1, tomorrow_07_00);
        Visit visit1 = new Visit("2", "John", LOCATION_2, 80, tomorrow_08_00, tomorrow_10_00, Duration.ofMinutes(30L));
        vehicleA.getVisits().add(visit1);
        Visit visit2 = new Visit("3", "Paul", LOCATION_3, 40, tomorrow_08_00, tomorrow_10_00, Duration.ofMinutes(30L));
        vehicleA.getVisits().add(visit2);
```

--------------------------------

### Configure Basic and List Variable Construction Heuristics

Source: https://docs.timefold.ai/timefold-solver/latest/optimization-algorithms/construction-heuristics

Simple XML configuration for basic and list variable placement using queued entity and value placers.

```xml
    <!-- Basic Variable -->
    <constructionHeuristic>
        <queuedEntityPlacer/>
    </constructionHeuristic>
    <!-- List Variable -->
    <constructionHeuristic>
        <queuedValuePlacer>
            <!-- The variableName property identifies the related list variable -->
            <valueSelector variableName="variableName"/>
        </queuedValuePlacer>
    </constructionHeuristic>
```

--------------------------------

### Define a Constraint Stream

Source: https://docs.timefold.ai/timefold-solver/latest/constraints-and-score/score-calculation

Example of a constraint stream that penalizes vehicles exceeding their capacity.

```Java
    Constraint vehicleCapacity(ConstraintFactory factory) {
        return factory.forEach(Vehicle.class)
                .filter(vehicle -> vehicle.getTotalDemand() > vehicle.getCapacity())
                .penalizeLong(HardSoftScore.ONE_HARD,
                        vehicle -> vehicle.getTotalDemand() - vehicle.getCapacity())
                .asConstraint(VEHICLE_CAPACITY);
    }
```

--------------------------------

### Build PlannerBenchmark with datasets

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/benchmarking-and-tweaking

Programmatically pass pre-loaded datasets to the benchmark factory.

```java
        PlannerBenchmark plannerBenchmark = benchmarkFactory.buildPlannerBenchmark(dataset1, dataset2, dataset3);
```

--------------------------------

### Build with Enterprise Edition

Source: https://docs.timefold.ai/timefold-solver/latest/deploying-to-platform/guide

Use this command to activate the enterprise Maven profile and pull in the required Enterprise Edition dependencies.

```bash
mvn clean package -Denterprise=true
```

--------------------------------

### GET /v<version>/demo-data/{demoDataId}

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/service/rest-api

Retrieve the demo dataset with the given identifier.

```APIDOC
## GET /v<version>/demo-data/{demoDataId}

### Description
Retrieve the demo dataset with the given identifier.

### Method
GET

### Endpoint
/v<version>/demo-data/{demoDataId}

### Parameters
#### Path Parameters
- **demoDataId** (string) - Required - The identifier of the demo dataset.
```

--------------------------------

### Configure Custom SolutionFileIO

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/benchmarking-and-tweaking

Reference a custom implementation for non-standard file formats in the benchmark configuration.

```xml
    <problemBenchmarks>
      <solutionFileIOClass>...MyXlsxSolutionFileIO</solutionFileIOClass>
      <inputSolutionFile>dataset01.xslx</inputSolutionFile>
      ...
    </problemBenchmarks>
```

--------------------------------

### Implement CustomerNearbyDistanceMeter

Source: https://docs.timefold.ai/timefold-solver/latest/optimization-algorithms/move-selector-reference

Example implementation of a distance meter handling both Customer and Vehicle types as destinations.

```java
public class CustomerNearbyDistanceMeter implements NearbyDistanceMeter<Customer, LocationAware> {

    public double getNearbyDistance(Customer origin, LocationAware destination) {
        return origin.getDistanceTo(destination);
    }

}
```

--------------------------------

### Configure a basic changeMoveSelector

Source: https://docs.timefold.ai/timefold-solver/latest/optimization-algorithms/move-selector-reference

Example of adding a changeMoveSelector to the Local Search optimization algorithm configuration.

```xml
  <localSearch>
    <changeMoveSelector/>
    ...
  </localSearch>
```

--------------------------------

### Example demo dataset response

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/service/consumer-guide

JSON response structure containing demo dataset metadata.

```json
[
  {
    "id": "BASIC",
    "shortDescription": "A small dataset suitable for quick tests.",
    "longDescription": "10 lessons, 5 timeslots, 2 rooms.",
    "tags": ["small"]
  },
  {
    "id": "COMPLEX_SET",
    "shortDescription": "A larger, more realistic dataset.",
    "longDescription": "200 lessons across multiple rooms and days.",
    "tags": ["large", "realistic"]
  }
]
```

--------------------------------

### PlannerBenchmark buildPlannerBenchmark(Object... datasets)

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/benchmarking-and-tweaking

Method to initialize a benchmark with datasets loaded directly from memory, such as from a database.

```APIDOC
## PlannerBenchmark buildPlannerBenchmark(Object... datasets)

### Description
Builds a planner benchmark instance using datasets loaded in advance, useful for scenarios where data is stored in a database or external repository.

### Parameters
- **datasets** (Object...) - Required - A variable number of dataset objects to be used in the benchmark.
```

--------------------------------

### Integrate Prometheus registry

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/solver-diagnostics

Example of setting up a Prometheus registry and exposing it via an HTTP server.

```java
PrometheusMeterRegistry prometheusRegistry = new PrometheusMeterRegistry(PrometheusConfig.DEFAULT);

try {
    HttpServer server = HttpServer.create(new InetSocketAddress(8080), 0);
    server.createContext("/prometheus", httpExchange -> {
        String response = prometheusRegistry.scrape(); (1)
        httpExchange.sendResponseHeaders(200, response.getBytes().length);
        try (OutputStream os = httpExchange.getResponseBody()) {
            os.write(response.getBytes());
        }
    });

    new Thread(server::start).start();
} catch (IOException e) {
    throw new RuntimeException(e);
}

Metrics.addRegistry(prometheusRegistry);
```

--------------------------------

### Configure SolverFactory

Source: https://docs.timefold.ai/timefold-solver/latest/quickstart/hello-world/hello-world-quickstart

Initializes the solver with solution, entity, and constraint provider classes, including a termination limit.

```java
SolverFactory<Timetable> solverFactory = SolverFactory.create(
    new SolverConfig()
        .withSolutionClass(Timetable.class)
        .withEntityClasses(Lesson.class)
        .withConstraintProviderClass(TimetableConstraintProvider.class)
        // The solver runs only for 5 seconds on this small dataset.
        // It's recommended to run for at least 5 minutes ("5m") otherwise.
        .withTerminationSpentLimit(Duration.ofSeconds(5)));
```

```kotlin
val solverFactory = SolverFactory.create<Timetable>(
    SolverConfig()
        .withSolutionClass(Timetable::class.java)
        .withEntityClasses(Lesson::class.java)
        .withConstraintProviderClass(TimetableConstraintProvider::class.java)
        // The solver runs only for 5 seconds on this small dataset.
        // It's recommended to run for at least 5 minutes ("5m") otherwise.
        .withTerminationSpentLimit(Duration.ofSeconds(5)))
```

--------------------------------

### Solve a planning problem with Solver

Source: https://docs.timefold.ai/timefold-solver/latest/running-timefold-solver/library/library-integration

Demonstrates the basic synchronous solve method. Note that the returned solution instance is a clone of the input.

```java
Timetable problem = ...;
Timetable bestSolution = solver.solve(problem);
```
Tokens:
Raw