Package ai.timefold.solver.core.api.domain.variable

Annotation Interface PlanningListVariable

@Target({METHOD,FIELD}) @Retention(RUNTIME) public @interface PlanningListVariable
Specifies that a bean property (or a field) can be changed and should be optimized by the optimization algorithms. It is specified on a getter of a java bean property (or directly on a field) of a PlanningEntity class. The type of the PlanningListVariable annotated bean property (or a field) must be List.

List variable

A planning entity's property annotated with @PlanningListVariable is referred to as a list variable. The way solver optimizes a list variable is by adding, removing, or changing order of elements in the List object held by the list variable.

Disjoint lists

Furthermore, the current implementation works under the assumption that the list variables of all entity instances are "disjoint lists":

  • List means that the order of elements inside a list planning variable is significant.
  • Disjoint means that any given pair of entities have no common elements in their list variables. In other words, each element from the list variable's value range appears in exactly one entity's list variable.

This makes sense for common use cases, for example the Vehicle Routing Problem or Task Assigning. In both cases the order in which customers are visited and tasks are being worked on matters. Also, each customer must be visited once and each task must be completed by exactly one employee.

See Also:

  • Element Details

    • allowsUnassignedValues

      boolean allowsUnassignedValues
      If set to false (default), all elements must be assigned to some list. If set to true, elements may be left unassigned.
      See Also:
      Default:
      false

    • valueRangeProviderRefs

      String[] valueRangeProviderRefs
      Default:
      {}

    • comparatorClass

      Class<? extends Comparator> comparatorClass
      Allows sorting a collection of planning values for this variable. Some algorithms perform better when the values are sorted based on specific metrics.

      The Comparator should sort the data in ascending order. For example, prioritize three visits by sorting them based on their importance: Visit C (SMALL_PRIORITY), Visit A (MEDIUM_PRIORITY), Visit B (HIGH_PRIORITY)

      Do not use together with comparatorFactoryClass().

      Returns:
      PlanningVariable.NullComparator when it is null (workaround for annotation limitation)
      See Also:
      Default:
      ai.timefold.solver.core.api.domain.variable.PlanningVariable.NullComparator.class

    • comparatorFactoryClass

      Class<? extends ComparatorFactory> comparatorFactoryClass
      The ComparatorFactory alternative for comparatorClass().

      Do not use together with comparatorClass().

      Returns:
      PlanningVariable.NullComparatorFactory when it is null (workaround for annotation limitation)
      See Also:
      Default:
      ai.timefold.solver.core.api.domain.variable.PlanningVariable.NullComparatorFactory.class