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

Interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Type Parameters:

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

Score_ - the score type to go with the solution

All Superinterfaces:

AutoCloseable, ScoreDirector<Solution_>, VariableDescriptorAwareScoreDirector<Solution_>

All Known Implementing Classes:

AbstractScoreDirector, BavetConstraintStreamScoreDirector, EasyScoreDirector, IncrementalScoreDirector

public interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>
extends VariableDescriptorAwareScoreDirector<Solution_>, AutoCloseable

Method Summary

Modifier and Type	Method	Description
void	afterEntityAdded(EntityDescriptor<Solution_> entityDescriptor, Object entity)
default void	afterEntityAdded(Object entity)
void	afterEntityRemoved(EntityDescriptor<Solution_> entityDescriptor, Object entity)
default void	afterEntityRemoved(Object entity)
void	afterProblemFactAdded(Object problemFact)
void	afterProblemFactRemoved(Object problemFact)
void	afterProblemPropertyChanged(Object problemFactOrEntity)
void	assertExpectedUndoMoveScore(Move<Solution_> move, InnerScore<Score_> beforeMoveScore, SolverLifecyclePoint executionPoint)	Asserts that if the Score is calculated for the current working solution in the current ScoreDirector (with incremental calculation residue), it is equal to the parameter beforeMoveScore.
void	assertExpectedWorkingScore(InnerScore<Score_> expectedWorkingScore, Object completedAction)	Asserts that if the Score is calculated for the current working solution in the current ScoreDirector (with possibly incremental calculation residue), it is equal to the parameter expectedWorkingScore.
void	assertPredictedScoreFromScratch(InnerScore<Score_> predictedScore, Object completedAction)	Asserts that if the Score is calculated for the current working solution in a fresh ScoreDirector (with no incremental calculation residue), it is equal to the parameter predictedScore.
void	assertShadowVariablesAreNotStale(InnerScore<Score_> expectedWorkingScore, Object completedAction)	Asserts that if all VariableListeners are forcibly triggered, and therefore all shadow variables are updated if needed, that none of the shadow variables of the working solution change, Then also asserts that the Score calculated for the working solution afterwards is equal to the parameter expectedWorkingScore.
void	assertWorkingScoreFromScratch(InnerScore<Score_> workingScore, Object completedAction)	Asserts that if the Score is calculated for the current working solution in a fresh ScoreDirector (with no incremental calculation residue), it is equal to the parameter workingScore.
void	beforeEntityAdded(EntityDescriptor<Solution_> entityDescriptor, Object entity)
default void	beforeEntityAdded(Object entity)
void	beforeEntityRemoved(EntityDescriptor<Solution_> entityDescriptor, Object entity)
default void	beforeEntityRemoved(Object entity)
void	beforeProblemFactAdded(Object problemFact)
void	beforeProblemFactRemoved(Object problemFact)
void	beforeProblemPropertyChanged(Object problemFactOrEntity)
default ScoreAnalysis<Score_>	buildScoreAnalysis(ScoreAnalysisFetchPolicy scoreAnalysisFetchPolicy)
InnerScore<Score_>	calculateScore()	Calculates the Score and updates the working solution accordingly.
Solution_	cloneSolution(Solution_ originalSolution)	Returns a planning clone of the solution, which is not a shallow clone nor a deep clone nor a partition clone.
default Solution_	cloneWorkingSolution()	Returns a planning clone of the solution, which is not a shallow clone nor a deep clone nor a partition clone.
void	close()	Needs to be called after use because some implementations need to clean up their resources.
InnerScoreDirector<Solution_,Score_>	createChildThreadScoreDirector(ChildThreadType childThreadType)
void	executeMove(Move<Solution_> move)
InnerScore<Score_>	executeTemporaryMove(Move<Solution_> move, boolean assertMoveScoreFromScratch)	Executes a move, finds out its score, and immediately undoes it.
boolean	expectShadowVariablesInCorrectState()	Inverse shadow variables have a fail-fast for cases where the shadow variable doesn't actually point to its correct inverse.
void	forceTriggerVariableListeners()	Unlike ScoreDirector.triggerVariableListeners() which only triggers notifications already in the queue, this triggers every variable listener on every genuine variable.
long	getCalculationCount()
static <Score_ extends Score<Score_>> ConstraintAnalysis<Score_>	getConstraintAnalysis(ConstraintMatchTotal<Score_> constraintMatchTotal, ScoreAnalysisFetchPolicy scoreAnalysisFetchPolicy)
ConstraintMatchPolicy	getConstraintMatchPolicy()
Map<String,ConstraintMatchTotal<Score_>>	getConstraintMatchTotalMap()	Explains the Score of calculateScore() by splitting it up per Constraint.
Map<Object,Indictment<Score_>>	getIndictmentMap()	Explains the impact of each planning entity or problem fact on the Score.
ListVariableStateSupply<Solution_>	getListVariableStateSupply(ListVariableDescriptor<Solution_> variableDescriptor)
MoveDirector<Solution_,Score_>	getMoveDirector()
ScoreDefinition<Score_>	getScoreDefinition()
ScoreDirectorFactory<Solution_,Score_>	getScoreDirectorFactory()
SolutionDescriptor<Solution_>	getSolutionDescriptor()
SupplyManager	getSupplyManager()
long	getWorkingEntityListRevision()
int	getWorkingGenuineEntityCount()
int	getWorkingInitScore()
void	incrementCalculationCount()
default boolean	isDerived()	A derived score director is created from a root score director.
boolean	isWorkingEntityListDirty(long expectedWorkingEntityListRevision)
boolean	isWorkingSolutionInitialized()
boolean	requiresFlushing()	Some score directors keep a set of changes that they only apply when calculateScore() is called.
void	resetCalculationCount()
void	setAllChangesWillBeUndoneBeforeStepEnds(boolean allChangesWillBeUndoneBeforeStepEnds)	Do not waste performance by propagating changes to step (or higher) mechanisms.
void	setMoveRepository(@Nullable MoveRepository<Solution_> moveRepository)	Different phases may need different move repositories, as they may be based on different sets of moves.
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 interface ai.timefold.solver.core.api.score.director.ScoreDirector

getWorkingSolution, lookUpWorkingObject, lookUpWorkingObjectOrReturnNull, triggerVariableListeners

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

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

Method Details

getConstraintAnalysis

static <Score_ extends Score<Score_>>
ConstraintAnalysis<Score_> getConstraintAnalysis(ConstraintMatchTotal<Score_> constraintMatchTotal,
 ScoreAnalysisFetchPolicy scoreAnalysisFetchPolicy)

setWorkingSolution

void setWorkingSolution(Solution_ workingSolution)

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

Parameters:

workingSolution - never null

setMoveRepository

void setMoveRepository(@Nullable MoveRepository<Solution_> moveRepository)

Different phases may need different move repositories, as they may be based on different sets of moves. Therefore move repository cannot be injected at score director construction time. A phase may not need a move repository at all, such as construction heuristics, which currently does not support Move Streams. Each phase is responsible for calling this method to set its repository, and also calling it again at the end to null it out.

calculateScore

InnerScore<Score_> calculateScore()

Calculates the Score and updates the working solution accordingly.

Returns:

never null, the Score of the working solution

getConstraintMatchPolicy

ConstraintMatchPolicy getConstraintMatchPolicy()

Returns:

ConstraintMatchPolicy.ENABLED if getConstraintMatchTotalMap() and getIndictmentMap() can be called. ConstraintMatchPolicy.ENABLED_WITHOUT_JUSTIFICATIONS if only the former can be called. ConstraintMatchPolicy.DISABLED if neither can be called.

getConstraintMatchTotalMap

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

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

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

Call 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.

Throws:

IllegalStateException - if getConstraintMatchPolicy() returns ConstraintMatchPolicy.DISABLED.

See Also:

• getIndictmentMap()

getIndictmentMap

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

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 calculateScore() because each ConstraintMatch.getScore() is counted for each constraint justification.

Call 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

Throws:

IllegalStateException - unless getConstraintMatchPolicy() returns ConstraintMatchPolicy.ENABLED.

See Also:

• getConstraintMatchTotalMap()

getWorkingEntityListRevision

long getWorkingEntityListRevision()

Returns:

used to check isWorkingEntityListDirty(long) later on

getWorkingGenuineEntityCount

int getWorkingGenuineEntityCount()

getWorkingInitScore

int getWorkingInitScore()

executeMove

void executeMove(Move<Solution_> move)

executeTemporaryMove

InnerScore<Score_> executeTemporaryMove(Move<Solution_> move,
 boolean assertMoveScoreFromScratch)

Executes a move, finds out its score, and immediately undoes it.

Parameters:

move - never null

assertMoveScoreFromScratch - true will hurt performance

Returns:

never null

isWorkingEntityListDirty

boolean isWorkingEntityListDirty(long expectedWorkingEntityListRevision)

Parameters:

expectedWorkingEntityListRevision - an

Returns:

true if the entityList might have a different set of instances now

isWorkingSolutionInitialized

boolean isWorkingSolutionInitialized()

requiresFlushing

boolean requiresFlushing()

Some score directors keep a set of changes that they only apply when 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.

expectShadowVariablesInCorrectState

boolean expectShadowVariablesInCorrectState()

Inverse shadow variables have a fail-fast for cases where the shadow variable doesn't actually point to its correct inverse. This is very useful to pinpoint improperly initialized solutions.

However, SolutionManager.update(Object) exists precisely for the purpose of initializing solutions. And when this API is used, the fail-fast must not be triggered as it is guaranteed and expected that the inverse relationships will be wrong. In fact, they will be null.

For this case and this case only, this method is allowed to return false. All other cases must return true, otherwise a very valuable fail-fast is lost.

Returns:

false if the fail-fast on shadow variables should not be triggered

getScoreDirectorFactory

ScoreDirectorFactory<Solution_,Score_> getScoreDirectorFactory()

Returns:

never null

getSolutionDescriptor

SolutionDescriptor<Solution_> getSolutionDescriptor()

Specified by:

getSolutionDescriptor in interface VariableDescriptorAwareScoreDirector<Solution_>

Returns:

never null

getScoreDefinition

ScoreDefinition<Score_> getScoreDefinition()

Returns:

never null

cloneWorkingSolution

default Solution_ cloneWorkingSolution()

Returns a planning clone of the solution, which is not a shallow clone nor a deep clone nor a partition clone.

Returns:

never null, planning clone

cloneSolution

Solution_ cloneSolution(Solution_ originalSolution)

Returns a planning clone of the solution, which is not a shallow clone nor a deep clone nor a partition clone.

Parameters:

originalSolution - never null

Returns:

never null, planning clone

getCalculationCount

long getCalculationCount()

Returns:

at least 0L

resetCalculationCount

void resetCalculationCount()

incrementCalculationCount

void incrementCalculationCount()

getSupplyManager

SupplyManager getSupplyManager()

Returns:

never null

getMoveDirector

MoveDirector<Solution_,Score_> getMoveDirector()

getListVariableStateSupply

ListVariableStateSupply<Solution_> getListVariableStateSupply(ListVariableDescriptor<Solution_> variableDescriptor)

createChildThreadScoreDirector

InnerScoreDirector<Solution_,Score_> createChildThreadScoreDirector(ChildThreadType childThreadType)

setAllChangesWillBeUndoneBeforeStepEnds

void setAllChangesWillBeUndoneBeforeStepEnds(boolean allChangesWillBeUndoneBeforeStepEnds)

Do not waste performance by propagating changes to step (or higher) mechanisms.

Parameters:

allChangesWillBeUndoneBeforeStepEnds - true if all changes will be undone

assertExpectedWorkingScore

void assertExpectedWorkingScore(InnerScore<Score_> expectedWorkingScore,
 Object completedAction)

Asserts that if the Score is calculated for the current working solution in the current ScoreDirector (with possibly incremental calculation residue), it is equal to the parameter expectedWorkingScore.

Used to assert that skipping calculateScore() (when the score is otherwise determined) is correct.

Parameters:

expectedWorkingScore - never null

completedAction - sometimes null, when assertion fails then the completedAction's Object.toString() is included in the exception message

assertShadowVariablesAreNotStale

void assertShadowVariablesAreNotStale(InnerScore<Score_> expectedWorkingScore,
 Object completedAction)

Asserts that if all VariableListeners are forcibly triggered, and therefore all shadow variables are updated if needed, that none of the shadow variables of the working solution change, Then also asserts that the Score calculated for the working solution afterwards is equal to the parameter expectedWorkingScore.

Used to assert that the shadow variables' state is consistent with the genuine variables' state.

Parameters:

expectedWorkingScore - never null

completedAction - sometimes null, when assertion fails then the completedAction's Object.toString() is included in the exception message

assertWorkingScoreFromScratch

void assertWorkingScoreFromScratch(InnerScore<Score_> workingScore,
 Object completedAction)

Asserts that if the Score is calculated for the current working solution in a fresh ScoreDirector (with no incremental calculation residue), it is equal to the parameter workingScore.

Furthermore, if the assert fails, a score corruption analysis might be included in the exception message.

Parameters:

workingScore - never null

completedAction - sometimes null, when assertion fails then the completedAction's Object.toString() is included in the exception message

See Also:

• ScoreDirectorFactory.assertScoreFromScratch(Solution_)

assertPredictedScoreFromScratch

void assertPredictedScoreFromScratch(InnerScore<Score_> predictedScore,
 Object completedAction)

Asserts that if the Score is calculated for the current working solution in a fresh ScoreDirector (with no incremental calculation residue), it is equal to the parameter predictedScore.

Furthermore, if the assert fails, a score corruption analysis might be included in the exception message.

Parameters:

predictedScore - never null

completedAction - sometimes null, when assertion fails then the completedAction's Object.toString() is included in the exception message

See Also:

• ScoreDirectorFactory.assertScoreFromScratch(Solution_)

assertExpectedUndoMoveScore

void assertExpectedUndoMoveScore(Move<Solution_> move,
 InnerScore<Score_> beforeMoveScore,
 SolverLifecyclePoint executionPoint)

Asserts that if the Score is calculated for the current working solution in the current ScoreDirector (with incremental calculation residue), it is equal to the parameter beforeMoveScore.

Furthermore, if the assert fails, a score corruption analysis might be included in the exception message.

Parameters:

move - never null

beforeMoveScore - never null

close

void close()

Needs to be called after use because some implementations need to clean up their resources.

Specified by:

close in interface AutoCloseable

forceTriggerVariableListeners

void forceTriggerVariableListeners()

Unlike ScoreDirector.triggerVariableListeners() which only triggers notifications already in the queue, this triggers every variable listener on every genuine variable. This is useful in SolutionManager.update(Object) to fill in shadow variable values.

isDerived

default boolean isDerived()

A derived score director is created from a root score director. The derived score director can be used to create separate* instances for use cases like multithreaded solving.

buildScoreAnalysis

default ScoreAnalysis<Score_> buildScoreAnalysis(ScoreAnalysisFetchPolicy scoreAnalysisFetchPolicy)

beforeEntityAdded

default void beforeEntityAdded(Object entity)

Specified by:

beforeEntityAdded in interface ScoreDirector<Solution_>

beforeEntityAdded

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

afterEntityAdded

default void afterEntityAdded(Object entity)

Specified by:

afterEntityAdded in interface ScoreDirector<Solution_>

afterEntityAdded

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

beforeEntityRemoved

default void beforeEntityRemoved(Object entity)

Specified by:

beforeEntityRemoved in interface ScoreDirector<Solution_>

beforeEntityRemoved

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

afterEntityRemoved

default void afterEntityRemoved(Object entity)

Specified by:

afterEntityRemoved in interface ScoreDirector<Solution_>

afterEntityRemoved

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

beforeProblemFactAdded

void beforeProblemFactAdded(Object problemFact)

Specified by:

beforeProblemFactAdded in interface ScoreDirector<Solution_>

afterProblemFactAdded

void afterProblemFactAdded(Object problemFact)

Specified by:

afterProblemFactAdded in interface ScoreDirector<Solution_>

beforeProblemPropertyChanged

void beforeProblemPropertyChanged(Object problemFactOrEntity)

Specified by:

beforeProblemPropertyChanged in interface ScoreDirector<Solution_>

afterProblemPropertyChanged

void afterProblemPropertyChanged(Object problemFactOrEntity)

Specified by:

afterProblemPropertyChanged in interface ScoreDirector<Solution_>

beforeProblemFactRemoved

void beforeProblemFactRemoved(Object problemFact)

Specified by:

beforeProblemFactRemoved in interface ScoreDirector<Solution_>

afterProblemFactRemoved

void afterProblemFactRemoved(Object problemFact)

Specified by:

afterProblemFactRemoved in interface ScoreDirector<Solution_>