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

Interface SolutionManager<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:

DefaultSolutionManager

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

A stateless service to help calculate Score, ConstraintMatchTotal, Indictment, etc.

To create a SolutionManager instance, use create(SolverFactory).

These methods are thread-safe unless explicitly stated otherwise.

Method Summary

Modifier and Type	Method	Description
default ScoreAnalysis<Score_>	analyze(Solution_ solution)	As defined by analyze(Object, ScoreAnalysisFetchPolicy, SolutionUpdatePolicy), using SolutionUpdatePolicy.UPDATE_ALL and ScoreAnalysisFetchPolicy.FETCH_ALL.
default ScoreAnalysis<Score_>	analyze(Solution_ solution, ScoreAnalysisFetchPolicy fetchPolicy)	As defined by analyze(Object, ScoreAnalysisFetchPolicy, SolutionUpdatePolicy), using SolutionUpdatePolicy.UPDATE_ALL.
ScoreAnalysis<Score_>	analyze(Solution_ solution, ScoreAnalysisFetchPolicy fetchPolicy, SolutionUpdatePolicy solutionUpdatePolicy)	Calculates and retrieves information about which constraints contributed to the solution's score.
static <Solution_, Score_ extends Score<Score_>> SolutionManager<Solution_,Score_>	create(SolverFactory<Solution_> solverFactory)	Uses a SolverFactory to build a SolutionManager.
static <Solution_, Score_ extends Score<Score_>, ProblemId_> SolutionManager<Solution_,Score_>	create(SolverManager<Solution_,ProblemId_> solverManager)	Uses a SolverManager to build a SolutionManager.
default ScoreExplanation<Solution_,Score_>	explain(Solution_ solution)	As defined by explain(Object, SolutionUpdatePolicy), using SolutionUpdatePolicy.UPDATE_ALL.
ScoreExplanation<Solution_,Score_>	explain(Solution_ solution, SolutionUpdatePolicy solutionUpdatePolicy)	Calculates and retrieves ConstraintMatchTotals and Indictments necessary for describing the quality of a particular solution.
default <EntityOrElement_, Proposition_> List<RecommendedAssignment<Proposition_,Score_>>	recommendAssignment(Solution_ solution, EntityOrElement_ evaluatedEntityOrElement, Function<EntityOrElement_,Proposition_> propositionFunction)	As defined by recommendAssignment(Object, Object, Function, ScoreAnalysisFetchPolicy), with ScoreAnalysisFetchPolicy.FETCH_ALL.
<EntityOrElement_, Proposition_> List<RecommendedAssignment<Proposition_,Score_>>	recommendAssignment(Solution_ solution, EntityOrElement_ evaluatedEntityOrElement, Function<EntityOrElement_,Proposition_> propositionFunction, ScoreAnalysisFetchPolicy fetchPolicy)	Quickly runs through all possible options of assigning a given entity or element in a given solution, and returns a list of recommendations sorted by score, with most favorable score first.
default <EntityOrElement_, Proposition_> List<RecommendedFit<Proposition_,Score_>>	recommendFit(Solution_ solution, EntityOrElement_ fittedEntityOrElement, Function<EntityOrElement_,Proposition_> propositionFunction)	Deprecated, for removal: This API element is subject to removal in a future version. Prefer recommendAssignment(Object, Object, Function, ScoreAnalysisFetchPolicy).
<EntityOrElement_, Proposition_> List<RecommendedFit<Proposition_,Score_>>	recommendFit(Solution_ solution, EntityOrElement_ fittedEntityOrElement, Function<EntityOrElement_,Proposition_> propositionFunction, ScoreAnalysisFetchPolicy fetchPolicy)	Deprecated, for removal: This API element is subject to removal in a future version. Prefer recommendAssignment(Object, Object, Function, ScoreAnalysisFetchPolicy).
default Score_	update(Solution_ solution)	As defined by update(Object, SolutionUpdatePolicy), using SolutionUpdatePolicy.UPDATE_ALL.
Score_	update(Solution_ solution, SolutionUpdatePolicy solutionUpdatePolicy)	Updates the given solution according to the SolutionUpdatePolicy.

Method Details

create

static <Solution_,
Score_ extends Score<Score_>>
SolutionManager<Solution_,Score_> create(SolverFactory<Solution_> solverFactory)

Uses a SolverFactory to build a SolutionManager.

Type Parameters:

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

Score_ - the actual score type

Parameters:

solverFactory - never null

Returns:

never null

create

static <Solution_,
Score_ extends Score<Score_>,
ProblemId_>
SolutionManager<Solution_,Score_> create(SolverManager<Solution_,ProblemId_> solverManager)

Uses a SolverManager to build a SolutionManager.

Type Parameters:

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

Score_ - the actual score type

ProblemId_ - the ID type of a submitted problem, such as Long or UUID

Parameters:

solverManager - never null

Returns:

never null

update

default Score_ update(Solution_ solution)

As defined by update(Object, SolutionUpdatePolicy), using SolutionUpdatePolicy.UPDATE_ALL.

update

Score_ update(Solution_ solution,
 SolutionUpdatePolicy solutionUpdatePolicy)

Updates the given solution according to the SolutionUpdatePolicy.

Parameters:

solution - never null

solutionUpdatePolicy - never null; if unsure, pick SolutionUpdatePolicy.UPDATE_ALL

Returns:

possibly null if already null and SolutionUpdatePolicy didn't cause its update

See Also:

• Description of individual policies with respect to performance trade-offs.

explain

default ScoreExplanation<Solution_,Score_> explain(Solution_ solution)

As defined by explain(Object, SolutionUpdatePolicy), using SolutionUpdatePolicy.UPDATE_ALL.

explain

ScoreExplanation<Solution_,Score_> explain(Solution_ solution,
 SolutionUpdatePolicy solutionUpdatePolicy)

Calculates and retrieves ConstraintMatchTotals and Indictments necessary for describing the quality of a particular solution. For a simplified, faster and JSON-friendly alternative, see analyze(Object)}.

Parameters:

solution - never null

solutionUpdatePolicy - never null; if unsure, pick SolutionUpdatePolicy.UPDATE_ALL

Returns:

never null

Throws:

IllegalStateException - when constraint matching is disabled or not supported by the underlying score calculator, such as EasyScoreCalculator.

See Also:

• Description of individual policies with respect to performance trade-offs.

analyze

default ScoreAnalysis<Score_> analyze(Solution_ solution)

As defined by analyze(Object, ScoreAnalysisFetchPolicy, SolutionUpdatePolicy), using SolutionUpdatePolicy.UPDATE_ALL and ScoreAnalysisFetchPolicy.FETCH_ALL.

analyze

default ScoreAnalysis<Score_> analyze(Solution_ solution,
 ScoreAnalysisFetchPolicy fetchPolicy)

As defined by analyze(Object, ScoreAnalysisFetchPolicy, SolutionUpdatePolicy), using SolutionUpdatePolicy.UPDATE_ALL.

analyze

ScoreAnalysis<Score_> analyze(Solution_ solution,
 ScoreAnalysisFetchPolicy fetchPolicy,
 SolutionUpdatePolicy solutionUpdatePolicy)

Calculates and retrieves information about which constraints contributed to the solution's score. This is a faster, JSON-friendly version of explain(Object).

Parameters:

solution - never null, must be fully initialized otherwise an exception is thrown

fetchPolicy - never null; if unsure, pick ScoreAnalysisFetchPolicy.FETCH_ALL

solutionUpdatePolicy - never null; if unsure, pick SolutionUpdatePolicy.UPDATE_ALL

Returns:

never null

Throws:

IllegalStateException - when constraint matching is disabled or not supported by the underlying score calculator, such as EasyScoreCalculator.

See Also:

• Description of individual policies with respect to performance trade-offs.

recommendAssignment

default <EntityOrElement_,
Proposition_>
List<RecommendedAssignment<Proposition_,Score_>> recommendAssignment(Solution_ solution,
 EntityOrElement_ evaluatedEntityOrElement,
 Function<EntityOrElement_,Proposition_> propositionFunction)

As defined by recommendAssignment(Object, Object, Function, ScoreAnalysisFetchPolicy), with ScoreAnalysisFetchPolicy.FETCH_ALL.

recommendAssignment

<EntityOrElement_,
Proposition_>
List<RecommendedAssignment<Proposition_,Score_>> recommendAssignment(Solution_ solution,
 EntityOrElement_ evaluatedEntityOrElement,
 Function<EntityOrElement_,Proposition_> propositionFunction,
 ScoreAnalysisFetchPolicy fetchPolicy)

Quickly runs through all possible options of assigning a given entity or element in a given solution, and returns a list of recommendations sorted by score, with most favorable score first. The input solution must either be fully initialized, or have a single entity or element unassigned.

For problems with only basic planning variables or with chained planning variables, the fitted element is a planning entity of the problem. Each available planning value will be tested by setting it to the planning variable in question. For problems with a list variable, the evaluated element may be a shadow entity, and it will be tested in each position of the planning list variable.

The score returned by RecommendedAssignment.scoreAnalysisDiff() is the difference between the score of the solution before and after fitting. Every recommendation will be in a state as if the solution was never changed; if it references entities, none of their genuine planning variables or shadow planning variables will be initialized. The input solution will be unchanged.

This method does not call local search, it runs a fast greedy algorithm instead. The construction heuristic configuration from the solver configuration is used. If not present, the default construction heuristic configuration is used. This means that the API will fail if the solver config requires custom initialization phase. In this case, it will fail either directly by throwing an exception, or indirectly by not providing correct data.

When an element is tested, a score is calculated over the entire solution with the element in place, also called a placement. The proposition function is also called at that time, allowing the user to extract any information from the current placement; the extracted information is called the proposition. After the proposition is extracted, the solution is returned to its original state, resetting all changes made by the fitting. This has a major consequence for the proposition, if it is a planning entity: planning entities contain live data in their planning variables, and that data will be erased when the next placement is tested for fit. In this case, the proposition function needs to make defensive copies of everything it wants to return, such as values of shadow variables etc.

Example: Consider a planning entity Shift, with a variable "employee". Let's assume we have two employees to test for fit, Ann and Bob, and a single Shift instance to fit them into, mondayShift. The proposition function will be called twice, once as mondayShift@Ann and once as mondayShift@Bob. Let's assume the proposition function returns the Shift instance in its entirety. This is what will happen:

1. Calling propositionFunction on mondayShift@Ann results in proposition P1: mondayShift@Ann
2. Placement is cleared, mondayShift@Bob is now tested for fit.
3. Calling propositionFunction on mondayShift@Bob results in proposition P2: mondayShift@Bob
4. Proposition P1 and P2 are now both the same mondayShift, which means Bob is now assigned to both of them. This is because both propositions operate on the same entity, and therefore share the same state.
5. The placement is then cleared again, both elements have been tested, and solution is returned to its original order. The propositions are then returned to the user, who notices that both P1 and P2 are mondayShift@null. This is because they shared state, and the original state of the solution was for Shift to be unassigned.

If instead the proposition function returned Ann and Bob directly, the immutable planning variables, this problem would have been avoided. Alternatively, the proposition function could have returned a defensive copy of the Shift.

Type Parameters:

EntityOrElement_ - generic type of the evaluated entity or element

Proposition_ - generic type of the user-provided proposition; if it is a planning entity, it is recommended to make a defensive copy inside the proposition function.

Parameters:

solution - never null; for basic variable, must be fully initialized or have a single entity unassigned. For list variable, all values must be assigned to some list, with the optional exception of one.

evaluatedEntityOrElement - never null; must be part of the solution. For basic variable, it is a planning entity and may have one or more variables unassigned. For list variable, it is a shadow entity and need not be present in any list variable.

propositionFunction - never null

fetchPolicy - never null; ScoreAnalysisFetchPolicy.FETCH_ALL will include more data within RecommendedAssignment, but will also take more time to gather that data.

Returns:

never null, sorted from best to worst; designed to be JSON-friendly, see RecommendedAssignment Javadoc for more.

See Also:

• More information about genuine and shadow planning entities.

recommendFit

@Deprecated(forRemoval=true,
            since="1.15.0")
default <EntityOrElement_,
Proposition_>
List<RecommendedFit<Proposition_,Score_>> recommendFit(Solution_ solution,
 EntityOrElement_ fittedEntityOrElement,
 Function<EntityOrElement_,Proposition_> propositionFunction)

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

Prefer recommendAssignment(Object, Object, Function, ScoreAnalysisFetchPolicy).

As defined by recommendAssignment(Object, Object, Function, ScoreAnalysisFetchPolicy), with ScoreAnalysisFetchPolicy.FETCH_ALL.

recommendFit

@Deprecated(forRemoval=true,
            since="1.15.0")
<EntityOrElement_,
Proposition_>
List<RecommendedFit<Proposition_,Score_>> recommendFit(Solution_ solution,
 EntityOrElement_ fittedEntityOrElement,
 Function<EntityOrElement_,Proposition_> propositionFunction,
 ScoreAnalysisFetchPolicy fetchPolicy)

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

Prefer recommendAssignment(Object, Object, Function, ScoreAnalysisFetchPolicy).

As defined by recommendAssignment(Object, Object, Function, ScoreAnalysisFetchPolicy).