Cream version 1.2 Core API Specification

jp.ac.kobe_u.cs.cream
Class Solver

java.lang.Object
  extended byjp.ac.kobe_u.cs.cream.Solver
All Implemented Interfaces:
java.lang.Runnable
Direct Known Subclasses:
DefaultSolver, LocalSearch, ParallelSolver

public abstract class Solver
extends java.lang.Object
implements java.lang.Runnable

An abstract class for constraint solvers. A solver is constructed with a constraint network which is used by the solver to find solutions. Please note that any network can not be simultaneously shared by two different solvers.

Solvers can be used in three typical ways.

Since:
1.0
See Also:
Network, Solution, SolutionHandler

Field Summary
static int BETTER
          An option value specifying to return only better solutions
static int DEFAULT
          A constant value for the default option
static int MAXIMIZE
          An option value specifying to maximize the objective variable
static int MINIMIZE
          An option value specifying to minimize the objective variable
static int NONE
          A constant value for no options
 
Constructor Summary
Solver(Network network)
          Constructs a solver for the given network (for invocation by subclass constructors).
Solver(Network network, int option)
          Constructs a solver for the given network and option (for invocation by subclass constructors).
Solver(Network network, int option, java.lang.String name)
          Constructs a solver for the given network, option, and name (for invocation by subclass constructors).
Solver(Network network, java.lang.String name)
          Constructs a solver for the given network and name (for invocation by subclass constructors).
 
Method Summary
 void clearBest()
          Clears the best solution this solver has been found.
 void findAll(SolutionHandler handler)
          Invokes the handler for each solution.
 void findAll(SolutionHandler handler, long timeout)
          Invokes the handler for each solution with the timeout.
 Solution findBest()
          Finds the best solution.
 Solution findBest(long timeout)
          Finds the best solution with the timeout.
 Solution findFirst()
          Finds the first solution.
 Solution findFirst(long timeout)
          Finds the first solution with the timeout.
 Solution getBestSolution()
          Returns the best solution this solver has been found.
 int getBestValue()
          Returns the best objective value this solver has been found.
 int getID()
          Returns the ID number of this solver.
 int getOption()
          Returns the option value.
 Solution getSolution()
          Returns the last solution this solver is found.
 void join()
          Waits until the solver ends the execution.
static void resetIDCounter()
          Resets the ID counter to be 0.
 void resume()
          Resumes the execution of the solver.
abstract  void run()
          The body of the solver.
 void setMonitor(Monitor monitor)
          Sets the monitor.
 void start()
          Starts the solver in a new thread, and immediately returns to the caller.
 void start(long timeout)
          Starts the solver in a new thread with the timeout, and immediately returns to the caller.
 void start(SolutionHandler handler)
          Starts the solver in a new thread, and immediately returns to the caller.
 void start(SolutionHandler handler, long timeout)
          Starts the solver in a new thread with the timeout, and immediately returns to the caller.
 void stop()
          Stops the execution of the solver.
 java.lang.String toString()
          Returns the name of this solver.
 boolean waitNext()
          Waits for the next solution, or the end of the solver execution.
 boolean waitNext(long timeout)
          Waits for the next solution, or the end of the solver execution with the timeout.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT

public static final int DEFAULT
A constant value for the default option

See Also:
Constant Field Values

NONE

public static final int NONE
A constant value for no options

See Also:
Constant Field Values

MINIMIZE

public static final int MINIMIZE
An option value specifying to minimize the objective variable

See Also:
Constant Field Values

MAXIMIZE

public static final int MAXIMIZE
An option value specifying to maximize the objective variable

See Also:
Constant Field Values

BETTER

public static final int BETTER
An option value specifying to return only better solutions

See Also:
Constant Field Values
Constructor Detail

Solver

public Solver(Network network)
Constructs a solver for the given network (for invocation by subclass constructors). This constructor is equivalent to Solver(network, DEFAULT, null).

Parameters:
network - the constraint network

Solver

public Solver(Network network,
              int option)
Constructs a solver for the given network and option (for invocation by subclass constructors). This constructor is equivalent to Solver(network, option, null).

Parameters:
network - the constraint network
option - the option for search strategy

Solver

public Solver(Network network,
              java.lang.String name)
Constructs a solver for the given network and name (for invocation by subclass constructors). This constructor is equivalent to Solver(network, DEFAULT, name).

Parameters:
network - the constraint network
name - the name of the solver

Solver

public Solver(Network network,
              int option,
              java.lang.String name)
Constructs a solver for the given network, option, and name (for invocation by subclass constructors). When option is DEFAULT, NONE is used if the network has no objective variable, or else MINIMIZE is used. Solvers and subclasses have their ID number starting from 0.

Parameters:
network - the constraint network
option - the option for search strategy, or DEFAULT for default search strategy
name - the name of the solver, or null for a default name
Method Detail

setMonitor

public void setMonitor(Monitor monitor)
Sets the monitor.

Parameters:
monitor - monitor

resetIDCounter

public static void resetIDCounter()
Resets the ID counter to be 0.


getID

public int getID()
Returns the ID number of this solver.

Returns:
the ID number of this solver

clearBest

public void clearBest()
Clears the best solution this solver has been found.


getSolution

public Solution getSolution()
Returns the last solution this solver is found.

Returns:
the last solution, or null if no solutions have been found

getBestSolution

public Solution getBestSolution()
Returns the best solution this solver has been found.

Returns:
the best solution, or null if no solutions have been found

getBestValue

public int getBestValue()
Returns the best objective value this solver has been found. When no solutions have been found, this method returns IntDomain.MAX_VALUE if the search strategy is MINIMIZE, or IntDomain.MIN_VALUE if the search strategy is MAXIMIZE.

Returns:
the best objective value

getOption

public int getOption()
Returns the option value.

Returns:
the option value

start

public void start()
Starts the solver in a new thread, and immediately returns to the caller. The waitNext() and waitNext(long timeout) methods can be used to wait the next solution. When a solution is found, the solver suspends the execution until the resume() method is called. You can stop the solver anytime by calling the stop() method.


start

public void start(long timeout)
Starts the solver in a new thread with the timeout, and immediately returns to the caller. When the timeout milliseconds have been elapsed since the start of the solver, it stops the execution. The waitNext() and waitNext(long timeout) methods can be used to wait the next solution, or to detect the timeout. When a solution is found, the solver suspends the execution until the resume() method is called. You can stop the solver anytime by calling the stop() method.

Parameters:
timeout - timeout in milliseconds (non-positive value means no timeout)

start

public void start(SolutionHandler handler)
Starts the solver in a new thread, and immediately returns to the caller. The handler is called for each solution and at the end of the solver execution. You can stop the solver anytime by calling the stop() method.

Parameters:
handler - solution handler

start

public void start(SolutionHandler handler,
                  long timeout)
Starts the solver in a new thread with the timeout, and immediately returns to the caller. When the timeout milliseconds have been elapsed since the start of the solver, it stops the execution. The handler is called for each solution and at the end of the solver execution. You can stop the solver anytime by calling the stop() method.

Parameters:
handler - solution handler
timeout - timeout in milliseconds (non-positive value means no timeout)

waitNext

public boolean waitNext()
Waits for the next solution, or the end of the solver execution. It returns true if the next solution is available, false if the solver ends the execution.

Returns:
true if the next solution is available

waitNext

public boolean waitNext(long timeout)
Waits for the next solution, or the end of the solver execution with the timeout. It returns true if the next solution is available within the timeout milliseconds, false if the solver ends the execution or the timeout milliseconds have been elapsed since the start of this method.

Parameters:
timeout - timeout in milliseconds (non-positive value means no timeout)
Returns:
true if the next solution is available

resume

public void resume()
Resumes the execution of the solver.


join

public void join()
Waits until the solver ends the execution.


stop

public void stop()
Stops the execution of the solver.


run

public abstract void run()
The body of the solver. This method is called from start() methods.

Specified by:
run in interface java.lang.Runnable

findFirst

public Solution findFirst()
Finds the first solution. This method is equivalent to findFirst(0).

Returns:
the first solution, or null if no solutions found

findFirst

public Solution findFirst(long timeout)
Finds the first solution with the timeout. This method is implemented as follows:
     clearBest();
     start(timeout);
     waitNext();
     stop();
     return getBestSolution();
 

Parameters:
timeout - timeout in milliseconds (non-positive value means no timeout)
Returns:
the first solution, or null if no solutions found

findBest

public Solution findBest()
Finds the best solution. This method is equivalent to findBest(0).

Returns:
the best solution, or null if no solutions found

findBest

public Solution findBest(long timeout)
Finds the best solution with the timeout. This method is implemented as follows:
     clearBest();
     for (start(timeout); waitNext(); resume()) {
         ;
     }
     stop();
     return getBestSolution();
 

Parameters:
timeout - timeout in milliseconds (non-positive value means no timeout)
Returns:
the best solution, or null if no solutions found

findAll

public void findAll(SolutionHandler handler)
Invokes the handler for each solution. This method is equivalent to findFirst(handler, 0).

Parameters:
handler - solution handler

findAll

public void findAll(SolutionHandler handler,
                    long timeout)
Invokes the handler for each solution with the timeout. This method is implemented as follows:
     clearBest();
     start(handler, timeout);
     join();
 

Parameters:
handler - solution handler
timeout - timeout in milliseconds (non-positive value means no timeout)

toString

public java.lang.String toString()
Returns the name of this solver.

Returns:
the name of this solver

Cream version 1.2 Core API Specification

Cream: Constraint Programming Class Library for Java