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 ScoreDirectorFactory<Solution_,Score_> getScoreDirectorFactory()

    • update

      public @Nullable Score_ update(@NonNull Solution_ solution, @NonNull 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_>>
      solutionUpdatePolicy - if unsure, pick SolutionUpdatePolicy.UPDATE_ALL
      Returns:
      possibly null if already null and SolutionUpdatePolicy didn't cause its update
      See Also:

    • explain

      public @NonNull ScoreExplanation<Solution_,Score_> explain(@NonNull Solution_ solution, @NonNull 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_>>
      solutionUpdatePolicy - if unsure, pick SolutionUpdatePolicy.UPDATE_ALL
      See Also:

    • analyze

      public @NonNull ScoreAnalysis<Score_> analyze(@NonNull Solution_ solution, @NonNull ScoreAnalysisFetchPolicy fetchPolicy, @NonNull 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 - must be fully initialized otherwise an exception is thrown
      fetchPolicy - if unsure, pick ScoreAnalysisFetchPolicy.FETCH_MATCH_COUNT
      solutionUpdatePolicy - if unsure, pick SolutionUpdatePolicy.UPDATE_ALL
      See Also:

    • diff

      public @NonNull PlanningSolutionDiff<Solution_> diff(@NonNull Solution_ oldSolution, @NonNull Solution_ newSolution)
      Description copied from interface: SolutionManager
      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.

      Specified by:
      diff in interface SolutionManager<Solution_,Score_ extends Score<Score_>>
      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

      public <In_, Out_> @NonNull List<RecommendedAssignment<Out_,Score_>> recommendAssignment(@NonNull Solution_ solution, @NonNull In_ evaluatedEntityOrElement, @NonNull Function<In_,Out_> propositionFunction, @NonNull 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 - 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

      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_>>

    • visualizeNodeNetwork

      public @NonNull String visualizeNodeNetwork(@NonNull Solution_ solution)
      Generates a Bavet node network visualization for the given solution. It uses a Graphviz DOT language representation. The string returned by this method can be converted to an image using dot: 
       $ dot -Tsvg input.dot > output.svg
      This assumes the string returned by this method is saved to a file named input.dot.

      The node network itself is an internal implementation detail of Constraint Streams. Do not rely on any particular node network structure in production code, and do not micro-optimize your constraints to match the node network. Such optimizations are destined to become obsolete and possibly harmful as the node network evolves.

      This method is only provided for debugging purposes and is deliberately not part of the public API. Its signature or behavior may change without notice, and it may be removed in future versions.

      Parameters:
      solution - Will be used to read constraint weights, which determine the final node network.
      Returns:
      A string representing the node network in Graphviz DOT language.
      See Also: