Timefold Solver 1.4.0 introduces explainable scoring, allowing easy breakdown of solution scores by constraints for end-users. Now available with JSON serialization for easy integration.
Subscribe to Planned, planning education for real-world stuff.
By Lukáš Petrovický
November 8, 2023
Have you ever received a solution from the Solver and wondered what -3hard/-11softactually means? Or had to explain it to your end-users? Now, you can just show it to them. In Timefold Solver 1.4.0, you can break down the score of a solution into constraints and constraint matches, to make it understandable for your end-users.
Let’s take a closer look and find out what’s new in another exciting monthly release of Timefold Solver.
We expand on our existing functionality by making score explanations easier to use than ever before. Here’s how you start using this new feature:
// First, we get some solution from the solver. Nothing new here, business as usual.
SolverJob<Timetable, ...> solverJob = solverManager.solve(...);
Timetable timetable = solverJob.getFinalBestSolution();
// Now that we have the timetable, we can analyze the score.
ScoreAnalysis<HardSoftScore> scoreAnalysis = solutionManager.analyze(timetable);
The ScoreAnalysis object holds the total score of the analyzed solution, and a breakdown of the score per constraints. This allows you to easily see which constraints are impacting your solution the most.
You can break the score down even further, by going deeper into the ConstraintAnalysis object. Each such object contains a list of matches, which are the individual violations of the constraint. This allows you to see which planning entities or values are causing the constraint to be violated. also called a justification.
for (MatchAnalysis<HardSoftScore> match: constraintAnalysis.matches()) {
System.out.println(" Match score: " + match.score());
System.out.println("Match justification: " + match.justification());
}
With this data structure, you have the full overview of your planning solution and how it was scored by Timefold Solver. But we did not stop there!
In today’s world, what good are excellent backend APIs if you cannot send the results over the wire to the frontend? We’ve got you covered. The ScoreAnalysis object is JSON-friendly, which means you can easily serialize it and send it over the wire. In Quarkus and Spring Boot, the ScoreAnalysis object will automatically serialize to JSON such as this:
We see the score is made up of two constraints here, each with their own score and matches. The frontend can then easily display the score breakdown to the user, such as this:
Note that in this case, we have chosen not to display the individual constraint matches to make the visualization simpler. In a more detail-oriented view, you may choose to display the individual matches as well.
In addition to the new score explanation functionality, we have also made it easier to compare two solutions to one another. You can use the same score analysis functionality above to compare two solutions.
The ScoreAnalysis object has a diff(ScoreAnalysis otherScoreAnalysis) method which, when called, returns a new ScoreAnalysis object. This object holds the differences between the two solutions. It shows the difference in score and the difference in individual constraints, down to every single constraint match.
Besides the features above, we have brought the usual battery of bug fixes and performance improvements. With Timefold Solver 1.4.0, you can enjoy slightly faster Constraint Streams and an even more stable experience. We also upgraded Quarkus, Spring and other dependencies to their latest versions.
We are also happy to have been included in Spring Initializr, making your getting started experience with Spring Boot and Timefold Solver even easier!
Timefold Solver continues full steam ahead. The new explainable score functionality is a great addition, and a feature much requested by our users. Upgrade now to get the best release yet!
Continue reading
Blog
The 4 levels of scheduling:From manual chaos to AI-driven optimization
Blog
The only constant is change: How PlanningAI keeps schedules alive in real-time
Plans rarely survive reality, no matter how perfect they are. Employee sick calls, broken trucks, or no-show customers can wreck your carefully built schedule before lunchtime. That’s why our PlanningAI optimization algorithms replan in real-time. In this post, Tom Cools will enlighten you on how this works.
Blog
Is PlanningAI a blessing for Operations Research?
Operations Research is, and has always been, about solving one of the world’s toughest challenges: planning problems. Finding the best way to allocate resources, schedule shifts, or route deliveries under an abundance of real-world constraints. It is widely accepted that optimizing those problems will make the world a better place. Then why does OR struggle with real-world adoption?