Timefold Solver Documentation

Timefold Solver is a lightweight, embeddable constraint satisfaction engine designed to optimize planning problems. It helps organizations manage constrained resources (such as employees, assets, time, and money) to achieve specific goals efficiently.

Common use cases include:

• Vehicle routing
• Employee scheduling
• Rostering
• Bin packing
• Equipment scheduling

Timefold Solver uses plain old JavaBeans (POJOs) for input and output data (the planning problem and the best solution), making it compatible with most Java technologies.

For streamlined development, use the first-class framework integrations:

• Quarkus
• Spring Boot

For other technologies, you can use standard Java annotations on your domain POJOs to handle data loading and exposure.

Timefold Solver Enterprise is a commercial, non-open-source product that includes advanced features for scaling to large datasets and improving user trust. Key Enterprise-only features include:

• Score Analysis & Constraint Profiling: Deep insights into how constraints affect the score.
• Advanced Optimization Algorithms: Nearby selection, Multistage moves, and Multithreaded solving.
• Scalability & Performance: Partitioned search and general performance improvements.
• API Extensions: Recommendation API and Throttling best solution events.

A MoveSelector is a component whose primary function is to create an Iterator<Move> when requested. Optimization algorithms iterate through a subset of these moves to explore the solution space.

Note: Move Selectors are not considered a public API. While they are supported in Timefold Solver 2.0, they will only receive critical bug fixes and no new features. Users are encouraged to migrate to the Neighborhoods API.

<localSearch>
  <changeMoveSelector/>
  ...
</localSearch>

Constraint Streams are a functional programming API for incremental score calculation in Timefold Solver. Unlike the standard Java Streams API, which must recalculate the entire stream from scratch when a single variable changes, Constraint Streams automatically detect changes and only recalculate the minimum necessary portion of the problem. This provides significant performance benefits for large-scale optimization problems.

An example of a constraint using Constraint Streams:

private Constraint doNotAssignAnn(ConstraintFactory factory) {
    return factory.forEach(Shift.class)
            .filter(Shift::isEmployeeAnn)
            .penalize(HardSoftScore.ONE_SOFT)
            .asConstraint("Don't assign Ann");
}

Model enrichment is the process of adding extra information to the SolverModel before the solving process begins. When a planning problem is submitted via the REST API, the raw model might be incomplete. Enrichers allow you to augment this model with derived fields, external lookups, or pre-computed values that are necessary for constraints to function correctly.

Common use cases include:

• External Lookups: Fetching data from databases or external services (e.g., travel times, holiday calendars, price lists).
• Pinning Entities: Marking entities that represent work already completed or committed.
• Pre-computing Values: Calculating expensive derived values (e.g., distance matrices, compatibility scores) once, so that constraints can access them instantly during solving.

A Move is a change (or set of changes) that transitions a solution from state A to state B. The resulting solution B is called a neighbor of solution A.

Key characteristics of a Move:

• It must not change the problem facts.
• It must not add or remove entities.
• It can affect multiple entities simultaneously.
• All optimization algorithms use Moves to navigate the search space.

Effective optimization relies on Move selection: the ability to efficiently create moves and identify the most promising subset of moves to evaluate.

A construction heuristic is used to build a reasonably good initial solution in a finite amount of time. While the solution might not always be feasible, it provides a fast starting point for metaheuristics (like Local Search) to refine.

Construction heuristics terminate automatically, so you typically do not need to configure a specific Termination for this phase.

In Timefold Solver, a Value Range Provider defines the set of possible values that can be assigned to a planning variable.

To connect a planning variable to its available values, you must:

1. Annotate the planning variable field (e.g., timeslot) with @PlanningVariable.
2. Annotate the field containing the collection of possible values (e.g., timeslots) with @ValueRangeProvider.

The solver matches the two by ensuring the type of the planning variable matches the type of the elements returned by the value range provider. For example, if a Lesson has a timeslot field of type Timeslot, the timeslots field must be a collection of Timeslot instances.

Common examples include fields for rooms or timeslots in scheduling problems.