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

Annotation Interface PlanningVariable

@Target({METHOD,FIELD})
@Retention(RUNTIME)
public @interface PlanningVariable

Specifies that a bean property (or a field) can be changed and should be optimized by the optimization algorithms.

The property must be an object type. Primitive types (such as int, double, long) are not allowed.

It is specified on a getter of a java bean property (or directly on a field) of a PlanningEntity class.

It is sometimes referred to as the "basic" planning variable, to distinguish it from a list variable.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	PlanningVariable.NullComparator<T>
static interface	PlanningVariable.NullComparatorFactory<Solution_,T>
static interface	PlanningVariable.NullStrengthComparator<T>	Deprecated, for removal: This API element is subject to removal in a future version. Deprecated in favor of PlanningVariable.NullComparator.
static interface	PlanningVariable.NullStrengthWeightFactory<Solution_,T>	Deprecated, for removal: This API element is subject to removal in a future version. Deprecated in favor of PlanningVariable.NullComparatorFactory.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
boolean	allowsUnassigned	A variable will automatically add the planning value null to the ValueRangeProvider's range.
Class<? extends Comparator>	comparatorClass	Allows sorting a collection of planning values for this variable.
Class<? extends ComparatorFactory>	comparatorFactoryClass	The ComparatorFactory alternative for comparatorClass().
PlanningVariableGraphType	graphType	Deprecated, for removal: This API element is subject to removal in a future version. Chained variable is deprecated.
boolean	nullable	Deprecated, for removal: This API element is subject to removal in a future version. Use allowsUnassigned() instead.
Class<? extends Comparator>	strengthComparatorClass	Deprecated, for removal: This API element is subject to removal in a future version. Deprecated in favor of comparatorClass().
Class<? extends SelectionSorterWeightFactory>	strengthWeightFactoryClass	Deprecated, for removal: This API element is subject to removal in a future version. Deprecated in favor of comparatorFactoryClass().
String[]	valueRangeProviderRefs	Any ValueRangeProvider annotation on a PlanningSolution or PlanningEntity will automatically be registered with its ValueRangeProvider.id().

Element Details

valueRangeProviderRefs

String[] valueRangeProviderRefs

Any ValueRangeProvider annotation on a PlanningSolution or PlanningEntity will automatically be registered with its ValueRangeProvider.id().

If no refs are provided, all ValueRangeProviders without an id will be registered, provided their return types match the type of this variable.

Returns:

0 or more registered ValueRangeProvider.id()

Default:

{}

allowsUnassigned

boolean allowsUnassigned

A variable will automatically add the planning value null to the ValueRangeProvider's range.

Allowing unassigned is not compatible with PlanningVariableGraphType.CHAINED true. Allowing unassigned is not compatible with a primitive property type.

Returns:

true if null is a valid value for this planning variable

See Also:

• PlanningListVariable.allowsUnassignedValues()

Default:

false

graphType

@Deprecated(forRemoval=true,
            since="1.31.0")
PlanningVariableGraphType graphType

Deprecated, for removal: This API element is subject to removal in a future version.

Chained variable is deprecated. Use list variable instead.

In some use cases, such as Vehicle Routing, planning entities form a specific graph type, as specified by PlanningVariableGraphType.

Returns:

never null, defaults to PlanningVariableGraphType.NONE

Default:

NONE

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:

• comparatorFactoryClass()

Default:

ai.timefold.solver.core.api.domain.variable.PlanningVariable.NullComparator.class

comparatorFactoryClass

Class<? extends ComparatorFactory> comparatorFactoryClass

The ComparatorFactory alternative for comparatorClass().

Differs from comparatorClass() because it allows accessing the current solution when creating the comparator.

Do not use together with comparatorClass().

Returns:

PlanningVariable.NullComparatorFactory when it is null (workaround for annotation limitation)

See Also:

• comparatorClass()

Default:

ai.timefold.solver.core.api.domain.variable.PlanningVariable.NullComparatorFactory.class

nullable

@Deprecated(forRemoval=true,
            since="1.8.0")
boolean nullable

Deprecated, for removal: This API element is subject to removal in a future version.

Use allowsUnassigned() instead.

As defined by allowsUnassigned().

Returns:

true if null is a valid value for this planning variable

Default:

false

strengthComparatorClass

@Deprecated(forRemoval=true,
            since="1.28.0")
Class<? extends Comparator> strengthComparatorClass

Deprecated, for removal: This API element is subject to removal in a future version.

Deprecated in favor of comparatorClass().

Allows a collection of planning values for this variable to be sorted by strength. A strengthWeight estimates how strong a planning value is. Some algorithms benefit from planning on weaker planning values first or from focusing on them.

The Comparator should sort in ascending strength. For example: sorting 3 computers on strength based on their RAM capacity: Computer B (1GB RAM), Computer A (2GB RAM), Computer C (7GB RAM),

Do not use together with strengthWeightFactoryClass().

Returns:

PlanningVariable.NullStrengthComparator when it is null (workaround for annotation limitation)

See Also:

• strengthWeightFactoryClass()

Default:

ai.timefold.solver.core.api.domain.variable.PlanningVariable.NullStrengthComparator.class

strengthWeightFactoryClass

@Deprecated(forRemoval=true,
            since="1.28.0")
Class<? extends SelectionSorterWeightFactory> strengthWeightFactoryClass

Deprecated, for removal: This API element is subject to removal in a future version.

Deprecated in favor of comparatorFactoryClass().

The SelectionSorterWeightFactory alternative for strengthComparatorClass().

Do not use together with strengthComparatorClass().

Returns:

PlanningVariable.NullStrengthWeightFactory when it is null (workaround for annotation limitation)

See Also:

• strengthComparatorClass()

Default:

ai.timefold.solver.core.api.domain.variable.PlanningVariable.NullStrengthWeightFactory.class