localsolver

Class LocalSolver

java.lang.Object

localsolver.LocalSolver

All Implemented Interfaces:

java.lang.AutoCloseable

public class LocalSolver
extends java.lang.Object
implements java.lang.AutoCloseable

LocalSolver environment. Main class of LocalSolver library. Here are described the basic steps for using LocalSolver:

1. Build your model (LSModel) by creating some expressions (LSExpression).
2. If desired, parameterize and add phases to the solver (LSParam, LSPhase).
3. Run the solver (LocalSolver).
4. Retrieve the best solution found by the solver (LSSolution).
5. Consult the statistics of the resolution (LSStatistics).

Note that this API is not thread safe. If multiple threads access and modify a same LocalSolver environment, it must be synchronized. The only methods that can be used without synchronization are getState() and stop(). Please consult LSVersion for copyright and version info.

Constructor Summary

Constructors

Constructor and Description
LocalSolver() Constructs a complete LocalSolver environment and take a token license.

Method Summary

Modifier and Type	Method and Description
void	addCallback(LSCallbackType type, LSCallback callback) Adds a new callback for a specific event type.
void	close() Deletes the LocalSolver objects and release the license token.
LSInconsistency	computeInconsistency() Computes an inconsistency core for this model.
LSPhase	createPhase() Adds a new phase to this LocalSolver environment.
void	delete() Deletes the LocalSolver objects and release the license token.
boolean	equals(java.lang.Object obj)
LSModel	getModel() Gets the model associated to this LocalSolver environment.
int	getNbPhases() Gets the number of phases.
LSParam	getParam() Gets the parameters of this LocalSolver environment.
LSPhase	getPhase(int phaseIndex) Gets the phase with the given index.
LSSolution	getSolution() Gets the best solution found by the solver.
LSState	getState() Gets the state of this LocalSolver environment.
LSStatistics	getStatistics() Gets the statistics of this LocalSolver environment.
int	hashCode()
void	loadEnvironment(java.lang.String filename) Import a complete environment or a model from a file.
boolean	removeCallback(LSCallbackType type, LSCallback callback) Removes the callback for the given event type.
void	saveEnvironment(java.lang.String filename) Export a complete environment or a model to a file.
void	solve() Solves the model.
void	stop() Aborts the resolution previously launched using solve().
java.lang.String	toString() Returns a String representation of this LocalSolver environment.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

LocalSolver

public LocalSolver()

Constructs a complete LocalSolver environment and take a token license. If no token is available or if the token server is not accessible, an exception is thrown. The token license is released when the destructor of this LocalSolver environment is called.

Method Detail

delete

public void delete()

Deletes the LocalSolver objects and release the license token. Calling this method releases the native memory used by LocalSolver and makes the LocalSolver license available for another LocalSolver model.

close

public void close()

Deletes the LocalSolver objects and release the license token. Calling this method releases the native memory used by LocalSolver and makes the LocalSolver license available for another LocalSolver model.

Specified by:

close in interface java.lang.AutoCloseable

getState

public LSState getState()

Gets the state of this LocalSolver environment. This method can be called in any state. In particular, this method can be called in state LSState.Running.

Returns:

State of LocalSolver.

getModel

public LSModel getModel()

Gets the model associated to this LocalSolver environment. Once the model is created and closed, the solver can be launched with solve().

Returns:

Model.

getParam

public LSParam getParam()

Gets the parameters of this LocalSolver environment.

Returns:

Parameters.

solve

public void solve()

Solves the model. This method returns only when the time limit, the iteration limit or the objective bounds are reached. The model must be closed to launch the resolution.

computeInconsistency

public LSInconsistency computeInconsistency()

Computes an inconsistency core for this model. Only allowed in state LSState.Stopped.

Returns:

The inconsistency core.

stop

public void stop()

Aborts the resolution previously launched using solve(). If no resolution was launched, this method does nothing. Called from another thread or callback, this method enables users to stop the resolution properly. Solution and statistics remain valid. This method can be called in any state, notably in state LSState.Running. Note that the effect of this method is not immediate. In particular when called within a callback, the resolution will not be stopped before the end of the callback.

See Also:

solve(), addCallback(localsolver.LSCallbackType, localsolver.LSCallback)

createPhase

public LSPhase createPhase()

Adds a new phase to this LocalSolver environment. Only allowed in states LSState.Modeling or LSState.Stopped.

Returns:

Created phase.

getPhase

public LSPhase getPhase(int phaseIndex)

Gets the phase with the given index.

Parameters:

phaseIndex - Index of the phase.

Returns:

Phase.

getNbPhases

public int getNbPhases()

Gets the number of phases.

Returns:

Number of phases.

getSolution

public LSSolution getSolution()

Gets the best solution found by the solver. If the solver has not been started at least once, all the decision variables of the solution are set to 0, or to their closest bound if 0 is not part of their domain (such a solution may be infeasible).. Only allowed in states LSState.Paused or LSState.Stopped.

Returns:

Best solution.

getStatistics

public LSStatistics getStatistics()

Gets the statistics of this LocalSolver environment. Statistics are reset to zero before each resolution. Only allowed in states LSState.Paused or LSState.Stopped. Note that for performance reasons, this function always returns the same object.

Returns:

Statistics.

See Also:

LSStatistics

toString

public java.lang.String toString()

Returns a String representation of this LocalSolver environment. This representation provides useful info related to the model, the parameters, and the phases (if any). Useful for debugging or logging purposes.

Overrides:

toString in class java.lang.Object

Returns:

String representation of this LocalSolver.

saveEnvironment

public void saveEnvironment(java.lang.String filename)

Export a complete environment or a model to a file. Currently, this function supports 2 file formats:

• LSB: with this format, the complete environment (model, parameters, solution, etc.) is exported. This format is useful to debug or replay a model in the same conditions. Since the produced file is binary, it offers good performance and space efficiency.
• LSP: with this format, only the model is exported in the LSP language. This format is useful to have a quick view of the optimization model or to perform some modifications. However, the file may be heavy for big models and the exact reproductibility is not guaranteed since the parameters from one execution to another may differ.

The chosen file format is determined by the file suffix. An exception is thrown if the provided file suffix is not supported. The suffix may optionally be followed by .gz. In that case, this function produces a compressed result (using deflate algorithm).

Parameters:

filename - Name of the file.

Since:

3.0

See Also:

loadEnvironment(java.lang.String)

loadEnvironment

public void loadEnvironment(java.lang.String filename)

Import a complete environment or a model from a file. Only allowed in state LSState.Modeling. The current model must be empty.

The only format supported is LSB.

The chosen file format is determined by the file suffix. An exception is thrown if the provided file suffix is not supported. The suffix may optionally be followed by .gz. In that case, this function uncompress the stream before reading.

Parameters:

filename - Name of the file.

Since:

3.0

See Also:

saveEnvironment(java.lang.String)

addCallback

public void addCallback(LSCallbackType type,
                        LSCallback callback)

Adds a new callback for a specific event type. The callback will be called time the given event occurs.

The same callback can be used for different events. Only allowed in states LSState.Stopped or LSState.Modeling.

Note: When a callback is called, the solver is paused. In that state, you can call all the methods marked as "allowed in state LSState.Paused". Calling any other method will throw an error. For example, you can stop the resolution from a callback, retrieve the current solution or retrieve the statistics of the solver but you can't remove a constraint.

Parameters:

type - Event to watch.

callback - Callback. Cannot be null.

Since:

4.0

See Also:

LSCallback

removeCallback

public boolean removeCallback(LSCallbackType type,
                              LSCallback callback)

Removes the callback for the given event type.

Parameters:

type - Event.

callback - User callback to delete.

Returns:

false if the callback was not added for the given event, true otherwise.

Since:

4.0

See Also:

addCallback(localsolver.LSCallbackType, localsolver.LSCallback), LSCallback

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object