Timefold Solver

https://docs.timefold.ai/timefold-solver/1.x
Admin
Timefold Solver is a lightweight, embeddable constraint satisfaction engine that optimizes planning...
Tokens:374,390
Snippets:2,443
Trust Score:8.5
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install Java with Sdkman

Source: https://docs.timefold.ai/timefold-solver/1.x/quickstart/quarkus/quarkus-quickstart?platform=1

Commands to install Java using Sdkman, as a prerequisite for the quickstart.

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

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

### Clone the Timefold quickstarts repository

Source: https://docs.timefold.ai/timefold-solver/1.x/quickstart/quarkus/quarkus-quickstart?platform=1

Clones the Timefold quickstarts repository to access the completed example. The solution is in the 'java' directory.

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

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

### Start Freemarker template for matrix benchmarking

Source: https://docs.timefold.ai/timefold-solver/1.x/using-timefold-solver/benchmarking-and-tweaking

Starts a Freemarker template for matrix benchmarking, which benchmarks combinations of value sets (e.g., entityTabuSize values combined with acceptedCountLimit values). The template reduces verbosity of such benchmark configurations.

```xml
<plannerBenchmark xmlns="https://timefold.ai/xsd/benchmark" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://timefold.ai/xsd/benchmark https://timefold.ai/xsd/benchmark/benchmark.xsd">
  ...
  <inheritedSolverBenchmark>
    ...
  </inheritedSolverBenchmark>
```

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

### Inject teacherSolver and roomSolver with domain classes (Kotlin)

Source: https://docs.timefold.ai/timefold-solver/1.x/integration/integration?platform=1

Kotlin version of the Java example, with nullable SolverManager properties.

```kotlin
@PlanningSolution
class TeacherToLessonSchedule {
    ...
}

@PlanningEntity
class Teacher {
    ...
}

@RestController
@RequestMapping("/path")
class Resource {

    @Autowired
    @Qualifier("teacherSolver")
    var teacherToLessonScheduleSolverManager: SolverManager<TeacherToLessonSchedule, String>?

    @Autowired
    @Qualifier("roomSolver")
    var lessonToRoomTimeslotSolverManager: SolverManager<Timetable, String>?

    ...
}

```

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

### Create TimetableApp.java with main() and generateDemoData()

Source: https://docs.timefold.ai/timefold-solver/1.x/quickstart/hello-world/hello-world-quickstart?platform=1

Main application class for the school timetabling quickstart. It creates a SolverFactory with a SolverConfig that uses Timetable as the solution class, Lesson as the entity class, and TimetableConstraintProvider as the constraint provider. The solver termination is set to 5 seconds, with a comment recommending at least 5 minutes for real datasets. The main method loads demo data, solves it, and prints the solution.

```java
package org.acme.schooltimetabling;

import java.time.DayOfWeek;
import java.time.Duration;
import java.time.LocalTime;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.stream.Collectors;

import ai.timefold.solver.core.api.solver.Solver;
import ai.timefold.solver.core.api.solver.SolverFactory;
import ai.timefold.solver.core.config.solver.SolverConfig;
import org.acme.schooltimetabling.domain.Lesson;
import org.acme.schooltimetabling.domain.Room;
import org.acme.schooltimetabling.domain.Timeslot;
import org.acme.schooltimetabling.domain.Timetable;
import org.acme.schooltimetabling.solver.TimetableConstraintProvider;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class TimetableApp {

    private static final Logger LOGGER = LoggerFactory.getLogger(TimetableApp.class);

    public static void main(String[] args) {
        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)));

        // Load the problem
        Timetable problem = generateDemoData();

        // Solve the problem
        Solver<Timetable> solver = solverFactory.buildSolver();
        Timetable solution = solver.solve(problem);

        // Visualize the solution
        printTimetable(solution);
    }

    public static Timetable generateDemoData() {
        List<Timeslot> timeslots = new ArrayList<>(10);
        timeslots.add(new Timeslot(DayOfWeek.MONDAY, LocalTime.of(8, 30), LocalTime.of(9, 30)));
        timeslots.add(new Timeslot(DayOfWeek.MONDAY, LocalTime.of(9, 30), LocalTime.of(10, 30)));
        timeslots.add(new Timeslot(DayOfWeek.MONDAY, LocalTime.of(10, 30), LocalTime.of(11, 30)));
        timeslots.add(new Timeslot(DayOfWeek.MONDAY, LocalTime.of(13, 30), LocalTime.of(14, 30)));
        timeslots.add(new Timeslot(DayOfWeek.MONDAY, LocalTime.of(14, 30), LocalTime.of(15, 30)));

        timeslots.add(new Timeslot(DayOfWeek.TUESDAY, LocalTime.of(8, 30), LocalTime.of(9, 30)));
        timeslots.add(new Timeslot(DayOfWeek.TUESDAY, LocalTime.of(9, 30), LocalTime.of(10, 30)));
        timeslots.add(new Timeslot(DayOfWeek.TUESDAY, LocalTime.of(10, 30), LocalTime.of(11, 30)));
        timeslots.add(new Timeslot(DayOfWeek.TUESDAY, LocalTime.of(13, 30), LocalTime.of(14, 30)));
        timeslots.add(new Timeslot(DayOfWeek.TUESDAY, LocalTime.of(14, 30), LocalTime.of(15, 30)));

        List<Room> rooms = new ArrayList<>(3);
        rooms.add(new Room("Room A"));
        rooms.add(new Room("Room B"));
        rooms.add(new Room("Room C"));

```

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

### Valid alignmentKey example with Leader and Follower entities

Source: https://docs.timefold.ai/timefold-solver/1.x/using-timefold-solver/modeling-planning-problems?platform=1

Shows a valid use of alignmentKey where the leader field is not a variable and entities with the same leader get the same value.

```java
@PlanningEntity
public class Leader {
    @PlanningVariable
    Integer value;
    // ...
}

@PlanningEntity
public class Follower {
    Leader leader;

    @ShadowVariable(supplierName="valueSupplier")
    Integer value;

    @ShadowSources(value = {"leader.value"}, alignmentKey = "leader")
    public Integer valueSupplier() {
      return leader.value;
    }
}
```

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

### Create and run a PlannerBenchmark from XML resource

Source: https://docs.timefold.ai/timefold-solver/1.x/using-timefold-solver/benchmarking-and-tweaking

Builds a PlannerBenchmark from a benchmark configuration XML classpath resource and runs it, opening the benchmark report in the browser.

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

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

### Example of incorrect equals/hashCode causing flattenLast issue

Source: https://docs.timefold.ai/timefold-solver/1.x/upgrading-timefold-solver/upgrade-to-latest-version

Shows a record with `equals` and `hashCode` based only on `start`, which can cause `flattenLast` to reuse an old interval instance, leading to score corruption when downstream constraints check the `end` property.

```java
record IntervalEqualByStart(int start, int end) {
    @Override
    public boolean equals(Object obj) {
        if (obj instanceof Interval interval) {
            return start == interval.start;
        }
        return false;
    }

    @Override
    public int hashCode() {
        return start;
    }
}

factory.forEach(Shift.class)
    .map(shift -> new IntervalEqualByStart(shift.getStart(), shift.getEnd()))
    .flattenLast(interval -> List.of(interval))
    // "end" is not considered in IntervalEqualByStart,
    // so IntervalEqualByStart(1, 2) and IntervalEqualByStart(1, 3)
    // are equals to one another, causing flattenLast to reuse
    // IntervalEqualByStart(1, 2) (which is not accepted by this filter)
    // instead of using IntervalEqualByStart(1, 3) (which would be accepted by this filter)
    // if shift.getEnd() was changed from 2 to 3.
    .filter(interval -> interval.end() > 2)
    // ...
```

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

### Run a simple benchmark with PlannerBenchmarkFactory

Source: https://docs.timefold.ai/timefold-solver/1.x/using-timefold-solver/benchmarking-and-tweaking

Run a simple benchmark with three datasets. Generates a report in local/benchmarkReport and opens it in the browser. The solver configuration must include a termination to limit each dataset's runtime. Pass a File parameter to createFromSolverConfigXmlResource() to change the benchmark directory.

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

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

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

### Testing a shadow variable with SolutionManager.updateShadowVariables

Source: https://docs.timefold.ai/timefold-solver/1.x/using-timefold-solver/modeling-planning-problems?docs=1

These examples show a basic shadow variable setup with a @ShadowVariable supplier and two unit tests. The first test passes the solution class and entity to SolutionManager.updateShadowVariables(Class, Object...), while the second passes a solution instance. Note that the class-based overload fails for models using custom variable listeners; the instance-based overload avoids that limitation.

```java
public class Schedule {

     @PlanningEntityCollectionProperty
     private List<Job> jobs;
     ...
}
```

```java
public class Job {

    public Job(LocalDate startDate, int durationInDays) {
        ...
    }

    @PlanningVariable
    private LocalDate startDate;

    private int durationInDays;

    @ShadowVariable(supplierName="endDateSupplier")
    private LocalDate endDate;

    @ShadowSources("startDate")
    public LocalDate endDateSupplier() {
        if (startDate == null) {
            return null;
        } else {
            return startDate.plusDays(durationInDays);
        }
    }
}
```

```java
    @Test
    void updateShadowVariables() {
        var job = new Job(LocalDate.now(), 10);
        SolutionManager.updateShadowVariables(Schedule.class, job);
        assertThat(job.getEndDate()).isEqualTo(LocalDate.now().plusDays(10));
    }
```

```java
    @Test
    void updateShadowVariables() {
        var solution = new Schedule();
        var job = new Job(LocalDate.now(), 10);
        solution.setJobs(List.of(job));
        SolutionManager.updateShadowVariables(solution);
        assertThat(job.getEndDate()).isEqualTo(LocalDate.now().plusDays(10));
    }
```

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

### Inject teacherSolver and roomSolver with domain classes (Java)

Source: https://docs.timefold.ai/timefold-solver/1.x/integration/integration?platform=1

Java example combining @PlanningSolution and @PlanningEntity classes with injected solver managers using @Qualifier for teacherSolver and roomSolver.

```java
@PlanningSolution
public class TeacherToLessonSchedule {
    ...
}

@PlanningEntity
public class Teacher {
    ...
}

@RestController
@RequestMapping("/path")
public class Resource {

    @Autowired
    @Qualifier("teacherSolver")
    SolverManager<TeacherToLessonSchedule, String> teacherToLessonScheduleSolverManager;

    @Autowired
    @Qualifier("roomSolver")
    SolverManager<Timetable, String> lessonToRoomTimeslotSolverManager;

    ...
}

```

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

### UniConstraintStream example

Source: https://docs.timefold.ai/timefold-solver/1.x/constraints-and-score/score-calculation?platform=1

Java example showing a constraint stream with cardinality 1, returning a UniConstraintStream<Shift>.

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

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

### Example output of score summary

Source: https://docs.timefold.ai/timefold-solver/1.x/constraints-and-score/understanding-the-score?docs=1

Example output from scoreAnalysis.summarize() showing a constraint match for minimizeTravelTime. This is for debugging only.

```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.])
            ...
        ...
```

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

### Simple First Fit configuration

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

Configures the construction heuristic phase with the FIRST_FIT type. This is the basic setup for using the First Fit algorithm.

```xml
  <constructionHeuristic>
    <constructionHeuristicType>FIRST_FIT</constructionHeuristicType>
  </constructionHeuristic>
```

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

### Example XML output for marshalled score

Source: https://docs.timefold.ai/timefold-solver/1.x/integration/integration

Example XML output produced when a HardSoftScore is marshalled with the JAXB adapter.

```xml
<vehicleRoutePlan>
   ...
   <score>0hard/-200soft</score>
</vehicleRoutePlan>
```

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

### EnvironmentMode change from REPRODUCIBLE to NO_ASSERT

Source: https://docs.timefold.ai/timefold-solver/1.x/upgrading-timefold-solver/upgrade-to-latest-version

Before and after examples for the EnvironmentMode enum change. REPRODUCIBLE is replaced by NO_ASSERT. The after example shows the new mode to restore unasserted behavior.

```java
var solverConfig = new SolverConfig()
    .withEnvironmentMode(EnvironmentMode.REPRODUCIBLE);
    ...
```

```java
var solverConfig = new SolverConfig()
    .withEnvironmentMode(EnvironmentMode.NO_ASSERT);
    ...
```

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

### Create SolverFactory from XML resource (Java)

Source: https://docs.timefold.ai/timefold-solver/1.x/using-timefold-solver/configuration?platform=1

Builds a Solver instance by creating a SolverFactory from a solver configuration XML file located as a classpath resource. The file is typically at $PROJECT_DIR/src/main/resources/org/acme/schooltimetabling/solverConfig.xml. Alternatively, use SolverFactory.createFromXmlFile() with a File, but a classpath resource is recommended for portability.

```java
       SolverFactory<Timetable> solverFactory = SolverFactory.createFromXmlResource(
               "org/acme/schooltimetabling/solverConfig.xml");
       Solver<Timetable> solver = solverFactory.buildSolver();
```

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

### Example score summary output for vehicle routing

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

Example output from summarize() for a vehicle routing problem. It shows a constraint match for minimizeTravelTime with a justification and indicted objects. The output is for debugging only; use score analysis instead.

```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
        ...
```

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

### Build benchmark with PlannerBenchmarkFactory

Source: https://docs.timefold.ai/timefold-solver/1.x/using-timefold-solver/benchmarking-and-tweaking

Builds a benchmark from a FreeMarker XML resource using `PlannerBenchmarkFactory`. The `createFromFreemarkerXmlResource` method loads the template and `buildPlannerBenchmark` creates the benchmark instance.

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

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

### Example debug log output showing steps

Source: https://docs.timefold.ai/timefold-solver/1.x/quickstart/quarkus/quarkus-quickstart?platform=1

Shows the debug log output that displays each step, including time spent, score, selected move count, and the picked move.

```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}]).
...
```

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

### Constraint profiling report example at INFO, DEBUG, and TRACE levels

Source: https://docs.timefold.ai/timefold-solver/1.x/enterprise-edition/enterprise-edition?platform=1

Example of the constraint profiling report output at INFO, DEBUG, and TRACE levels. The output is a Markdown table showing the time spent per constraint, node breakdown, and lifecycle breakdown.

```text
INFO:  # Constraint Profiling Summary
|                                                    | Time Spent | Of Total |
| :------------------------------------------------- | ---------: | -------: |
| 2: Teacher time efficiency                         |     6.19 s |  23.15 % |
| 6: Room conflict                                   |     4.17 s |  15.61 % |
| 4: Student group conflict                          |     3.76 s |  14.07 % |
| 5: Teacher conflict                                |     3.41 s |  12.76 % |
| 1: Student group subject variety                   |     3.25 s |  12.14 % |
| 3: Teacher room stability                          |     3.25 s |  12.14 % |
| Work shared by 1, 2, 3, 4, 5, 6                    |     2.71 s |  10.12 % |

DEBUG: ## Constraint Profiling Node Breakdown
| 2: Teacher time efficiency                         | Time Spent | Of Total |
| :------------------------------------------------- | ---------: | -------: |
| JOIN Node 26                                       |     1.56 s |  25.20 % |
| JOIN Left Input 6                                  |     1.28 s |  20.69 % |
| JOIN Right Input 7                                 |     1.09 s |  17.55 % |
| FILTER 5                                           |     1.83 s |  29.49 % |
| SCORING 4                                          |     0.44 s |   7.06 % |

 - JOIN Node 26 defined at location org.acme.schooltimetabling.solver.TimetableConstraintProvider#teacherTimeEfficiency:77
 - JOIN Left Input 6 defined at location org.acme.schooltimetabling.solver.TimetableConstraintProvider#teacherTimeEfficiency:77
 - JOIN Right Input 7 defined at location org.acme.schooltimetabling.solver.TimetableConstraintProvider#teacherTimeEfficiency:77
 - FILTER 5 defined at location org.acme.schooltimetabling.solver.TimetableConstraintProvider#teacherTimeEfficiency:79
 - SCORING 4 defined at location org.acme.schooltimetabling.solver.TimetableConstraintProvider#teacherTimeEfficiency:84

...

TRACE: ## Constraint Profiling Lifecycle Breakdown
| 2: Teacher time efficiency               |  INSERT  |  UPDATE  |  RETRACT  |
| :--------------------------------------- | -------: | -------: | --------: |
| JOIN                                     |  13.12 % |  75.64 % |   11.23 % |
| FILTER                                   |  23.69 % |  50.45 % |   25.86 % |
| SCORING                                  |  13.10 % |  16.12 % |   70.78 % |

...
```

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

### Solver configuration XML example

Source: https://docs.timefold.ai/timefold-solver/1.x/using-timefold-solver/configuration?platform=1

Shows the structure of a solver configuration XML file. It defines the model with solutionClass and entityClass, the score function with a constraintProviderClass, and optionally configures optimization algorithms with termination, constructionHeuristic, and localSearch elements.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<solver xmlns="https://timefold.ai/xsd/solver" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://timefold.ai/xsd/solver https://timefold.ai/xsd/solver/solver.xsd">
  <!-- Define the model -->
  <solutionClass>org.acme.schooltimetabling.domain.Timetable</solutionClass>
  <entityClass>org.acme.schooltimetabling.domain.Lesson</entityClass>

  <!-- Define the score function -->
  <scoreDirectorFactory>
    <constraintProviderClass>org.acme.schooltimetabling.solver.TimetableConstraintProvider</constraintProviderClass>
  </scoreDirectorFactory>

  <!-- Configure the optimization algorithms (optional) -->
  <termination>
    ...
  </termination>
  <constructionHeuristic>
    ...
  </constructionHeuristic>
  <localSearch>
    ...
  </localSearch>
</solver>
```

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

### toConsecutiveSequences() collector example in Java

Source: https://docs.timefold.ai/timefold-solver/1.x/constraints-and-score/score-calculation?platform=1

Groups matches by home team and creates consecutive sequences based on round ID. Flattens sequences and filters those with count >= MAX_CONSECUTIVE_MATCHES, penalizing by the count. The example shows a full constraint for penalizing 4 or more consecutive home matches.

```java
Constraint multipleConsecutiveHomeMatches(ConstraintFactory constraintFactory) {
        return constraintFactory.forEach(Match.class)
                .groupBy(match -> Match::getHomeTeam,
                        ConstraintCollectors.toConsecutiveSequences(Match::getRoundId))
                .flattenLast(SequenceChain::getConsecutiveSequences)
                .filter((team, matches) -> matches.getCount() >= MAX_CONSECUTIVE_MATCHES)
                .penalize(HardSoftScore.ONE_HARD, (team, matches) -> matches.getCount())
                .asConstraint("4 or more consecutive home matches");
}
```

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

### ConstraintCollectors.average()

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

Documentation for the `average()` collector from ConstraintCollectors, including its variants and usage example.

```APIDOC
## `average()` collector

### Description
Calculates the average of a particular property of all elements per group using the `ConstraintCollectors.average(…)` collector. The average is collected as a `double`, and the average of no elements is `null`.

### Method
`ConstraintCollectors.average(…)`

### Parameters
- **groupBy** (Function) - Required - The property to group by.
- **average** (Function) - Required - The property to average.

### Variants
- `averageLong()` - collects a `long` value instead of an `int` value.
- `averageBigDecimal()` - collects a `java.math.BigDecimal` value instead of an `int` value, resulting in a `BigDecimal` average.
- `averageBigInteger()` - collects a `java.math.BigInteger` value instead of an `int` value, resulting in a `BigDecimal` average.
- `averageDuration()` - collects a `java.time.Duration` value instead of an `int` value, resulting in a `Duration` average.

### Example
```java
private Constraint averageServiceDuration(ConstraintFactory constraintFactory) {
    return constraintFactory.forEach(Visit.class)
            .groupBy(Visit::getVehicle, average(Visit::getServiceDuration))
            .penalize(HardSoftScore.ONE_SOFT,
                    (vehicle, averageServiceDuration) -> (int) averageServiceDuration)
            .asConstraint("averageServiceDuration");
}
```
```

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

### Create Lesson.kt planning entity

Source: https://docs.timefold.ai/timefold-solver/1.x/quickstart/quarkus/quarkus-quickstart?platform=1

Kotlin implementation of the Lesson class as a data class with @PlanningEntity and @PlanningVariable annotations. The timeslot and room fields are nullable planning variables. Includes a no-arg constructor required for Timefold.

```kotlin
package org.acme.schooltimetabling.domain

import ai.timefold.solver.core.api.domain.entity.PlanningEntity
import ai.timefold.solver.core.api.domain.lookup.PlanningId
import ai.timefold.solver.core.api.domain.variable.PlanningVariable

@PlanningEntity
data class Lesson (
    @PlanningId
    val id: String,
    val subject: String,
    val teacher: String,
    val studentGroup: String) {

    @PlanningVariable
    var timeslot: Timeslot? = null

    @PlanningVariable
    var room: Room? = null

    // No-arg constructor required for Timefold
    constructor() : this("0", "", "", "")

    override fun toString(): String = "$subject($id)"

}
```

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

### Configure Maven credentials in .m2/settings.xml

Source: https://docs.timefold.ai/timefold-solver/1.x/enterprise-edition/enterprise-edition?docs=1

Create .m2/settings.xml in your home directory with this content to provide the credentials obtained from a Timefold representative. Replace 'my_username' and 'my_password' with your actual credentials.

```xml
<settings>
  ...
  <servers>
    <server>
      <!-- Replace "my_username" and "my_password" with credentials obtained from a Timefold representative. -->
      <id>timefold-solver-enterprise</id>
      <username>my_username</username>
      <password>my_password</password>
    </server>
  </servers>
  ...
</settings>
```

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

### ConstraintCollectors.sum()

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

Documentation for the `sum()` collector from ConstraintCollectors, including its variants and usage example.

```APIDOC
## `sum()` collector

### Description
Sums the values of a particular property of all elements per group using the `ConstraintCollectors.sum(…)` collector. The sum is collected in an `int`.

### Method
`ConstraintCollectors.sum(…)`

### Parameters
- **groupBy** (Function) - Required - The property to group by.
- **sum** (Function) - Required - The property to sum.

### Variants
- `sumLong()` - collects a `long` value instead of an `int` value.
- `sumBigDecimal()` - collects a `java.math.BigDecimal` value instead of an `int` value.
- `sumBigInteger()` - collects a `java.math.BigInteger` value instead of an `int` value.
- `sumDuration()` - collects a `java.time.Duration` value instead of an `int` value.
- `sumPeriod()` - collects a `java.time.Period` value instead of an `int` value.
- a generic `sum()` variant for summing up custom types

### Example
```java
private Constraint totalServiceDuration(ConstraintFactory constraintFactory) {
    return constraintFactory.forEach(Visit.class)
            .groupBy(Visit::getVehicle, sum(Visit::getServiceDuration))
            .penalize(HardSoftScore.ONE_SOFT,
                    (vehicle, totalServiceDuration) -> totalServiceDuration)
            .asConstraint("totalServiceDuration");
}
```
```

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

### Compare two solutions with ScoreAnalysis.diff()

Source: https://docs.timefold.ai/timefold-solver/1.x/constraints-and-score/understanding-the-score?docs=1

Use SolutionManager.analyze() to get ScoreAnalysis for two solutions, then call diff() to get a ScoreAnalysis containing only constraints whose matches changed. The diff is like a subtraction: second minus first. Constraint matches added in the second solution appear as negative, removed ones as positive.

```java
ScoreAnalysis<HardSoftScore>  firstAnalysis = solutionManager.analyze(firstSolution);
ScoreAnalysis<HardSoftScore> secondAnalysis = solutionManager.analyze(secondSolution);
ScoreAnalysis<HardSoftScore>           diff = firstAnalysis.diff(secondSolution);

// Score difference only carries the constraints whose matches changed from first to second solution.
diff.constraintMap().forEach((constraintRef, constraintAnalysis) -> {
   String constraintId = constraintRef.constraintId();
   HardSoftScore scoreDiff = constraintAnalysis.score();
   // Matches only include constraint matches that:
   //   - the second solution either added to or removed from the first solution.
   //   - had their score changed.
   // Two matches are considered equal if their justification objects are equal.
   constraintAnalysis.matches().forEach(matchAnalysis -> {
       ...
   });
});
```

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

### Allocate From Pool Simple Configuration

Source: https://docs.timefold.ai/timefold-solver/1.x/optimization-algorithms/construction-heuristics?platform=1

Minimal configuration to enable the Allocate From Pool construction heuristic in OptaPlanner XML solver configuration.

```xml
  <constructionHeuristic>
    <constructionHeuristicType>ALLOCATE_FROM_POOL</constructionHeuristicType>
  </constructionHeuristic>

```

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

### Inject teacherSolver and roomSolver in Kotlin

Source: https://docs.timefold.ai/timefold-solver/1.x/integration/integration?platform=1

Kotlin example showing planning solution and entity classes, then injecting two SolverManager instances via constructor injection with @Named for teacherSolver and roomSolver.

```kotlin
@PlanningSolution
class TeacherToLessonSchedule {
    ...
}

@PlanningEntity
class Teacher {
    ...
}

@Path("path")
class Resource {

    private final var teacherToLessonScheduleSolverManager: SolverManager<TeacherToLessonSchedule, String>?
    private final var lessonToRoomTimeslotSolverManager: SolverManager<Timetable, String>?

    @Inject
    constructor(
        @Named("teacherSolver") teacherToLessonScheduleSolverManager: SolverManager<TeacherToLessonSchedule, String>,
        @Named("roomSolver") lessonToRoomTimeslotSolverManager: SolverManager<Timetable, String>
    ) {
        this.teacherToLessonScheduleSolverManager = teacherToLessonScheduleSolverManager
        this.lessonToRoomTimeslotSolverManager = lessonToRoomTimeslotSolverManager
    }

    ...
}
```

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

### teachersSolverConfig.xml for teacher assignment step

Source: https://docs.timefold.ai/timefold-solver/1.x/integration/integration

XML solver configuration for the teacher-to-lesson optimization step in the two-step example.

```xml
<solver xmlns="https://timefold.ai/xsd/solver" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://timefold.ai/xsd/solver https://timefold.ai/xsd/solver/solver.xsd">
  <solutionClass>org.acme.schooltimetabling.domain.TeacherToLessonSchedule</solutionClass>
  <entityClass>org.acme.schooltimetabling.domain.Teacher</entityClass>
</solver>

```

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

### Inject multiple solver managers with XML configs in Java

Source: https://docs.timefold.ai/timefold-solver/1.x/integration/integration

In Java, define the planning solution and entity classes needed by the teacher and room solvers, then inject each SolverManager using the corresponding @Qualifier. teacherSolver uses TeacherToLessonSchedule and Teacher, roomSolver uses Timetable and Lesson.

```java
@PlanningSolution
public class TeacherToLessonSchedule {
    ...
}

@PlanningEntity
public class Teacher {
    ...
}

@RestController
@RequestMapping("/path")
public class Resource {

    @Autowired
    @Qualifier("teacherSolver")
    SolverManager<TeacherToLessonSchedule, String> teacherToLessonScheduleSolverManager;

    @Autowired
    @Qualifier("roomSolver")
    SolverManager<Timetable, String> lessonToRoomTimeslotSolverManager;

    ...
}
```

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

### Run application in dev mode with Gradle

Source: https://docs.timefold.ai/timefold-solver/1.x/quickstart/quarkus/quarkus-quickstart?platform=1

Starts the Quarkus application in dev mode using Gradle.

```shell
$ gradle --console=plain quarkusDev
```
Tokens:
Raw