Package ai.timefold.solver.core.impl.score.director.incremental

Class IncrementalScoreDirector<Solution_,Score_ extends Score<Score_>>

java.lang.Object

ai.timefold.solver.core.impl.score.director.AbstractScoreDirector<Solution_,Score_,IncrementalScoreDirectorFactory<Solution_,Score_>>

ai.timefold.solver.core.impl.score.director.incremental.IncrementalScoreDirector<Solution_,Score_>

Type Parameters:

Solution_ - the solution type, the class with the PlanningSolution annotation

Score_ - the score type to go with the solution

All Implemented Interfaces:

ScoreDirector<Solution_>, InnerScoreDirector<Solution_,Score_>, VariableDescriptorAwareScoreDirector<Solution_>, AutoCloseable, Cloneable

public final class IncrementalScoreDirector<Solution_,Score_ extends Score<Score_>>
extends AbstractScoreDirector<Solution_,Score_,IncrementalScoreDirectorFactory<Solution_,Score_>>

Incremental java implementation of ScoreDirector, which only recalculates the Score of the part of the working solution that changed, instead of the going through the entire PlanningSolution. This is incremental calculation, which is fast.

See Also:

• ScoreDirector

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	IncrementalScoreDirector.Builder<Solution_,Score_ extends Score<Score_>>

Nested classes/interfaces inherited from class ai.timefold.solver.core.impl.score.director.AbstractScoreDirector

AbstractScoreDirector.AbstractScoreDirectorBuilder<Solution_,Score_ extends Score<Score_>,Factory_ extends AbstractScoreDirectorFactory<Solution_,Score_,Factory_>,Builder_ extends AbstractScoreDirector.AbstractScoreDirectorBuilder<Solution_,Score_,Factory_,Builder_>>

Field Summary

Fields inherited from class ai.timefold.solver.core.impl.score.director.AbstractScoreDirector

constraintMatchPolicy, logger, scoreDirectorFactory, variableListenerSupport, workingSolution

Method Summary

Modifier and Type	Method	Description
void	afterEntityAdded(EntityDescriptor<Solution_> entityDescriptor, Object entity)
void	afterEntityRemoved(EntityDescriptor<Solution_> entityDescriptor, Object entity)
void	afterListVariableChanged(ListVariableDescriptor<Solution_> variableDescriptor, Object entity, int fromIndex, int toIndex)	Notify the score director after a list variable changes.
void	afterListVariableElementAssigned(ListVariableDescriptor<Solution_> variableDescriptor, Object element)	Call this for each element that was assigned (added to a list variable of one entity without being removed from a list variable of another entity).
void	afterListVariableElementUnassigned(ListVariableDescriptor<Solution_> variableDescriptor, Object element)	Call this for each element that was unassigned (removed from a list variable of one entity without being added to a list variable of another entity).
void	afterProblemFactAdded(Object problemFact)
void	afterProblemFactRemoved(Object problemFact)
void	afterProblemPropertyChanged(Object problemFactOrEntity)
void	afterVariableChanged(VariableDescriptor variableDescriptor, Object entity)
void	beforeEntityAdded(EntityDescriptor<Solution_> entityDescriptor, Object entity)
void	beforeEntityRemoved(EntityDescriptor<Solution_> entityDescriptor, Object entity)
void	beforeListVariableChanged(ListVariableDescriptor<Solution_> variableDescriptor, Object entity, int fromIndex, int toIndex)	Notify the score director before a list variable changes.
void	beforeListVariableElementAssigned(ListVariableDescriptor<Solution_> variableDescriptor, Object element)	Call this for each element that will be assigned (added to a list variable of one entity without being removed from a list variable of another entity).
void	beforeListVariableElementUnassigned(ListVariableDescriptor<Solution_> variableDescriptor, Object element)	Call this for each element that will be unassigned (removed from a list variable of one entity without being added to a list variable of another entity).
void	beforeProblemFactAdded(Object problemFact)
void	beforeProblemFactRemoved(Object problemFact)
void	beforeProblemPropertyChanged(Object problemFactOrEntity)
void	beforeVariableChanged(VariableDescriptor variableDescriptor, Object entity)
InnerScore<Score_>	calculateScore()	Calculates the Score and updates the working solution accordingly.
Map<String,ConstraintMatchTotal<Score_>>	getConstraintMatchTotalMap()	Explains the Score of InnerScoreDirector.calculateScore() by splitting it up per Constraint.
IncrementalScoreCalculator<Solution_,Score_>	getIncrementalScoreCalculator()
Map<Object,Indictment<Score_>>	getIndictmentMap()	Explains the impact of each planning entity or problem fact on the Score.
boolean	requiresFlushing()	Some score directors keep a set of changes that they only apply when InnerScoreDirector.calculateScore() is called.
void	setWorkingSolution(Solution_ workingSolution)	The working solution must never be the same instance as the best solution, it should be a (un)changed clone.

Methods inherited from class ai.timefold.solver.core.impl.score.director.AbstractScoreDirector

assertExpectedUndoMoveScore, assertExpectedWorkingScore, assertPredictedScoreFromScratch, assertShadowVariablesAreNotStale, assertWorkingScoreFromScratch, buildScoreCorruptionAnalysis, buildShadowVariableAnalysis, clearVariableListenerEvents, clone, cloneSolution, close, createChildThreadScoreDirector, executeMove, executeTemporaryMove, expectShadowVariablesInCorrectState, forceTriggerVariableListeners, getCalculationCount, getConstraintMatchPolicy, getListVariableStateSupply, getMoveDirector, getScoreDefinition, getScoreDirectorFactory, getSolutionCorruptionAfterUndo, getSolutionDescriptor, getSupplyManager, getVariableDescriptorCache, getWorkingEntityListRevision, getWorkingGenuineEntityCount, getWorkingInitScore, getWorkingSolution, incrementCalculationCount, isConstraintConfiguration, isWorkingEntityListDirty, isWorkingSolutionInitialized, lookUpWorkingObject, lookUpWorkingObjectOrReturnNull, resetCalculationCount, setAllChangesWillBeUndoneBeforeStepEnds, setCalculatedScore, setMoveRepository, setWorkingEntityListDirty, setWorkingSolution, toString, triggerVariableListeners

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ai.timefold.solver.core.impl.score.director.InnerScoreDirector

afterEntityAdded, afterEntityRemoved, beforeEntityAdded, beforeEntityRemoved, buildScoreAnalysis, cloneWorkingSolution, isDerived

Methods inherited from interface ai.timefold.solver.core.impl.score.director.VariableDescriptorAwareScoreDirector

afterListVariableChanged, afterListVariableElementAssigned, afterListVariableElementUnassigned, afterVariableChanged, beforeListVariableChanged, beforeListVariableElementAssigned, beforeListVariableElementUnassigned, beforeVariableChanged, changeVariableFacade

Method Details

getIncrementalScoreCalculator

public IncrementalScoreCalculator<Solution_,Score_> getIncrementalScoreCalculator()

setWorkingSolution

public void setWorkingSolution(Solution_ workingSolution)

Description copied from interface: InnerScoreDirector

The working solution must never be the same instance as the best solution, it should be a (un)changed clone.

Parameters:

workingSolution - never null

calculateScore

public InnerScore<Score_> calculateScore()

Description copied from interface: InnerScoreDirector

Calculates the Score and updates the working solution accordingly.

Returns:

never null, the Score of the working solution

getConstraintMatchTotalMap

public Map<String,ConstraintMatchTotal<Score_>> getConstraintMatchTotalMap()

Description copied from interface: InnerScoreDirector

Explains the Score of InnerScoreDirector.calculateScore() by splitting it up per Constraint.

The sum of ConstraintMatchTotal.getScore() equals InnerScoreDirector.calculateScore().

Call InnerScoreDirector.calculateScore() before calling this method, unless that method has already been called since the last PlanningVariable changes.

Returns:

never null, the key is the constraintId (to create one, use ConstraintRef.composeConstraintId(String, String)). If a constraint is present in the problem but resulted in no matches, it will still be in the map with a ConstraintMatchTotal.getConstraintMatchSet() size of 0.

See Also:

• InnerScoreDirector.getIndictmentMap()

getIndictmentMap

public Map<Object,Indictment<Score_>> getIndictmentMap()

Description copied from interface: InnerScoreDirector

Explains the impact of each planning entity or problem fact on the Score. An Indictment is basically the inverse of a ConstraintMatchTotal: it is a Score total for each constraint justification.

The sum of ConstraintMatchTotal.getScore() differs from InnerScoreDirector.calculateScore() because each ConstraintMatch.getScore() is counted for each constraint justification.

Call InnerScoreDirector.calculateScore() before calling this method, unless that method has already been called since the last PlanningVariable changes.

Returns:

never null, the key is a problem fact or a planning entity

See Also:

• InnerScoreDirector.getConstraintMatchTotalMap()

requiresFlushing

public boolean requiresFlushing()

Description copied from interface: InnerScoreDirector

Some score directors keep a set of changes that they only apply when InnerScoreDirector.calculateScore() is called. Until that happens, this set accumulates and could possibly act as a memory leak.

Returns:

true if the score director can potentially cause a memory leak due to unflushed changes.

beforeEntityAdded

public void beforeEntityAdded(EntityDescriptor<Solution_> entityDescriptor,
 Object entity)

Specified by:

beforeEntityAdded in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Overrides:

beforeEntityAdded in class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,IncrementalScoreDirectorFactory<Solution_,Score_ extends Score<Score_>>>

afterEntityAdded

public void afterEntityAdded(EntityDescriptor<Solution_> entityDescriptor,
 Object entity)

Specified by:

afterEntityAdded in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Overrides:

afterEntityAdded in class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,IncrementalScoreDirectorFactory<Solution_,Score_ extends Score<Score_>>>

beforeVariableChanged

public void beforeVariableChanged(VariableDescriptor variableDescriptor,
 Object entity)

Specified by:

beforeVariableChanged in interface VariableDescriptorAwareScoreDirector<Solution_>

Overrides:

beforeVariableChanged in class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,IncrementalScoreDirectorFactory<Solution_,Score_ extends Score<Score_>>>

afterVariableChanged

public void afterVariableChanged(VariableDescriptor variableDescriptor,
 Object entity)

Specified by:

afterVariableChanged in interface VariableDescriptorAwareScoreDirector<Solution_>

Overrides:

afterVariableChanged in class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,IncrementalScoreDirectorFactory<Solution_,Score_ extends Score<Score_>>>

beforeListVariableElementAssigned

public void beforeListVariableElementAssigned(ListVariableDescriptor<Solution_> variableDescriptor,
 Object element)

Description copied from interface: VariableDescriptorAwareScoreDirector

Call this for each element that will be assigned (added to a list variable of one entity without being removed from a list variable of another entity).

Specified by:

beforeListVariableElementAssigned in interface VariableDescriptorAwareScoreDirector<Solution_>

Overrides:

beforeListVariableElementAssigned in class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,IncrementalScoreDirectorFactory<Solution_,Score_ extends Score<Score_>>>

Parameters:

variableDescriptor - the list variable descriptor

element - the assigned element

afterListVariableElementAssigned

public void afterListVariableElementAssigned(ListVariableDescriptor<Solution_> variableDescriptor,
 Object element)

Description copied from interface: VariableDescriptorAwareScoreDirector

Call this for each element that was assigned (added to a list variable of one entity without being removed from a list variable of another entity).

Specified by:

afterListVariableElementAssigned in interface VariableDescriptorAwareScoreDirector<Solution_>

Overrides:

afterListVariableElementAssigned in class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,IncrementalScoreDirectorFactory<Solution_,Score_ extends Score<Score_>>>

Parameters:

variableDescriptor - the list variable descriptor

element - the assigned element

beforeListVariableElementUnassigned

public void beforeListVariableElementUnassigned(ListVariableDescriptor<Solution_> variableDescriptor,
 Object element)

Description copied from interface: VariableDescriptorAwareScoreDirector

Call this for each element that will be unassigned (removed from a list variable of one entity without being added to a list variable of another entity).

Specified by:

beforeListVariableElementUnassigned in interface VariableDescriptorAwareScoreDirector<Solution_>

Overrides:

beforeListVariableElementUnassigned in class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,IncrementalScoreDirectorFactory<Solution_,Score_ extends Score<Score_>>>

Parameters:

variableDescriptor - the list variable descriptor

element - the unassigned element

afterListVariableElementUnassigned

public void afterListVariableElementUnassigned(ListVariableDescriptor<Solution_> variableDescriptor,
 Object element)

Description copied from interface: VariableDescriptorAwareScoreDirector

Call this for each element that was unassigned (removed from a list variable of one entity without being added to a list variable of another entity).

Specified by:

afterListVariableElementUnassigned in interface VariableDescriptorAwareScoreDirector<Solution_>

Overrides:

afterListVariableElementUnassigned in class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,IncrementalScoreDirectorFactory<Solution_,Score_ extends Score<Score_>>>

Parameters:

variableDescriptor - the list variable descriptor

element - the unassigned element

beforeListVariableChanged

public void beforeListVariableChanged(ListVariableDescriptor<Solution_> variableDescriptor,
 Object entity,
 int fromIndex,
 int toIndex)

Description copied from interface: VariableDescriptorAwareScoreDirector

Notify the score director before a list variable changes.

The list variable change includes:

• Changing position (index) of one or more elements.
• Removing one or more elements from the list variable.
• Adding one or more elements to the list variable.
• Any mix of the above.

For the sake of variable listeners' efficiency, the change notification requires an index range that contains elements affected by the change. The range starts at fromIndex (inclusive) and ends at toIndex (exclusive).

The range has to comply with the following contract:

1. fromIndex must be greater than or equal to 0; toIndex must be less than or equal to the list variable size.
2. toIndex must be greater than or equal to fromIndex.
3. The range must contain all elements that are going to be changed.
4. The range is allowed to contain elements that are not going to be changed.
5. The range may be empty (fromIndex equals toIndex) if none of the existing list variable elements are going to be changed.

VariableDescriptorAwareScoreDirector.beforeListVariableElementUnassigned(ListVariableDescriptor, Object) must be called for each element that will be unassigned (removed from a list variable of one entity without being added to a list variable of another entity).

Specified by:

beforeListVariableChanged in interface VariableDescriptorAwareScoreDirector<Solution_>

Overrides:

beforeListVariableChanged in class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,IncrementalScoreDirectorFactory<Solution_,Score_ extends Score<Score_>>>

Parameters:

variableDescriptor - descriptor of the list variable being changed

entity - the entity owning the list variable being changed

fromIndex - low endpoint (inclusive) of the changed range

toIndex - high endpoint (exclusive) of the changed range

afterListVariableChanged

public void afterListVariableChanged(ListVariableDescriptor<Solution_> variableDescriptor,
 Object entity,
 int fromIndex,
 int toIndex)

Description copied from interface: VariableDescriptorAwareScoreDirector

Notify the score director after a list variable changes.

The list variable change includes:

• Changing position (index) of one or more elements.
• Removing one or more elements from the list variable.
• Adding one or more elements to the list variable.
• Any mix of the above.

For the sake of variable listeners' efficiency, the change notification requires an index range that contains elements affected by the change. The range starts at fromIndex (inclusive) and ends at toIndex (exclusive).

The range has to comply with the following contract:

1. fromIndex must be greater than or equal to 0; toIndex must be less than or equal to the list variable size.
2. toIndex must be greater than or equal to fromIndex.
3. The range must contain all elements that have changed.
4. The range is allowed to contain elements that have not changed.
5. The range may be empty (fromIndex equals toIndex) if none of the existing list variable elements have changed.

VariableDescriptorAwareScoreDirector.afterListVariableElementUnassigned(ListVariableDescriptor, Object) must be called for each element that was unassigned (removed from a list variable of one entity without being added to a list variable of another entity).

Specified by:

afterListVariableChanged in interface VariableDescriptorAwareScoreDirector<Solution_>

Overrides:

afterListVariableChanged in class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,IncrementalScoreDirectorFactory<Solution_,Score_ extends Score<Score_>>>

Parameters:

variableDescriptor - descriptor of the list variable being changed

entity - the entity owning the list variable being changed

fromIndex - low endpoint (inclusive) of the changed range

toIndex - high endpoint (exclusive) of the changed range

beforeEntityRemoved

public void beforeEntityRemoved(EntityDescriptor<Solution_> entityDescriptor,
 Object entity)

Specified by:

beforeEntityRemoved in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Overrides:

beforeEntityRemoved in class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,IncrementalScoreDirectorFactory<Solution_,Score_ extends Score<Score_>>>

afterEntityRemoved

public void afterEntityRemoved(EntityDescriptor<Solution_> entityDescriptor,
 Object entity)

Specified by:

afterEntityRemoved in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Overrides:

afterEntityRemoved in class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,IncrementalScoreDirectorFactory<Solution_,Score_ extends Score<Score_>>>

beforeProblemFactAdded

public void beforeProblemFactAdded(Object problemFact)

Specified by:

beforeProblemFactAdded in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Specified by:

beforeProblemFactAdded in interface ScoreDirector<Solution_>

Overrides:

beforeProblemFactAdded in class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,IncrementalScoreDirectorFactory<Solution_,Score_ extends Score<Score_>>>

afterProblemFactAdded

public void afterProblemFactAdded(Object problemFact)

Specified by:

afterProblemFactAdded in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Specified by:

afterProblemFactAdded in interface ScoreDirector<Solution_>

Overrides:

afterProblemFactAdded in class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,IncrementalScoreDirectorFactory<Solution_,Score_ extends Score<Score_>>>

beforeProblemPropertyChanged

public void beforeProblemPropertyChanged(Object problemFactOrEntity)

Specified by:

beforeProblemPropertyChanged in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Specified by:

beforeProblemPropertyChanged in interface ScoreDirector<Solution_>

Overrides:

beforeProblemPropertyChanged in class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,IncrementalScoreDirectorFactory<Solution_,Score_ extends Score<Score_>>>

afterProblemPropertyChanged

public void afterProblemPropertyChanged(Object problemFactOrEntity)

Specified by:

afterProblemPropertyChanged in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Specified by:

afterProblemPropertyChanged in interface ScoreDirector<Solution_>

Overrides:

afterProblemPropertyChanged in class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,IncrementalScoreDirectorFactory<Solution_,Score_ extends Score<Score_>>>

beforeProblemFactRemoved

public void beforeProblemFactRemoved(Object problemFact)

Specified by:

beforeProblemFactRemoved in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Specified by:

beforeProblemFactRemoved in interface ScoreDirector<Solution_>

Overrides:

beforeProblemFactRemoved in class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,IncrementalScoreDirectorFactory<Solution_,Score_ extends Score<Score_>>>

afterProblemFactRemoved

public void afterProblemFactRemoved(Object problemFact)

Specified by:

afterProblemFactRemoved in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Specified by:

afterProblemFactRemoved in interface ScoreDirector<Solution_>

Overrides:

afterProblemFactRemoved in class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,IncrementalScoreDirectorFactory<Solution_,Score_ extends Score<Score_>>>