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 Details

    • create

      static <Solution_, Score_ extends Score<Score_>> @NonNull SolutionManager<Solution_,Score_> create(@NonNull 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

    • create

      static <Solution_, Score_ extends Score<Score_>, ProblemId_> @NonNull SolutionManager<Solution_,Score_> create(@NonNull 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

    • update

      default @Nullable Score_ update(@NonNull Solution_ solution)
      As defined by update(Object, SolutionUpdatePolicy), using SolutionUpdatePolicy.UPDATE_ALL.

    • update

      @Nullable Score_ update(@NonNull Solution_ solution, @NonNull SolutionUpdatePolicy solutionUpdatePolicy)
      Updates the given solution according to the SolutionUpdatePolicy.
      Parameters:
      solutionUpdatePolicy - if unsure, pick SolutionUpdatePolicy.UPDATE_ALL
      Returns:
      possibly null if already null and SolutionUpdatePolicy didn't cause its update
      See Also:

    • updateShadowVariables

      static <Solution_> void updateShadowVariables(@NonNull Class<Solution_> solutionClass, @NonNull Object... entities)
      This method updates all shadow variables at the entity level, simplifying the requirements of update(Object). Unlike the latter method, it does not require the complete configuration necessary to obtain an instance of SolutionManager.

      However, this method requires that the entity does not define any shadow variables that rely on listeners, as that would require a complete solution.

      Parameters:
      solutionClass - the solution class
      entities - all entities to be updated

    • updateShadowVariables

      static <Solution_> void updateShadowVariables(@NonNull Solution_ solution)
      Same as updateShadowVariables(Class, Object...), this method accepts a solution rather than a list of entities.
      Parameters:
      solution - the solution

    • explain

      default @NonNull ScoreExplanation<Solution_,Score_> explain(@NonNull Solution_ solution)
      As defined by explain(Object, SolutionUpdatePolicy), using SolutionUpdatePolicy.UPDATE_ALL.

    • explain

      @NonNull ScoreExplanation<Solution_,Score_> explain(@NonNull Solution_ solution, @NonNull 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:
      solutionUpdatePolicy - if unsure, pick SolutionUpdatePolicy.UPDATE_ALL
      Throws:
      IllegalStateException - when constraint matching is disabled or not supported by the underlying score calculator, such as EasyScoreCalculator.
      See Also:

    • analyze

      default @NonNull ScoreAnalysis<Score_> analyze(@NonNull Solution_ solution)
      As defined by analyze(Object, ScoreAnalysisFetchPolicy, SolutionUpdatePolicy), using SolutionUpdatePolicy.UPDATE_ALL and ScoreAnalysisFetchPolicy.FETCH_ALL.

    • analyze

      default @NonNull ScoreAnalysis<Score_> analyze(@NonNull Solution_ solution, @NonNull ScoreAnalysisFetchPolicy fetchPolicy)
      As defined by analyze(Object, ScoreAnalysisFetchPolicy, SolutionUpdatePolicy), using SolutionUpdatePolicy.UPDATE_ALL.

    • analyze

      @NonNull ScoreAnalysis<Score_> analyze(@NonNull Solution_ solution, @NonNull ScoreAnalysisFetchPolicy fetchPolicy, @NonNull 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 - must be fully initialized otherwise an exception is thrown
      fetchPolicy - if unsure, pick ScoreAnalysisFetchPolicy.FETCH_MATCH_COUNT
      solutionUpdatePolicy - if unsure, pick SolutionUpdatePolicy.UPDATE_ALL
      Throws:
      IllegalStateException - when constraint matching is disabled or not supported by the underlying score calculator, such as EasyScoreCalculator.
      See Also:

    • diff

      @NonNull PlanningSolutionDiff<Solution_> diff(@NonNull Solution_ oldSolution, @NonNull Solution_ newSolution)
      Compute a difference between two solutions. The difference will contain information about which entities's variables have changed, which entities were added and which were removed.

      Two instances of a planning entity or a variable value are considered equal if they equal. Instances of different classes are never considered equal, even if they share a common superclass. For the correct operation of this method, make sure that equals and hashCode honor their contract and are mutually consistent.

      This method is only offered as a preview feature. There are no guarantees for backward compatibility; its signature or the types it operates on and returns may change or be removed without prior notice, although we will strive to avoid this as much as possible.

      Parameters:
      oldSolution - The solution to use as a base for comparison.
      newSolution - The solution to compare against the base.
      Returns:
      A diff object containing information about the differences between the two solutions. Entities from the old solution that are not present in the new solution will be marked as removed. Entities from the new solution that are not present in the old solution will be marked as added. Entities that are present in both solutions will be marked as changed if their variables differ, according to the equality rules described above.

    • recommendAssignment

      default <EntityOrElement_, Proposition_> @NonNull List<RecommendedAssignment<Proposition_,Score_>> recommendAssignment(@NonNull Solution_ solution, EntityOrElement_ evaluatedEntityOrElement, @NonNull Function<EntityOrElement_,@NonNull Proposition_> propositionFunction)
      As defined by recommendAssignment(Object, Object, Function, ScoreAnalysisFetchPolicy), with ScoreAnalysisFetchPolicy.FETCH_ALL.

    • recommendAssignment

      <EntityOrElement_, Proposition_> @NonNull List<RecommendedAssignment<Proposition_,Score_>> recommendAssignment(@NonNull Solution_ solution, @NonNull EntityOrElement_ evaluatedEntityOrElement, @NonNull Function<EntityOrElement_,Proposition_> propositionFunction, @NonNull 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 - 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 - 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. ScoreAnalysisFetchPolicy.FETCH_ALL will include more data within RecommendedAssignment, but will also take more time to gather that data.
      Returns:
      sorted from best to worst; designed to be JSON-friendly, see RecommendedAssignment Javadoc for more.
      See Also:

    • 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).