Model Enrichment

This page describes features which are only relevant when running Timefold Solver as a service.
The information on these pages may describe functionality which may be changed or even removed in a future release.

1. SolverModel enrichment

In some situations, the SolverModel must be enriched with additional information. This could be external information such as map data or smaller enhancements such as pinning entities which occurred in the past.

Enrichers usually pre-calculate fields which would otherwise be calculated in a ConstraintStream. Especially when the field depends on external information or is difficult to compute, pre-calculating can lead to much faster results.

In this example, we enrich the Timetable PlanningSolution described above by filling in the "isHoliday" field for all Timeslot objects.

Timeslot class for the School Timetabling example

Java
Kotlin

public class Timeslot {

    private LocalDateTime startTime;
    private LocalDateTime endTime;

    private boolean isHoliday;

    public void setHoliday(boolean isHoliday) {
        this.isHoliday = isHoliday;
    }

    // other Getters/Setters/Constructors excluded
}

data class Timeslot(
    val startTime: LocalDateTime? = null,
    val endTime: LocalDateTime? = null
) {
    var isHoliday: Boolean = false
}

Enrichment of the SolverModel is possible by implementing a SolverModelEnricher.

Timeslot Enricher for the School Timetabling example

Java
Kotlin

@ApplicationScoped
public class TimeslotHolidayEnricher implements SolverModelEnricher<Timetable> {

    @Override
    public Timetable enrich(Timetable solverModel) {
        for (Timeslot timeslot : solverModel.getTimeslots()) {
            boolean isHoliday = overlapsWithKnownHoliday(timeslot.getStartTime(), timeslot.getEndTime());
            timeslot.setHoliday(isHoliday);
        }

        return solverModel;
    }

    private boolean overlapsWithKnownHoliday(LocalDateTime start, LocalDateTime end) {
        // Implementation excluded; potentially call external service / database.
        return false;
    }
}

@ApplicationScoped
class TimeslotHolidayEnricher : SolverModelEnricher<Timetable> {

    override fun enrich(solverModel: Timetable): Timetable {
        for (timeslot in solverModel.timeslots) {
            timeslot.isHoliday = overlapsWithKnownHoliday(timeslot.startTime, timeslot.endTime)
        }

        return solverModel
    }

    private fun overlapsWithKnownHoliday(start: LocalDateTime?, end: LocalDateTime?): Boolean {
        // Implementation excluded; potentially call external service / database.
        return false
    }
}

Next, register a SolverModelEnrichmentDirector implementation. This class allows you to determine the order in which enrichers are executed. This might be important when 1 of your custom enrichers depends on an enricher provided by Timefold Solver.

Timetable Enrichment Director for the School Timetabling example

Java
Kotlin

@ApplicationScoped
public class TimetableEnrichmentDirector implements SolverModelEnrichmentDirector<Timetable> {

    private final TimeslotHolidayEnricher timeslotEnricher;

    @Inject
    public TimetableEnrichmentDirector(TimeslotHolidayEnricher timeslotEnricher) {
        this.timeslotEnricher = timeslotEnricher;
    }

    @Override
    public Timetable enrich(Timetable solverModel) {
        var enrichedModel = timeslotEnricher.enrich(solverModel);
        // Additional enrichers.
        return enrichedModel;
    }
}

@ApplicationScoped
class TimetableEnrichmentDirector @Inject constructor(
    private val timeslotEnricher: TimeslotHolidayEnricher
) : SolverModelEnrichmentDirector<Timetable> {

    override fun enrich(solverModel: Timetable): Timetable {
        val enrichedModel = timeslotEnricher.enrich(solverModel)
        // Additional enrichers.
        return enrichedModel
    }
}