Package ai.timefold.solver.core.api.score

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

Type Parameters:

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

Score_ - the actual score type

All Known Implementing Classes:

DefaultScoreExplanation

public interface ScoreExplanation<Solution_,Score_ extends Score<Score_>>

Build by SolutionManager.explain(Object) to hold ConstraintMatchTotals and Indictments necessary to explain the quality of a particular Score.

For a simplified, faster and JSON-friendly alternative, see ScoreAnalysis.

Method Summary

Modifier and Type	Method	Description
@NonNull Map<String,ConstraintMatchTotal<Score_>>	getConstraintMatchTotalMap()	Explains the Score of getScore() by splitting it up per Constraint.
@NonNull Map<Object,Indictment<Score_>>	getIndictmentMap()	Explains the impact of each planning entity or problem fact on the Score.
@NonNull List<ConstraintJustification>	getJustificationList()	Explains the Score of getScore() for all constraints.
default <ConstraintJustification_ extends ConstraintJustification> @NonNull List<ConstraintJustification_>	getJustificationList(@NonNull Class<? extends ConstraintJustification_> constraintJustificationClass)	Explains the Score of getScore() for all constraints justified with a given ConstraintJustification type.
@NonNull Score_	getScore()	Return the Score being explained.
@NonNull Solution_	getSolution()	Retrieve the PlanningSolution that the score being explained comes from.
@NonNull String	getSummary()	Returns a diagnostic text that explains the solution through the ConstraintMatch API to identify which constraints or planning entities cause that score quality.
boolean	isInitialized()	Whether getSolution() is initialized or not.

Method Details

getSolution

@NonNull Solution_ getSolution()

Retrieve the PlanningSolution that the score being explained comes from.

getScore

@NonNull Score_ getScore()

Return the Score being explained. If the specific Score type used by the PlanningSolution is required, call getSolution() and retrieve it from there.

isInitialized

boolean isInitialized()

Whether getSolution() is initialized or not.

Returns:

true if initialized

getSummary

@NonNull String getSummary()

Returns a diagnostic text that explains the solution through the ConstraintMatch API to identify which constraints or planning entities cause that score quality.

In case of an infeasible solution, this can help diagnose the cause of that.

Do not parse the return value, its format may change without warning. Instead, to provide this information in a UI or a service, use getConstraintMatchTotalMap() and getIndictmentMap() and convert those into a domain-specific API.

getConstraintMatchTotalMap

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

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

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

Returns:

the key is the constraintId (to create one, use ConstraintRef.composeConstraintId(String, String)).

See Also:

• getIndictmentMap()

getJustificationList

@NonNull List<ConstraintJustification> getJustificationList()

Explains the Score of getScore() for all constraints. The return value of this method is determined by several factors:

• With Constraint Streams, the user has an option to provide a custom justification mapping, implementing ConstraintJustification. If provided, every ConstraintMatch of such constraint will be associated with this custom justification class. Every constraint not associated with a custom justification class will be associated with DefaultConstraintJustification.
• With ConstraintMatchAwareIncrementalScoreCalculator, every ConstraintMatch will be associated with the justification class that the user created it with.

Returns:

all constraint matches

See Also:

• getIndictmentMap()

getJustificationList

default <ConstraintJustification_ extends ConstraintJustification>
@NonNull List<ConstraintJustification_> getJustificationList(@NonNull Class<? extends ConstraintJustification_> constraintJustificationClass)

Explains the Score of getScore() for all constraints justified with a given ConstraintJustification type. Otherwise, as defined by getJustificationList(). May be empty, if the score explanation ran with justification support disabled.

Returns:

all constraint matches associated with the given justification class

See Also:

• getIndictmentMap()

getIndictmentMap

@NonNull 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 any of the indicted objects.

The sum of ConstraintMatchTotal.getScore() differs from getScore() because each ConstraintMatch.getScore() is counted for each of the indicted objects.

Returns:

the key is a problem fact or a planning entity

See Also:

• getConstraintMatchTotalMap()