LocalSolver Class

class LocalSolver

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.

Please consult LSVersion for copyright and version info.

Summary

Functions

LocalSolver

Constructs a complete LocalSolver environment and takes a token license.

~LocalSolver

Deletes this LocalSolver environment and all associated objects.

getState

Gets the state of this LocalSolver environment.

getModel

Gets the model associated to this LocalSolver environment.

getParam

Gets the parameters of this LocalSolver environment.

solve

Solves the model.

computeInconsistency

Compute an inconsistency core for this model.

stop

Aborts the resolution previously launched using solve().

createPhase

Adds a new phase to this LocalSolver environment.

getPhase

Gets the phase with the given index.

getNbPhases

Gets the number of phases.

getSolution

Gets the best solution found by the solver.

getStatistics

Gets the statistics of this LocalSolver environment.

toString

Returns a string representation of this LocalSolver environment.

saveEnvironment

Export a complete environment or a model to a file.

loadEnvironment

Import a complete environment from a file.

addCallback

Add a new callback for a specific event type.

removeCallback

Remove the callback for the given event type.

Functions

LocalSolver::LocalSolver()

Constructs a complete LocalSolver environment and takes 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.

LocalSolver::~LocalSolver()

Deletes this LocalSolver environment and all associated objects. In particular, the model, its expressions, the phases, the statistics, and the solution are deleted. The token license is then released.

LSState LocalSolver::getState() const

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

Returns

State of LocalSolver

LSModel LocalSolver::getModel() const

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

Returns

Model

LSParam LocalSolver::getParam() const

Gets the parameters of this LocalSolver environment.

Returns

Parameters

void LocalSolver::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.

LSInconsistency LocalSolver::computeInconsistency() const

Compute an inconsistency core for this model. Only allowed in state S_Stopped.

Returns

The inconsistency core

void LocalSolver::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 S_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

LocalSolver::solve()

See

LocalSolver::addCallback()

LSPhase LocalSolver::createPhase()

Adds a new phase to this LocalSolver environment. Only allowed in state S_Stopped.

Returns

Created phase.

LSPhase LocalSolver::getPhase(int phaseIndex) const

Gets the phase with the given index. Only allowed in states S_Paused or S_Stopped.

Parameters

phaseIndex – Index of the phase.

Returns

Phase

int LocalSolver::getNbPhases() const

Gets the number of phases. Only allowed in states S_Paused or S_Stopped.

Returns

Number of phases.

LSSolution LocalSolver::getSolution() const

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 S_Paused or S_Stopped.

Returns

Best solution.

LSStatistics LocalSolver::getStatistics() const

Gets the statistics of this LocalSolver environment. Statistics are reset to zero before each resolution. Only allowed in states S_Paused or S_Stopped.

Returns

Statistics.

See

LSStatistics

std::string LocalSolver::toString() const

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.

Returns

String representation of this LocalSolver.

void LocalSolver::saveEnvironment(const std::string &filename) const

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, …) 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.

See

LocalSolver::loadEnvironment()

Since

3.0

void LocalSolver::loadEnvironment(const std::string &filename)

Import a complete environment from a file. Only allowed in state S_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.

See

LocalSolver::saveEnvironment()

Since

3.0

void LocalSolver::addCallback(LSCallbackType type, LSCallback *callback)

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

The same callback can be used for different events. Only allowed in states S_Paused or S_Stopped.

Note 1: When a callback is called, the solver is paused. In that state, you can call all the methods marked as “allowed in state S_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.

Note 2: Please note that LocalSolver does not manage memory of objects created outside of its environment. Thus, you have to explicitly remove and delete your LSCallback object at the end of the search.

Parameters
  • type – Event to watch.

  • callback – Callback. Cannot be null.

See

LSCallback

Since

4.0

bool LocalSolver::removeCallback(LSCallbackType type, LSCallback *callback)

Remove 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.

See

LocalSolver::addCallback()

See

LSCallback

Since

4.0