Introduction

1. What is Timefold Solver?

Every organization faces planning problems: providing products or services with a limited set of constrained resources (employees, assets, time and money). Timefold Solver’s Planning AI optimizes these problems to do more business with less resources using Constraint Satisfaction Programming, which is part of the Operations Research discipline.

Timefold Solver is a lightweight, embeddable constraint satisfaction engine which optimizes planning problems. It solves use cases such as:

  • Employee shift rostering: timetabling nurses, repairmen, …​

  • Agenda scheduling: scheduling meetings, appointments, maintenance jobs, advertisements, …​

  • Educational timetabling: scheduling lessons, courses, exams, conference presentations, …​

  • Vehicle routing: planning vehicle routes (trucks, trains, boats, airplanes, …​) for moving freight and/or passengers through multiple destinations using known mapping tools …​

  • Bin packing: filling containers, trucks, ships, and storage warehouses with items, but also packing information across computer resources, as in cloud computing …​

  • Job shop scheduling: planning car assembly lines, machine queue planning, workforce task planning, …​

  • Cutting stock: minimizing waste while cutting paper, steel, carpet, …​

  • Sport scheduling: planning games and training schedules for football leagues, baseball leagues, …​

  • Financial optimization: investment portfolio optimization, risk spreading, …​

useCaseOverview

2. Planning

The need to create plans generally arises from a desire to achieve a goal:

  • Build a house.

  • Correctly staff a hospital shift.

  • Complete work at all customer locations.

Achieving those goals involves organizing the available resources. To correctly staff a hospital you need enough qualified personnel in a variety of fields and specializations to cover the opening hours of the hospital.

Any plan to deploy resources, whether to staff a hospital shift or to assemble the building materials for a new house, is done under constraints.

Constraints could be laws of the universe; people can’t work two shifts in two separate locations at the same time, and you can’t mount a roof on a house that doesn’t exist. Constraints can also be relevant legislation; employees need a certain number of hours between shifts or are only allowed to work a maximum number of hours per week. Employee preferences can also be considered constraints, such as, certain employees prefer to work specific shift patterns.

2.1. Feasible plans

Any plan needs to consider all three elements, goals, resources, and constraints, in balance to be a feasible plan. A plan that fails to account for all the elements of the problem is an infeasible plan. For instance, if a hospital staff roster covers all shifts, but assigns employees back-to-back shifts with no breaks for sleep or life outside work, it is not a valid plan.

2.2. Planning problems are hard to solve

Planning problems become harder to solve as the number of resources and constraints increase. Creating an employee shift schedule for a small team of four employees is fairly straightforward. However, if each employee performs a specific function within the business and those functions need to be performed in a specific order, changes that affect one employee quickly cascade and affect everybody on the team. If parts are delivered late and prevent one employee from completing their tasks, subsequent work will also be delayed.

As more employees and different work specializations are added, things become much more complicated.

For a trivial field service routing problem with 4 vehicles and 8 visits, the number of possibilities that a brute algorithm considers is 19,958,418.

What would take a team of planners many hours to schedule can be automatically scheduled by Timefold Solver in a fraction of the time.

2.2.1. Operations Research

Operations Research (OR) is a field of research that is focused on finding optimal (or near optimal) solutions to problems with techniques that improve decision-making.

Constraint satisfaction programming is part of Operations Research that aims to satisfy all the constraints of a problem.

2.3. Planning AI

Planning AI is a type of artificial intelligence designed specifically to handle complex planning and scheduling tasks, and to satisfy the constraints of planning problems. Instead of just automating simple, repetitive tasks, it helps you make better decisions by sorting through countless possibilities to find the best solutions—saving you time, reducing costs, and improving efficiency.

2.3.1. Why Planning AI is different

Traditional methods of planning often involve manually sifting through options or relying on basic tools that can’t keep up with the complexity of real-world problems. Planning AI, on the other hand, uses advanced strategies to quickly focus on the most promising solutions, even when the situation is extremely complicated. Planning AI also makes it possible to understand the final solution with a breakdown of which constraints have been violated and scores for individual constraints and an overall score. This makes Planning AI incredibly valuable in industries where getting the right plan is crucial—whether that’s scheduling workers, routing deliveries, or managing resources in a factory.

Planning AI is designed to be accessible, so you can start improving your planning process right away.

2.4. Constraints

Constraints can be considered hard, medium, or soft.

Hard constraints represent rules and limitations of the real world that any planning solution has to respect. For instance, there are only 24 hours in a day and people can only be in one place at a time. Hard constraints also include rules that must be adhered to, for instance, employee contracts and the order in which dependent tasks are completed.

Breaking hard constraints would result in infeasible plans.

Medium constraints help manage plans when resources are limited, (for instance, when there aren’t enough technicians to complete all the customer visits or there aren’t enough employees to work all the available shifts). Medium constraints incentivize Timefold Platform to assign as many entities (visits or shifts) as possible.

Soft constraints help optimize plans based on the business goals, for instance, minimize travel time between customer visits or assign employees to their preferred shifts.

To help determine the quality of the solution, plans are assigned a score with values for hard, medium, and soft constraints.

"0hard/-257medium/-6119520soft"

From this example score we can see zero hard constraints were broken, while both the medium and soft scores have negative values (the scores do not show how many constraints were broken, but values associated with those constraints).

Because breaking hard constraints would result in an infeasible solution, a solution that breaks zero hard constraints and has a soft constraint score of -1,000,000 is better than a solution that breaks one hard constraint and has a soft constraint score of 0.

The weight of constraints can be tweaked to adjust their impact on the solution.

3. Status of Timefold Solver

Timefold Solver is 100% pure JavaTM and runs on Java 17 or higher. It integrates very easily with other JavaTM, Python and other technologies. Timefold Solver works on any Java Virtual Machine and is compatible with the major JVM languages and all major platforms. It also supports Kotlin and Python.

compatibility

Timefold Solver is stable, reliable and scalable. It has been heavily tested with unit, integration, and stress tests, and is used in production throughout the world. One example handles over 50 000 variables with 5000 values each, multiple constraint types and billions of possible constraint matches.

We offer two editions of Timefold Solver.

3.1. Timefold Solver Community Edition

Timefold Solver Community Edition is open source software, released under the Apache License 2.0. This license is very liberal and allows reuse for commercial purposes. Read the layman’s explanation.

Timefold Solver Community Edition is available in the Maven Central Repository. It is and will always be free. The overwhelming majority of solver features will always be available in the Community Edition. Most users will be able to solve their planning problems with the Community Edition.

3.2. Timefold Solver Enterprise Edition

Timefold Solver Enterprise Edition is a commercial product that offers additional features to scale out to very large datasets. To find out more, see Enterprise Edition section of this documentation.

4. Backwards compatibility

Timefold Solver separates its API from its implementation:

  • Public API: All classes in the following package namespaces are 100% backwards compatible in future releases, especially minor and hotfix releases:

    • ai.timefold.solver.core.api

    • ai.timefold.solver.benchmark.api

    • ai.timefold.solver.test.api

    • ai.timefold.solver…​api*

  • Configuration: The solver configuration is backwards compatible for all elements, except for elements that require the use of non-public API classes. The solver configuration is defined by the classes in the following package namespaces:

    • ai.timefold.solver.core.config

    • ai.timefold.solver.benchmark.config

  • Implementation classes: All other classes are not backwards compatible. They will change in future major or minor releases, but probably not in hotfix releases.

Backwards incompatible changes will be clearly documented in the upgrade recipe.

This documentation covers some impl classes too. Those documented impl classes are reliable and safe to use (unless explicitly marked as experimental in this documentation), but we’re just not entirely comfortable yet to write their signatures in stone.

The Python Solver is currently in beta and its API is subject to change.

5. Start using Timefold Solver

5.1. Use Timefold Solver with Maven, Gradle or PyPI

The Timefold Solver jars are available in the central maven repository and PyPI.

  • Maven

  • Gradle

  • Pyproject.toml

Add a dependency to timefold-solver-core in your pom.xml:

    <dependency>
      <groupId>ai.timefold.solver</groupId>
      <artifactId>timefold-solver-core</artifactId>
      <version>...</version>
    </dependency>

Or better yet, import the timefold-solver-bom in dependencyManagement to avoid duplicating version numbers when adding other timefold dependencies later on:

<project>
  ...
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>ai.timefold.solver</groupId>
        <artifactId>timefold-solver-bom</artifactId>
        <type>pom</type>
        <version>...</version>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>ai.timefold.solver</groupId>
      <artifactId>timefold-solver-core</artifactId>
    </dependency>
    <dependency>
      <groupId>ai.timefold.solver</groupId>
      <artifactId>timefold-solver-jpa</artifactId>
    </dependency>
    ...
  </dependencies>
</project>

Add a dependency to timefold-solver-core in your build.gradle:

dependencies {
  implementation 'ai.timefold.solver:timefold-solver-core:...'
}

Add a dependency to timefold in your pyproject.toml:

[project]
dependencies = [
    'timefold == ...',
    # ...
]

See also how to switch To Enterprise Edition.

To find out how to get started with Timefold Solver, see Quickstarts.

5.2. Upgrade to the latest version

See the dedicated section on Upgrading Timefold Solver.