Timefold

In this, the last release of 2024, we are bringing mostly small fixes and improvements. But we are also...

Introducing Preview Features!

[Preview features](https://docs.timefold.ai/timefold-solver/latest/upgrading-timefold-solver/backwards-compatibility#previewFeatures) are developed to the same standard of quality as the rest of Timefold Solver. They are fully specced out, implemented and documented. However, their APIs and behavior are not yet considered stable - we can change them in the future, and we may even remove them if they don't prove themselves. And to make that decision, we need your feedback!

Diversified Late Acceptance Search (DLAS)

We're kicking off the previous features with an improvement to our local search implementation! [Diversified Late Acceptance Search](https://docs.timefold.ai/timefold-solver/latest/optimization-algorithms/local-search#diversifiedLateAcceptance) is a tweak to the standard [Late Acceptance Hill Climbing](https://docs.timefold.ai/timefold-solver/latest/optimization-algorithms/local-search#lateAcceptance) and if we're right about it, it will get you better solutions to your optimization problems, and it will get there faster.

Please try it out and [let us know](https://github.com/TimefoldAI/timefold-solver/discussions) what your experience is - did your solver reach better solutions than before? How much better? Have you suffered any issues after switching to DLAS? We want to know!

Changelog

🚀 Features
- c6c30e9 Add Diversified Late Acceptance approach (1253), closes 1253
- 9c6f7b4 Add method to `SolverConfig` for setting unimproved termination limit

🐛 Fixes
- 3a1ef62 Ensure the sort manner is applied to the default CH config (1258), closes 1258
- 9d7a502 Off-by-one error when choosing element locations
- 07cc41d Use a stable recipe order for `NullableRecipe.getRecipeList()`
- 28201ef Recurse through DeepPlanningCloned classes to discover all DeepPlanningCloned classes (1237), closes 1208 1237

🧰 Tasks
- ab27eef Improve ConstraintAnalysis toString
- ee760ca Unify the handling of list variable shadows (1228), closes 1228

📝 Documentation
- d55c510 Restucture multi-threaded section (1269), closes 1269
- 8c769f7 Simplify Vehicle Routing Quickstart (1229), closes 1229
- 05ebcd4 Add FAQ section


Contributors
We'd like to thank the following people for their contributions:
- Lars Beckmann (larsbeck )
- Tim te Beek (timtebeek )
- Lee Carlon (lee-carlon )
- Christopher Chianelli (Christopher-Chianelli )
- Tom Cools (TomCools )
- Frederico Gonçalves (zepfred )
- Lukáš Petrovický (triceo )
- Geoffrey De Smet (ge0ffrey )


_Timefold Solver Community Edition_ is an open source project, and you are more than welcome to contribute as well!
For more, see [Contributing](https://github.com/TimefoldAI/timefold-solver/blob/main/CONTRIBUTING.adoc).

Should your business need to scale to truly massive data sets or require enterprise-grade support,
check out [_Timefold Solver Enterprise Edition_](https://timefold.ai/pricing).

How to use Timefold Solver

To see Timefold Solver in action, check out [the quickstarts](https://github.com/TimefoldAI/timefold-quickstarts).

[//]: (Ideally we'd show the pom.xml snippet, but a JReleaser bug would remove all whitespace from it.)
[//]: (See https://github.com/jreleaser/jreleaser/issues/1142)
With Maven or Gradle, add the `ai.timefold.solver : timefold-solver-core : 1.17.0` dependency in your `pom.xml` to get started.

You can also import the Timefold Solver Bom (`ai.timefold.solver : timefold-solver-bom : 1.17.0`)
to avoid duplicating version numbers when adding other Timefold Solver dependencies later on.

Additional notes

The changelog and the list of contributors above are automatically generated.
It excludes contributions to certain areas of the repository, such as CI and build automation.
This is done for the sake of brevity and to make the user-facing changes stand out more.

Looks like Christmas came early this year! This release of your favorite solver is packed to the brim with cool new features.

Featured update: Nullness annotations on public API

Users of Kotlin rejoice! All public APIs of Timefold Solver have now been null-marked using [JSpecify](https://jspecify.dev). This means you should now be able to remove some of those pesky Elvis operators from your code. Both Java and Kotlin users will also be able to benefit from IDE support, warning of improper use and handling of `null`.

This has been a big change and we are doubly excited about it, because it was entirely contributed by a member of our growing community! Our thanks go out to Peter Laggner (greyhairredbear), for the time and effort he spent delivering this. We hope he'll enjoy some Timefold-branded tokens of appreciation we've sent his way.

But that's not all we have in store for you!

- Due to some improvements to the solver, we no longer require you to implement undo moves for your [Custom moves](https://docs.timefold.ai/timefold-solver/latest/optimization-algorithms/overview#customMoves); you can safely delete them from your codebase, just like we did with ours.
- We have also updated the [Score Analysis API](https://docs.timefold.ai/timefold-solver/latest/constraints-and-score/understanding-the-score#scoreAnalysis) to optionally skip listing all justifications, which will help users with massive datasets.
- We have a brand [new documentation website](https://docs.timefold.ai) with some refreshed content.

And last but not least, we've been making smaller improvements and bugfixes here and there, as per usual. Enjoy the latest and greatest Timefold Solver, and [stay in touch](https://github.com/TimefoldAI/timefold-solver/discussions)!

Changelog

🚀 Features
- 48542aa Add nullness annotations on public API (Part 2) (1160), closes 1160
- 06d2c82 Enable score analysis without justifications (1185), closes 1185
- 34dded5 Add nullness annotations on public API (Part 1) (1009), closes 1009

🐛 Fixes
- 0750c9d Add PlanningPinToIndex to Python (1191), closes 1191

📝 Documentation
- 2b68305 Fix syntax issues in Python (1182), closes 1182
- 1300d72 Improve note on allows unassigned
- 6f5f54f Restructure introduction (1151), closes 1151
- ef2aae9 Add missing link to backup planning (1147), closes 1147


Contributors
We'd like to thank the following people for their contributions:
- Christopher Chianelli (Christopher-Chianelli)
- Franco Peschiera (pchtsp)
- Geoffrey De Smet (ge0ffrey)
- Lukáš Petrovický (triceo)
- Peter Laggner (greyhairredbear)
- Pieter De Schepper (pieterdeschepper)
- Tom Cools (TomCools)

_Timefold Solver Community Edition_ is an open source project, and you are more than welcome to contribute as well!
For more, see [Contributing](https://github.com/TimefoldAI/timefold-solver/blob/main/CONTRIBUTING.adoc).

Should your business need to scale to truly massive data sets or require enterprise-grade support,
check out [_Timefold Solver Enterprise Edition_](https://timefold.ai/pricing).

How to use Timefold Solver

To see Timefold Solver in action, check out [the quickstarts](https://github.com/TimefoldAI/timefold-quickstarts).

[//]: (Ideally we'd show the pom.xml snippet, but a JReleaser bug would remove all whitespace from it.)
[//]: (See https://github.com/jreleaser/jreleaser/issues/1142)
With Maven or Gradle, add the `ai.timefold.solver : timefold-solver-core : 1.16.0` dependency in your `pom.xml` to get started.

You can also import the Timefold Solver Bom (`ai.timefold.solver : timefold-solver-bom : 1.16.0`)
to avoid duplicating version numbers when adding other Timefold Solver dependencies later on.

Additional notes

The changelog and the list of contributors above are automatically generated.
It excludes contributions to certain areas of the repository, such as CI and build automation.
This is done for the sake of brevity and to make the user-facing changes stand out more.

Fall is here and the days are getting shorter, but the release cadence of Timefold Solver is still once a month!

This time, we've brought a whole bunch of smaller improvements and bug fixes. We've extended our Recommendations API, made the recently introduced Ruin and Recreate move more reliable, and improved our Python experience.

Changelog

🚀 Features
- 11cd2fb Support assigned values for Recommendations as well (1136), closes 1136
- c027d7e Add new move count metric (1072), closes 1072
- 0801dfd Expose constraint metamodel in Quarkus and Spring Boot (1108), closes 1108
- 9c36871 Multi-threaded solving support for Ruin and Recreate moves
- 0bf63f6 Add solver job start event (1084), closes 1084

🐛 Fixes
- 23d64bd Don't pick a move if CH terminates prematurely (1132), closes 1132
- 753b6f9 Don't restart solver termination in Ruin and Recreate
- c416a8b Don't override value with loop variable
- 141b70f Cast classmethods' first argument to PythonLikeType in 3.10, use same instances for Enum values
- f24fb28 Pop off result of __setattr__ and __delattr__ in generic case
- 1482036 Generate override methods when parent's parameters have a different signature

🧰 Tasks
- 6534b0f Improve SolverManager error message in Python (1114), closes 1114

📝 Documentation
- 1b910cb Updated intro with planning content


Contributors
We'd like to thank the following people for their contributions:
- Christopher Chianelli
- Frederico Gonçalves ([zepfred](https://github.com/zepfred))
- Lukáš Petrovický
- Matej Čimbora
- lee-carlon


_Timefold Solver Community Edition_ is an open source project, and you are more than welcome to contribute as well!
For more, see [Contributing](https://github.com/TimefoldAI/timefold-solver/blob/main/CONTRIBUTING.adoc).

Should your business need to scale to truly massive data sets or require enterprise-grade support,
check out [_Timefold Solver Enterprise Edition_](https://timefold.ai/pricing).

How to use Timefold Solver

To see Timefold Solver in action, check out [the quickstarts](https://github.com/TimefoldAI/timefold-quickstarts).

[//]: (Ideally we'd show the pom.xml snippet, but a JReleaser bug would remove all whitespace from it.)
[//]: (See https://github.com/jreleaser/jreleaser/issues/1142)
With Maven or Gradle, add the `ai.timefold.solver : timefold-solver-core : 1.15.0` dependency in your `pom.xml` to get started.

You can also import the Timefold Solver Bom (`ai.timefold.solver : timefold-solver-bom : 1.15.0`)
to avoid duplicating version numbers when adding other Timefold Solver dependencies later on.

Additional notes

The changelog and the list of contributors above are automatically generated.
It excludes contributions to certain areas of the repository, such as CI and build automation.
This is done for the sake of brevity and to make the user-facing changes stand out more.

Summer vacations are over, the [big announcements](https://timefold.ai/press/timefold-secures-6-million-to-expand-planning-ai-platform) are made, and now we're back with another release of Timefold Solver!

Featured Update: Ruin and Recreate Move

Is your solver getting stuck in local optima, no longer improving the solution? Then you may benefit from the ["Ruin and Recreate" move](https://docs.timefold.ai/timefold-solver/latest/optimization-algorithms/move-selector-reference#ruinRecreateMoveSelector), which destroys part of the solution and rebuilds it all over again. Our experiments show that this can often help the solver escape local optima, so why don't you give it a try? And when you do, we'd love to hear what your own experience with this new move was - [come talk to us](https://github.com/TimefoldAI/timefold-solver/discussions)!

Besides that, we are bringing the usual bunch of bug fixes and improvements. As always, all of these are available for all of our Java, Python and Kotlin users.

Changelog

🚀 Features
- 85e6812 introduce a Ruin And Recreate move (1010), closes 1010
- ff6ae02 Add missing `of` methods to scores in Python (1055), closes 1055
- 6c7416c Add chained variable support to Python
- df74d42 improve JVM exceptions (1037), closes 1037

🐛 Fixes
- f09a244 Prevent excessive logging of constraint weights
- 037450f Allow relative imports in translated functions (1081), closes 967 1081
- 5f44f32 Show Python traceback when constructing constraints fail (1082), closes 969 1082
- 7149abe Initialize nested selectors correctly
- 96c3da0 Allow PlanningId to be defined on interfaces (1060), closes 1060
- 274dadd Use inserted range when retracting range in `toConnectedRanges` (1056), closes 953 1056

📝 Documentation
- 3b01463 Fix InverseRelationShadowVariable code snippet (1066), closes 1066
- 716e45e Add Python examples (1047), closes 1047


Contributors
We'd like to thank the following people for their contributions:
- Christopher Chianelli
- Frederico Gonçalves ([zepfred](https://github.com/zepfred))
- Geoffrey De Smet
- Lukáš Petrovický
- Rutger Lubbers
- Tobias Wasner ([wasnertobias](https://github.com/wasnertobias))


_Timefold Solver Community Edition_ is an open source project, and you are more than welcome to contribute as well!
For more, see [Contributing](https://github.com/TimefoldAI/timefold-solver/blob/main/CONTRIBUTING.adoc).

Should your business need to scale to truly massive data sets or require enterprise-grade support,
check out [_Timefold Solver Enterprise Edition_](https://timefold.ai/pricing).

How to use Timefold Solver

To see Timefold Solver in action, check out [the quickstarts](https://github.com/TimefoldAI/timefold-quickstarts).

[//]: (Ideally we'd show the pom.xml snippet, but a JReleaser bug would remove all whitespace from it.)
[//]: (See https://github.com/jreleaser/jreleaser/issues/1142)
With Maven or Gradle, add the `ai.timefold.solver : timefold-solver-core : 1.14.0` dependency in your `pom.xml` to get started.

You can also import the Timefold Solver Bom (`ai.timefold.solver : timefold-solver-bom : 1.14.0`)
to avoid duplicating version numbers when adding other Timefold Solver dependencies later on.

Additional notes

The changelog and the list of contributors above are automatically generated.
It excludes contributions to certain areas of the repository, such as CI and build automation.
This is done for the sake of brevity and to make the user-facing changes stand out more.

As the summer sun is slowly baking us, so have we baked something new for you. Timefold Solver 1.13.0 brings new features as well as the usual assortment of bug fixes and improvements.

Featured Update: Constraint Weight Overrides

We bring you a smaller an improved API for [setting weights for your constraints](https://docs.timefold.ai/timefold-solver/latest/constraints-and-score/constraint-configuration). Where previously you had to write a lot of boilerplate to provide an entire `ConstraintConfiguration` implementation, specifying a constraint weight is now as easy as adding a `Map` to your planning solution!

Besides that, we are introducing a [new type of shadow variable](https://docs.timefold.ai/timefold-solver/latest/using-timefold-solver/modeling-planning-problems#tailChainVariable) - one that can be updated by a simple method, as opposed to introducing an entire `VariableListener`. This allows for easy updates to the tail chains of a list variable.

As always, all of these updates are available for all of our Java, Python and Kotlin users.

Changelog

🚀 Features
- 10b9258 Add CascadingUpdateShadowVariable (954), closes 954
- 2c74a11 Constraint weight override (946), closes 946

🐛 Fixes
- 3ffb49b Address scale equal to NaN
- ec49da1 Respect merge function in toMap() collector
- d01cd42 Avoid duplicating nearby configuration
- ecae569 Proper casts in Python load_balance collector

🔄️ Changes
- 1a9d194 Create less BigDecimal in load balancing (1030), closes 1030


Contributors
We'd like to thank the following people for their contributions:
- Christopher Chianelli
- Frederico Gonçalves ([zepfred](https://github.com/zepfred))
- Jurriaan Persyn ([oemebamo](https://github.com/oemebamo))
- Lukáš Petrovický ([triceo](https://github.com/triceo))
- Marek Winkler ([winklerm](https://github.com/winklerm))
- hizhangbo ([hizhangbo](https://github.com/hizhangbo))
- lee-carlon


_Timefold Solver Community Edition_ is an open source project, and you are more than welcome to contribute as well!
For more, see [Contributing](https://github.com/TimefoldAI/timefold-solver/blob/main/CONTRIBUTING.adoc).

Should your business need to scale to truly massive data sets or require enterprise-grade support,
check out [_Timefold Solver Enterprise Edition_](https://timefold.ai/pricing).

How to use Timefold Solver

To see Timefold Solver in action, check out [the quickstarts](https://github.com/TimefoldAI/timefold-quickstarts)
and read [our documentation](https://docs.timefold.ai/timefold-solver/latest/quickstart/overview).

Additional notes

The changelog and the list of contributors above are automatically generated.
It excludes contributions to certain areas of the repository, such as CI and build automation.
This is done for the sake of brevity and to make the user-facing changes stand out more.

Summer is here, but we're not resting! Not all of us anyway. This release brings features, as well as an assortment of bug fixes and enhancements.

Featured update: Fairness and Load Balancing

Providing optimized schedules is only one part of the problem. And if our employees see that our schedule isn't being fair to them, because Ann is getting three times as many shifts as Dan is, they will not be very happy and the business will struggle. The business may even run into labour law issues.

That is why we are introducing a load balancing collector for Constraint Streams. You can read all about it in [Fairness and load balancing](https://docs.timefold.ai/timefold-solver/latest/constraints-and-score/load-balancing-and-fairness) section of the documentation.

Besides that, we have added some quality of life improvements:
- `ScoreAnalysis` now provides more information about itself, including a useful [textual summary of the analysis](https://docs.timefold.ai/timefold-solver/latest/constraints-and-score/understanding-the-score#scoreAnalysis).
- The solver can now trigger an event when the first initialized solution shows up, letting you know when the construction heuristic ends and local search begins.

All of these improvements and bugfixes are also available in [Timefold Solver for Python](https://pypi.org/project/timefold/). Have you checked it out yet?

Changelog

🚀 Features
- d07cfb2 Add support for fairness constraints (918), closes 918
- 7e6102e Improve `ScoreAnalysis` debug information (923), closes 923
- 84e4ae0 Allow to consume the initialized solution (915), closes 915

🐛 Fixes
- e7fae26 Only include tail chain move when using a single var (936), closes 936
- d5ed7e1 Do not fail on solution/entity classes as interfaces (934), closes 934
- 24b3240 Continue the warmup when one configuration fails
- 03ed42c Update the best score image of the benchmark section
- 5690ec6 Fail fast when local search starts from an uninitialized solution


Contributors
We'd like to thank the following people for their contributions:
- Christopher Chianelli
- Frederico Gonçalves ([zepfred](https://github.com/zepfred))
- Lukáš Petrovický ([triceo](https://github.com/triceo))
- lee-carlon


_Timefold Solver Community Edition_ is an open source project, and you are more than welcome to contribute as well!
For more, see [Contributing](https://github.com/TimefoldAI/timefold-solver/blob/main/CONTRIBUTING.adoc).

Should your business need to scale to truly massive data sets or require enterprise-grade support,
check out [_Timefold Solver Enterprise Edition_](https://timefold.ai/pricing).

How to use Timefold Solver

To see Timefold Solver in action, check out [the quickstarts](https://github.com/TimefoldAI/timefold-quickstarts).

[//]: (Ideally we'd show the pom.xml snippet, but a JReleaser bug would remove all whitespace from it.)
[//]: (See https://github.com/jreleaser/jreleaser/issues/1142)
With Maven or Gradle, add the `ai.timefold.solver : timefold-solver-core : 1.12.0` dependency in your `pom.xml` to get started.

You can also import the Timefold Solver Bom (`ai.timefold.solver : timefold-solver-bom : 1.12.0`)
to avoid duplicating version numbers when adding other Timefold Solver dependencies later on.

Additional notes

The changelog and the list of contributors above are automatically generated.
It excludes contributions to certain areas of the repository, such as CI and build automation.
This is done for the sake of brevity and to make the user-facing changes stand out more.