Docs
  • Solver
  • Models
    • Field Service Routing
    • Employee Shift Scheduling
  • Platform
Try models
  • Timefold Solver 0.8.42
  • Examples overview
  • Edit this Page
  • 0.8.x
    • latest
    • 0.8.x

Timefold Solver 0.8.42

    • Timefold introduction
    • Quickstart
      • Overview
      • Hello world Java quick start
      • Quarkus Java quick start
      • Spring Boot Java quick start
    • Use cases and examples
    • Timefold configuration
    • Score calculation
    • Constraint streams score calculation
    • Shadow variable
    • Optimization algorithms
    • Move and neighborhood selection
    • Exhaustive search
    • Construction heuristics
    • Local search
    • Evolutionary algorithms
    • Hyperheuristics
    • Partitioned search
    • Benchmarking and tweaking
    • Repeated planning
    • Integration
    • Design patterns
    • Development
    • Release Notes

Examples overview

Timefold has several examples. In this manual we explain mainly using the n queens example and cloud balancing example. So it is advisable to read at least those sections.

Some of the examples solve problems that are presented in academic contests. The Contest column in the following table lists the contests. It also identifies an example as being either realistic or unrealistic for the purpose of a contest. A realistic contest is an official, independent contest:

  • that clearly defines a real-world use case.

  • with real-world constraints.

  • with multiple, real-world datasets.

  • that expects reproducible results within a specific time limit on specific hardware.

  • that has had serious participation from the academic and/or enterprise Operations Research community.

Realistic contests provide an objective comparison of Timefold with competitive software and academic research.

The source code of all these examples is available in the distribution zip under examples/sources and also in git under timefold/timefold-solver-examples.

Table 1. Examples overview
Example Domain Size Contest Special features used

N queens

  • 1 entity class

    • 1 variable

  • Entity ⇐ 256

  • Value ⇐ 256

  • Search space ⇐ 10^616

  • Pointless (cheatable)

None

Cloud balancing

  • 1 entity class

    • 1 variable

  • Entity ⇐ 2400

  • Value ⇐ 800

  • Search space ⇐ 10^6967

  • No

  • Defined by us

  • Real-time planning

Traveling salesman

  • 1 entity class

    • 1 chained variable

  • Entity ⇐ 980

  • Value ⇐ 980

  • Search space ⇐ 10^2504

  • Unrealistic

  • TSP web

  • Real-time planning

Tennis club scheduling

  • 1 entity class

    • 1 variable

  • Entity ⇐ 72

  • Value ⇐ 7

  • Search space ⇐ 10^60

  • No

  • Defined by us

  • Fairness score constraints

  • Pinned entities

Meeting scheduling

  • 1 entity class

    • 2 variables

  • Entity ⇐ 10

  • Value ⇐ 320 and ⇐ 5

  • Search space ⇐ 10^320

  • No

  • Defined by us

  • TimeGrain pattern

Course timetabling

  • 1 entity class

    • 2 variables

  • Entity ⇐ 434

  • Value ⇐ 25 and ⇐ 20

  • Search space ⇐ 10^1171

  • Realistic

  • ITC 2007 track 3

  • Pinned entities

Machine reassignment

  • 1 entity class

    • 1 variable

  • Entity ⇐ 50000

  • Value ⇐ 5000

  • Search space ⇐ 10^184948

  • Nearly realistic

  • ROADEF 2012

  • Real-time planning

Vehicle routing

  • 1 entity class

    • 1 list variable

  • 1 shadow entity class

    • 3 automatic shadow variable

  • Entity ⇐ 55

  • Value ⇐ 2750

  • Search space ⇐ 10^8380

  • Unrealistic

  • VRP web

  • Shadow variable

  • Real-time planning

  • Nearby selection

  • Real road distances

Vehicle routing with time windows

  • All of Vehicle routing

  • 1 shadow variable

  • Entity ⇐ 55

  • Value ⇐ 2750

  • Search space ⇐ 10^8380

  • Unrealistic

  • VRP web

  • All of Vehicle routing

  • Custom VariableListener

Project job scheduling

  • 1 entity class

    • 2 variables

    • 1 shadow variable

  • Entity ⇐ 640

  • Value ⇐ ? and ⇐ ?

  • Search space ⇐ ?

  • Nearly realistic

  • MISTA 2013

  • Bendable score

  • Custom VariableListener

  • ValueRangeFactory

Hospital bed planning

  • 1 entity class

    • 1 nullable variable

  • Entity ⇐ 2750

  • Value ⇐ 471

  • Search space ⇐ 10^6851

  • Unrealistic

  • Kaho PAS

  • Overconstrained planning

Task assigning

  • 1 entity class

    • 1 list variable

  • 1 shadow entity class

    • 1 automatic shadow variable

    • 1 shadow variable

  • Entity ⇐ 20

  • Value ⇐ 500

  • Search space ⇐ 10^1168

  • No

  • Defined by us

  • Bendable score

  • Chained through time pattern

  • Custom VariableListener

  • Continuous planning

  • Real-time planning

Exam timetabling

  • 2 entity classes (same hierarchy)

    • 2 variables

  • Entity ⇐ 1096

  • Value ⇐ 80 and ⇐ 49

  • Search space ⇐ 10^3374

  • Realistic

  • ITC 2007 track 1

  • Custom VariableListener

Nurse rostering

  • 1 entity class

    • 1 variable

  • Entity ⇐ 752

  • Value ⇐ 50

  • Search space ⇐ 10^1277

  • Realistic

  • INRC 2010

  • Continuous planning

  • Real-time planning

Traveling tournament

  • 1 entity class

    • 1 variable

  • Entity ⇐ 1560

  • Value ⇐ 78

  • Search space ⇐ 10^2301

  • Unrealistic

  • TTP

  • Custom MoveListFactory

Conference scheduling

  • 1 entity class

    • 2 variables

  • Entity ⇐ 216

  • Value ⇐ 18 and ⇐ 20

  • Search space ⇐ 10^552

  • No

  • Defined by us

Flight crew scheduling

  • 1 entity class

    • 1 variable

  • 1 shadow entity class

    • 1 automatic shadow variable

  • Entity ⇐ 4375

  • Value ⇐ 750

  • Search space ⇐ 10^12578

  • No

  • Defined by us

  • © 2025 Timefold BV
  • Timefold.ai
  • Documentation
  • Changelog
  • Send feedback
  • Privacy
  • Legal
    • Light mode
    • Dark mode
    • System default