javax.constraints
Interface Solver

All Known Implementing Classes:

AbstractSolver, SolverWithGoals

public interface Solver

The interface Solver is used for Problem Resolution and utilizes concepts of Search Strategies and Solutions.

The Solver provides a standardized way to implement the following functions:

• Find a solution
• Find an optimal solution that minimizes/maximizes an objective variable
• Iterate through multiple solutions
• Limit search time and a number of solutions.

These functions use an ordered list of search strategies called "execution list". Each implementation should provide at least one default search strategy that is available by the Solver's method "getSearchStrategy". A user may get this strategy and apply its methods "setVars", "setVarSelector", and "setValueSelector" to customize it. This strategy is the first one to be executed. A user may also add another strategy using the Solver's method "newSearchStrategy". It returns a new instance of the default search strategy. A user may set its attributes and use the method "addStrategy" to add a new customized strategy to the end of the execution list. For example, if a user want first to instantiate all variables from the array "types" and then all variables from the array "counts", it can be done as follow:

 SearchStrategy s1 = solver.getSearchStrategy();
 s1.setVars(types);
 SearchStrategy s2 = solver.newSearchStrategy();
 s2.setVars(counts);
 s2.setVarSelectorType(VarSelectorType.RANDOM);
 solver.addStrategy(s2);
 

See Also:

Solution, SearchStrategy, VarSelector, ValueSelector

Method Summary

void	addSearchStrategy(SearchStrategy strategy) This methods adds this strategy to the end of the strategy execution lists.
void	addSearchStrategy(Var[] vars) This methods takes the default search strategy, resets its vars, and adds this strategy to the end of the strategy execution lists.
void	addSearchStrategy(Var[] vars, ValueSelector valueSelector) This methods takes the default search strategy, resets its vars and valueSelector, and adds this strategy to the end of the strategy execution lists.
void	addSearchStrategy(Var[] vars, ValueSelectorType valueSelectorType) This methods takes the default search strategy, resets its vars and valueSelector, and adds this strategy to the end of the strategy execution lists.
void	addSearchStrategy(Var[] vars, VarSelector varSelector) This methods takes the default search strategy, resets its vars and varSelector, and adds this strategy to the end of the strategy execution lists.
void	addSearchStrategy(Var[] vars, VarSelectorType varSelectorType) This methods takes the default search strategy, resets its vars and varSelector, and adds this strategy to the end of the strategy execution lists.
void	addSearchStrategy(Var[] vars, VarSelectorType varSelectorType, ValueSelectorType valueSelectorType) This methods takes the default search strategy, resets its vars, varSelector, and valueSelector, and then adds this strategy to the end of the strategy execution lists.
void	addSearchStrategy(Var[] vars, VarSelector varSelector, ValueSelector valueSelector) This methods takes the default search strategy, resets its vars, varSelector, and valueSelector, and then adds this strategy to the end of the strategy execution lists.
void	addStrategyLogVariables() This methods adds the strategy getStrategyLogVariables() to the end of the strategy execution lists.
Solution[]	findAllSolutions() This method attempts to find all solutions for the Problem.
Solution	findOptimalSolution(Objective objective, Var objectiveVar) This method is equivalent to findOptimalSolution(Objective.MINIMIZE,objectiveVar,OptimizationStrategy.NATIVE) It is usually overridden by an implementation
Solution	findOptimalSolution(Objective objective, Var objectiveVar, OptimizationStrategy optStrategy) This method attempts to find the solution that minimizes/maximizes the objective variable.
Solution	findOptimalSolution(Var objectiveVar) This method is equivalent to findOptimalSolution(Objective.MINIMIZE,objectiveVar)
Solution	findSolution() This method is equivalent to findSolution(DO_NOT_RESTORE); It means that the problem state will always be restored even when a solution is found.
Solution	findSolution(ProblemState restoreOrNot) This method attempts to find a solution of the problem, for which the solver was defined.
int	getMaxNumberOfSolutions() Returns the maximal number of solutions any search can look for.
int	getNumberOfSolutions() Returns the number of the last solution found, or 0 if no solutions have been found yet (or the search for a solution was not yet launched).
int	getOptimizationTolerance() Returns the current tolerance for the method findOptimalSolution()
Problem	getProblem() Returns the Problem for which this solver was created
SearchStrategy	getSearchStrategy() Returns a SearchStrategy that is currently used by the solver
Solution	getSolution(int i) Returns the i-th Solution found by the latest search
SearchStrategy	getStrategyLogVariables() Returns a search strategy that logs all variables
int	getTimeLimit() Returns the duration, in milliseconds, of the imposed time limit on search of one solution.
int	getTimeLimitGlobal() Returns the duration, in milliseconds, of the imposed time limit on global search of all solutions or an optimal solution.
long	getTimeLimitStart() Returns the time, in milliseconds, at which the time limit began counting.
void	logStats() This method logs execution statistics such as a number of choice points, number of failures, used memory, etc.
SearchStrategy	newSearchStrategy() This methods returns a new default search strategy
void	restoreProblem() Restores a previously saved problem
void	saveProblem() Creates a copy of the problem in its current state
void	setMaxNumberOfSolutions(int maxNumberOfSolutions) Sets the limit on the maximal number of solutions any search can look for.
void	setOptimizationTolerance(int tolerance) Specifies a tolerance for the method findOptimalSolution().
void	setProblem(Problem problem) Set the Problem with which this solver should work
void	setSearchStrategy(SearchStrategy strategy) Define a search strategy that will be used by the solver to solve the problem.
void	setSearchStrategy(Var[] vars) Define a searchStrategy that will be used by find solutions methods.
void	setSearchStrategy(Var[] vars, ValueSelector valueSelector) Define a searchStrategy that will be used by find solutions methods.
void	setSearchStrategy(Var[] vars, VarSelector varSelector) Define a searchStrategy that will be used by find solutions methods.
void	setSearchStrategy(Var[] vars, VarSelector varSelector, ValueSelector valueSelector) Define a searchStrategy that will be used by find solutions methods.
void	setTimeLimit(int mills) Sets the duration, in milliseconds, of the time limit on search of one solution.
void	setTimeLimitGlobal(int mills) Sets the duration, in milliseconds, of the time limit on global search of all solutions or an optimal solution.
void	setTimeLimitStart() Sets the start time as the system current time, for counting milliseconds to the time limit.
SolutionIterator	solutionIterator() Creates a solution iterator that allows a user to find and navigate through solutions using the default search strategy.
void	trace(Var var) This method forces to trace (to log) all modification events for the variable "var".
void	trace(Var[] vars) This method forces to trace (to log) all modification events for all variables "vars"
void	trace(VarSet setVar) This method forces to trace (to log) all modification events for the variable "setVar".
void	traceExecution(boolean trueOrFalse) This method forces the execution to log important execution points
void	traceFailures(boolean flag) If flag is true, all failures will be traced (logged)
void	traceSolutions(boolean trueOrFalse) This method forces the execution to log intermediate solutions during optimization search

Method Detail

addSearchStrategy

void addSearchStrategy(SearchStrategy strategy)

This methods adds this strategy to the end of the strategy execution lists.

Parameters:

strategy -

addSearchStrategy

void addSearchStrategy(Var[] vars)

This methods takes the default search strategy, resets its vars, and adds this strategy to the end of the strategy execution lists.

Parameters:

vars -

addSearchStrategy

void addSearchStrategy(Var[] vars,
                       ValueSelector valueSelector)

This methods takes the default search strategy, resets its vars and valueSelector, and adds this strategy to the end of the strategy execution lists.

Parameters:

vars -

valueSelector -

addSearchStrategy

void addSearchStrategy(Var[] vars,
                       ValueSelectorType valueSelectorType)

This methods takes the default search strategy, resets its vars and valueSelector, and adds this strategy to the end of the strategy execution lists.

Parameters:

vars -

valueSelectorType -

addSearchStrategy

void addSearchStrategy(Var[] vars,
                       VarSelector varSelector)

This methods takes the default search strategy, resets its vars and varSelector, and adds this strategy to the end of the strategy execution lists.

Parameters:

vars -

varSelector -

addSearchStrategy

void addSearchStrategy(Var[] vars,
                       VarSelectorType varSelectorType)

This methods takes the default search strategy, resets its vars and varSelector, and adds this strategy to the end of the strategy execution lists.

Parameters:

vars -

varSelectorType -

addSearchStrategy

void addSearchStrategy(Var[] vars,
                       VarSelectorType varSelectorType,
                       ValueSelectorType valueSelectorType)

This methods takes the default search strategy, resets its vars, varSelector, and valueSelector, and then adds this strategy to the end of the strategy execution lists.

Parameters:

vars -

varSelectorType -

valueSelectorType -

addSearchStrategy

void addSearchStrategy(Var[] vars,
                       VarSelector varSelector,
                       ValueSelector valueSelector)

This methods takes the default search strategy, resets its vars, varSelector, and valueSelector, and then adds this strategy to the end of the strategy execution lists.

Parameters:

vars -

varSelector -

valueSelector -

addStrategyLogVariables

void addStrategyLogVariables()

This methods adds the strategy getStrategyLogVariables() to the end of the strategy execution lists.

findAllSolutions

Solution[] findAllSolutions()

This method attempts to find all solutions for the Problem. It uses the default search strategy or the strategy defined by the latest method setSearchStrategy(). It returns an array of found solutions or null if there are no solutions. A user has to be careful not to overload the available memory because the number of found solutions could be huge. The process of finding all solutions can be also controlled by:

• MaxNumberOfSolutions that is the total number of considered solutions that may be limited by the method setMaxNumberOfSolutions();
• TotalTimeLimit that is the number of seconds allocated for the entire optimization process.

The problem state after the execution of this method is always restored.

Returns:

Solution[]

findOptimalSolution

Solution findOptimalSolution(Objective objective,
                             Var objectiveVar)

This method is equivalent to findOptimalSolution(Objective.MINIMIZE,objectiveVar,OptimizationStrategy.NATIVE) It is usually overridden by an implementation

Parameters:

objectiveVar -

Returns:

Solution if a solution is found, null if there are no solutions.

findOptimalSolution

Solution findOptimalSolution(Objective objective,
                             Var objectiveVar,
                             OptimizationStrategy optStrategy)

This method attempts to find the solution that minimizes/maximizes the objective variable. It uses the search strategy defined by the method setSearchStrategy(strategy). The optimization process can be also controlled by:

• OptimizationTolerance that is a difference between optimal solutions - see setOptimizationTolarance()
• MaxNumberOfSolutions that is the total number of considered solutions - may be limited by the method setMaxNumberOfSolutions()
• TimeLimitGlobal that is the number of seconds allocated for the entire optimization process.

At the same time the time for one iteration inside optimization loop (a search of one solution) can be also limited by the Solver's attribute TimeLimit or by the use of a special search strategy specified by a particular implementation.
The problem state after the execution of this method is always restored. All variables that were added to the problems (plus the objectiveVar) will have their assigned values saved inside the optimal solution.

Parameters:

objective - Objective.MINIMIZE or Objective.MAXIMIZE

objectiveVar - the variable that is being minimized/maximized

optStrategy - OptimizationStrategy (BASIC, DICHOTOMIZE, or NATIVE)

Returns:

Solution if a solution is found, null if there are no solutions.

findOptimalSolution

Solution findOptimalSolution(Var objectiveVar)

This method is equivalent to findOptimalSolution(Objective.MINIMIZE,objectiveVar)

Parameters:

objectiveVar -

Returns:

Solution if a solution is found, null if there are no solutions.

findSolution

Solution findSolution()

This method is equivalent to findSolution(DO_NOT_RESTORE); It means that the problem state will always be restored even when a solution is found.

Returns:

a Solution if the search is successful or null.

findSolution

Solution findSolution(ProblemState restoreOrNot)

This method attempts to find a solution of the problem, for which the solver was defined. It uses the search strategy defined by the method setSearchStrategy(). It returns the found solution (if any) or null. It also saves the solution and makes it available through the method getSolution(). If a solution is not found, the problem state is restored to that of before the invocation of this method. If a solution is found, the problem state will be restored only if the parameter "restore" is true. Otherwise all problem variables will be instantiated with the solution values. The search can be limited by time, number of failed attempts, etc.

Parameters:

restoreOrNot - defines if the problem state should be restored after a solution is found

Returns:

a Solution if the search is successful or null

getMaxNumberOfSolutions

int getMaxNumberOfSolutions()

Returns the maximal number of solutions any search can look for. A value of -1 indicates infinity, i.e. that there is no limitation on the maximal number of solutions. The default value is -1.

Returns:

the maximal number of solutions any search can look for. A value of -1 indicates infinity, i.e. that there is no limitation on the maximal number of solutions. The default value is -1.

getNumberOfSolutions

int getNumberOfSolutions()

Returns the number of the last solution found, or 0 if no solutions have been found yet (or the search for a solution was not yet launched).

Returns:

the number of the last solution found, or 0 if no solution have been found yet (or the search for a solution was not yet launched).

getOptimizationTolerance

int getOptimizationTolerance()

Returns the current tolerance for the method findOptimalSolution()

Returns:

the current tolerance for the method findOptimalSolution()

getProblem

Problem getProblem()

Returns the Problem for which this solver was created

Returns:

the Problem for which this solver was created

getSearchStrategy

SearchStrategy getSearchStrategy()

Returns a SearchStrategy that is currently used by the solver

Returns:

a SearchStrategy that is currently used by the solver to solve the problem

getSolution

Solution getSolution(int i)

Returns the i-th Solution found by the latest search

Returns:

the i-th Solution found by the latest search

See Also:

findAllSolutions()

getStrategyLogVariables

SearchStrategy getStrategyLogVariables()

Returns a search strategy that logs all variables

Returns:

a a search strategy that logs all variables

getTimeLimit

int getTimeLimit()

Returns the duration, in milliseconds, of the imposed time limit on search of one solution.

Returns:

the duration, in milliseconds, of the imposed time limit on search of one solution.

getTimeLimitGlobal

int getTimeLimitGlobal()

Returns the duration, in milliseconds, of the imposed time limit on global search of all solutions or an optimal solution.

Returns:

the duration, in milliseconds, of the imposed time limit on global search of all solutions or an optimal solution.

getTimeLimitStart

long getTimeLimitStart()

Returns the time, in milliseconds, at which the time limit began counting.

Returns:

the time, in milliseconds, at which the time limit began counting.

logStats

void logStats()

This method logs execution statistics such as a number of choice points, number of failures, used memory, etc. This method is expected to be specific for different reference implementations

newSearchStrategy

SearchStrategy newSearchStrategy()

This methods returns a new default search strategy

Returns:

a new default search strategy

restoreProblem

void restoreProblem()

Restores a previously saved problem

saveProblem

void saveProblem()

Creates a copy of the problem in its current state

setMaxNumberOfSolutions

void setMaxNumberOfSolutions(int maxNumberOfSolutions)

Sets the limit on the maximal number of solutions any search can look for. A value of -1 indicates infinity, i.e. that there is no limitation on the maximal number of solutions. The default value is -1.

Parameters:

maxNumberOfSolutions - the new limit for the maximal number of solutions any search can look for.

setOptimizationTolerance

void setOptimizationTolerance(int tolerance)

Specifies a tolerance for the method findOptimalSolution(). If the difference between newly found solution and a previous one is less or equal "tolerance" then the last solution is considered to be the optimal one. By default, the optimization tolerance is 0.

Parameters:

tolerance -

setProblem

void setProblem(Problem problem)

Set the Problem with which this solver should work

setSearchStrategy

void setSearchStrategy(SearchStrategy strategy)

Define a search strategy that will be used by the solver to solve the problem. Each Solver' implementation should set a default search strategy in the its Solver constructor.

Parameters:

strategy -

setSearchStrategy

void setSearchStrategy(Var[] vars)

Define a searchStrategy that will be used by find solutions methods. This methods takes the default search strategy, and resets its vars.

Parameters:

vars -

setSearchStrategy

void setSearchStrategy(Var[] vars,
                       ValueSelector valueSelector)

Define a searchStrategy that will be used by find solutions methods. This methods takes the default search strategy, and resets its vars and valueSelector.

Parameters:

vars -

valueSelector -

setSearchStrategy

void setSearchStrategy(Var[] vars,
                       VarSelector varSelector)

Define a searchStrategy that will be used by find solutions methods. This methods takes the default search strategy, and resets its vars and varSelector.

Parameters:

vars -

varSelector -

setSearchStrategy

void setSearchStrategy(Var[] vars,
                       VarSelector varSelector,
                       ValueSelector valueSelector)

Define a searchStrategy that will be used by find solutions methods. This methods takes the default search strategy, and resets its vars, varSelector, and valueSelector.

Parameters:

vars -

varSelector -

valueSelector -

setTimeLimit

void setTimeLimit(int mills)

Sets the duration, in milliseconds, of the time limit on search of one solution.

Parameters:

mills - the new time limit in milliseconds

setTimeLimitGlobal

void setTimeLimitGlobal(int mills)

Sets the duration, in milliseconds, of the time limit on global search of all solutions or an optimal solution.

Parameters:

mills - the new global time limit in milliseconds

setTimeLimitStart

void setTimeLimitStart()

Sets the start time as the system current time, for counting milliseconds to the time limit.

solutionIterator

SolutionIterator solutionIterator()

Creates a solution iterator that allows a user to find and navigate through solutions using the default search strategy.

Returns:

a solution iterator

trace

void trace(Var var)

This method forces to trace (to log) all modification events for the variable "var".

Parameters:

var -

trace

void trace(Var[] vars)

This method forces to trace (to log) all modification events for all variables "vars"

Parameters:

vars -

trace

void trace(VarSet setVar)

This method forces to trace (to log) all modification events for the variable "setVar".

Parameters:

setVar -

traceExecution

void traceExecution(boolean trueOrFalse)

This method forces the execution to log important execution points

Parameters:

trueOrFalse - boolean

traceFailures

void traceFailures(boolean flag)

If flag is true, all failures will be traced (logged)

Parameters:

flag -

traceSolutions

void traceSolutions(boolean trueOrFalse)

This method forces the execution to log intermediate solutions during optimization search

Parameters:

trueOrFalse - boolean