org.optaplanner.core.api.solver

Interface Solver<Solution_>

Type Parameters:

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

All Known Implementing Classes:

AbstractSolver, DefaultSolver, PartitionSolver

public interface Solver<Solution_>

A Solver solves a planning problem and returns the best solution found. It's recommended to create a new Solver instance for each dataset.

To create a Solver, use SolverFactory.buildSolver(). To solve a planning problem, call solve(Object). To solve a planning problem without blocking the current thread, use SolverManager instead.

These methods are not thread-safe and should be called from the same thread, except for the methods that are explicitly marked as thread-safe. Note that despite that solve(Solution_) is not thread-safe for clients of this class, that method is free to do multithreading inside itself.

Method Summary

Modifier and Type	Method and Description
void	addEventListener(SolverEventListener<Solution_> eventListener)
boolean	addProblemFactChange(ProblemFactChange<Solution_> problemFactChange) Schedules a ProblemFactChange to be processed.
boolean	addProblemFactChanges(List<ProblemFactChange<Solution_>> problemFactChangeList) Schedules multiple ProblemFactChanges to be processed.
String	explainBestScore() Deprecated. in favor of ScoreManager.explainScore(Object)
Score	getBestScore() Deprecated. in favor of ScoreManager.updateScore(Object)
Solution_	getBestSolution() Deprecated. in favor of addEventListener(SolverEventListener) or SolverJob.getFinalBestSolution().
ScoreDirectorFactory<Solution_>	getScoreDirectorFactory() Deprecated. in favor of SolverFactory.getScoreDirectorFactory() Will be removed in 8.0.
long	getTimeMillisSpent() Deprecated. in favor of SolverJob.getSolvingDuration().
boolean	isEveryProblemFactChangeProcessed() Checks if all scheduled ProblemFactChanges have been processed.
boolean	isSolving() This method is thread-safe.
boolean	isTerminateEarly() This method is thread-safe.
void	removeEventListener(SolverEventListener<Solution_> eventListener)
Solution_	solve(Solution_ problem) Solves the planning problem and returns the best solution encountered (which might or might not be optimal, feasible or even initialized).
boolean	terminateEarly() Notifies the solver that it should stop at its earliest convenience.

Method Detail

solve

Solution_ solve(Solution_ problem)

Solves the planning problem and returns the best solution encountered (which might or might not be optimal, feasible or even initialized).

It can take seconds, minutes, even hours or days before this method returns, depending on the Termination configuration. To terminate a Solver early, call terminateEarly().

Parameters:

problem - never null, a PlanningSolution, usually its planning variables are uninitialized

Returns:

never null, but it can return the original, uninitialized PlanningSolution with a null Score.

See Also:

terminateEarly()

terminateEarly

boolean terminateEarly()

Notifies the solver that it should stop at its earliest convenience. This method returns immediately, but it takes an undetermined time for the solve(Solution_) to actually return.

If the solver is running in daemon mode, this is the only way to terminate it normally.

This method is thread-safe. It can only be called from a different thread because the original thread is still calling solve(Object).

Returns:

true if successful, false if was already terminating or terminated

See Also:

isTerminateEarly(), Future.cancel(boolean)

getBestSolution

@Deprecated
Solution_ getBestSolution()

Deprecated. in favor of addEventListener(SolverEventListener) or SolverJob.getFinalBestSolution().

The best solution is the best solution found during solving: it might or might not be optimal, feasible or even initialized.

The solve(Solution_) method also returns the best solution, but this method is useful in rare asynchronous situations (although SolverEventListener.bestSolutionChanged(BestSolutionChangedEvent) is often more appropriate).

This method is thread-safe.

Returns:

never null (unless solve(Object) hasn't been called yet), but it can return the uninitialized PlanningSolution with a Score null.

getBestScore

@Deprecated
Score getBestScore()

Deprecated. in favor of ScoreManager.updateScore(Object)

Returns the Score of the getBestSolution().

This is useful for generic code, which doesn't know the type of the PlanningSolution to retrieve the Score from the getBestSolution() easily.

This method is thread-safe.

Returns:

null if the PlanningSolution is still uninitialized

explainBestScore

@Deprecated
String explainBestScore()

Deprecated. in favor of ScoreManager.explainScore(Object)

Returns a diagnostic text that explains the getBestSolution() through the ConstraintMatch API to identify which constraints or planning entities cause that getBestScore() quality. In case of an infeasible solution, this can help diagnose the cause of that.

Do not parse this string. Instead, to provide this information in a UI or a service, use SolverFactory.getScoreDirectorFactory() to retrieve ScoreDirector.getConstraintMatchTotalMap() and ScoreDirector.getIndictmentMap() and convert those into a domain specific API.

This method is thread-safe.

Returns:

null if getBestScore() returns null

See Also:

ScoreDirector.explainScore()

getTimeMillisSpent

@Deprecated
long getTimeMillisSpent()

Deprecated. in favor of SolverJob.getSolvingDuration().

Returns the amount of milliseconds spent solving since the last start. If it hasn't started it yet, it returns 0. If it hasn't ended yet, it returns the time between the last start and now. If it has ended already, it returns the time between the last start and the ending.

A addProblemFactChange(ProblemFactChange) triggers a restart which resets this time.

This method is thread-safe.

Returns:

the amount of milliseconds spent solving since the last (re)start, at least 0

isSolving

boolean isSolving()

This method is thread-safe.

Returns:

true if the solve(Solution_) method is still running.

isTerminateEarly

boolean isTerminateEarly()

This method is thread-safe.

Returns:

true if terminateEarly has been called since the Solver started.

See Also:

Future.isCancelled()

addProblemFactChange

boolean addProblemFactChange(ProblemFactChange<Solution_> problemFactChange)

Schedules a ProblemFactChange to be processed.

As a side-effect, this restarts the Solver, effectively resetting all Terminations, but not terminateEarly().

This method is thread-safe. Follows specifications of BlockingQueue.add(Object) with by default a capacity of Integer.MAX_VALUE.

Parameters:

problemFactChange - never null

Returns:

true (as specified by Collection.add(E))

See Also:

addProblemFactChanges(List)

addProblemFactChanges

boolean addProblemFactChanges(List<ProblemFactChange<Solution_>> problemFactChangeList)

Schedules multiple ProblemFactChanges to be processed.

As a side-effect, this restarts the Solver, effectively resetting all Terminations, but not terminateEarly().

This method is thread-safe. Follows specifications of Collection.addAll(Collection) with by default a capacity of Integer.MAX_VALUE.

Parameters:

problemFactChangeList - never null

Returns:

true (as specified by Collection.add(E))

See Also:

addProblemFactChange(ProblemFactChange)

isEveryProblemFactChangeProcessed

boolean isEveryProblemFactChangeProcessed()

Checks if all scheduled ProblemFactChanges have been processed.

This method is thread-safe.

Returns:

true if there are no ProblemFactChanges left to do

addEventListener

void addEventListener(SolverEventListener<Solution_> eventListener)

Parameters:

eventListener - never null

removeEventListener

void removeEventListener(SolverEventListener<Solution_> eventListener)

Parameters:

eventListener - never null

getScoreDirectorFactory

@Deprecated
ScoreDirectorFactory<Solution_> getScoreDirectorFactory()

Deprecated. in favor of SolverFactory.getScoreDirectorFactory() Will be removed in 8.0.

Useful to reuse the Score calculation (for example in a UI) and to explain the Score to the user with the ConstraintMatchTotal and Indictment API.

Returns:

never null