LocalSolver Class

class localsolver.LocalSolver

This class contains the LocalSolver environment. It is the main class of the 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).

Please consult LSVersion for copyright and version info.

Summary

Methods
Dispose Delete the LocalSolver objects and release the licence token.
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.
GetInfo Returns useful info about the search while running.
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.
ToString Returns a string representation of this LocalSolver environment.

Instance methods

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.

void Dispose()

Delete the LocalSolver objects and release the licence token. This method is automatically called when the LocalSolver object was created in a using statement (see IDisposable interface). Otherwise it must be called explicitly. It deletes the native memory used by LocalSolver and makes the LocalSolver licence available for another LocalSolver model.

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

Returns:State of LocalSolver.
Return type:LSState
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
Return type:LSModel
LSParam GetParam()

Gets the parameters of this LocalSolver environment.

Returns:Parameters
Return type:LSParam
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.

See:LocalSolver.Stop()
LSInconsistency ComputeInconsistency()

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

Returns:Inconsistency core
Return type:LSInconsistency
void Stop()

Aborts the resolution previously launched using Solve(). If no resolution was launched, this method does nothing. Called from another thread, 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 Running.

See:LocalSolver.Solve()
LSPhase CreatePhase()

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

Returns:Created phase.
Return type:LSPhase
LSPhase GetPhase(int phaseId)

Gets the phase with the given index. Only allowed in states Paused or Stopped.

Arguments:phaseId (int) – Index of the phase
Returns:Phase
Return type:LSPhase
int GetNbPhases()

Gets the number of phases. Only allowed in states Paused or Stopped.

Returns:Number of phases.
Return type:int
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 Paused or Stopped.

Returns:The best solution.
Return type:LSSolution
LSStatistics GetStatistics()

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

Returns:Statistics.
Return type:LSStatistics
string GetInfo()

Returns useful info about the search while running. Only allowed if the solver has been started at least once. Only allowed in states Paused or Stopped. Useful for debugging or logging purposes. Here are some explanations about the output string:

  • “sec” stands for the number of seconds.
  • “itr” stands for the number of iterations.
  • “infeas” corresponds to the infeasibility score of the best solution found, if infeasible.
  • “obj” corresponds to the objective values of the best solution found, if feasible.
  • “mov” corresponds to the number of moves performed.
  • “inf” corresponds to the percentage of infeasible moves.
  • “acc” corresponds to the percentage of accepted moves.
  • “imp” corresponds to the number of improving moves.
Returns:Info about the search while running
Return type:string
void SaveEnvironment(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, ...) 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).

Arguments:filename (string) – Name of the file.
Since:3.0
void LoadEnvironment(string filename)

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

The only format supported is LSB. You can obtain a such file thanks to SaveEnvironment().

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.

Arguments:filename (string) – Name of the file.
Since:3.0
void 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. When a callback is called, the solver is paused. You can stop the resolution from a callback, retrieve the current solution, retrieve the statistics of the solver and, in general, call all the methods marked as “allowed in state Paused”.

The same callback can be used for different events.

The callback delegate must accept 2 parameters that are respectively the LocalSolver environment and the type of the event.

Arguments:
Since:

4.0

bool RemoveCallback(LSCallbackType type, LSCallback callback)

Remove the callback for the given event type.

Arguments:
Returns:

False if the callback was not added for the given event, True otherwise.

Return type:

bool

Since:

4.0

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.

Returns:String representation of this LocalSolver.
Return type:string