Package ai.timefold.solver.core.impl.solver

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

java.lang.Object
ai.timefold.solver.core.impl.solver.DefaultSolutionManager<Solution_,Score_>
Type Parameters:
Solution_ - the solution type, the class with the PlanningSolution annotation
All Implemented Interfaces:
SolutionManager<Solution_,Score_>
public final class DefaultSolutionManager<Solution_,Score_ extends Score<Score_>> extends Object implements SolutionManager<Solution_,Score_>

  • Constructor Details

  • Method Details

    • getScoreDirectorFactory

      public InnerScoreDirectorFactory<Solution_,Score_> getScoreDirectorFactory()

    • update

      public Score_ update(Solution_ solution, SolutionUpdatePolicy solutionUpdatePolicy)
      Description copied from interface: SolutionManager
      Updates the given solution according to the SolutionUpdatePolicy.
      Specified by:
      update in interface SolutionManager<Solution_,Score_ extends Score<Score_>>
      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:

    • explain

      public ScoreExplanation<Solution_,Score_> explain(Solution_ solution, SolutionUpdatePolicy solutionUpdatePolicy)
      Description copied from interface: SolutionManager
      Calculates and retrieves ConstraintMatchTotals and Indictments necessary for describing the quality of a particular solution. For a simplified, faster and JSON-friendly alternative, see SolutionManager.analyze(Object)}.
      Specified by:
      explain in interface SolutionManager<Solution_,Score_ extends Score<Score_>>
      Parameters:
      solution - never null
      solutionUpdatePolicy - never null; if unsure, pick SolutionUpdatePolicy.UPDATE_ALL
      Returns:
      never null
      See Also:

    • analyze

      public ScoreAnalysis<Score_> analyze(Solution_ solution, ScoreAnalysisFetchPolicy fetchPolicy, SolutionUpdatePolicy solutionUpdatePolicy)
      Description copied from interface: SolutionManager
      Calculates and retrieves information about which constraints contributed to the solution's score. This is a faster, JSON-friendly version of SolutionManager.explain(Object).
      Specified by:
      analyze in interface SolutionManager<Solution_,Score_ extends Score<Score_>>
      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
      See Also:

    • recommendAssignment

      public <In_, Out_> List<RecommendedAssignment<Out_,Score_>> recommendAssignment(Solution_ solution, In_ evaluatedEntityOrElement, Function<In_,Out_> propositionFunction, ScoreAnalysisFetchPolicy fetchPolicy)
      Description copied from interface: SolutionManager
      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.
      Specified by:
      recommendAssignment in interface SolutionManager<Solution_,Score_ extends Score<Score_>>
      Type Parameters:
      In_ - generic type of the evaluated entity or element
      Out_ - 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:

    • recommendFit

      public <In_, Out_> List<RecommendedFit<Out_,Score_>> recommendFit(Solution_ solution, In_ fittedEntityOrElement, Function<In_,Out_> propositionFunction, ScoreAnalysisFetchPolicy fetchPolicy)
      Description copied from interface: SolutionManager
      As defined by SolutionManager.recommendAssignment(Object, Object, Function, ScoreAnalysisFetchPolicy).
      Specified by:
      recommendFit in interface SolutionManager<Solution_,Score_ extends Score<Score_>>