LocalSolver Class¶

class LocalSolver¶: LocalSolver environment. Main type of LocalSolver library.

Summary¶

Methods¶
`createPhase`	Creates and adds a new phase to this LocalSolver environment.
`solve`	Solves the model.
`stop`	Aborts the resolution previously launched using solve().
`computeInconsistency`	Compute an inconsistency core for this model.
`loadEnvironment`	Import a complete environment from a file.
`saveEnvironment`	Export a complete environment or a model to a file.
`addCallback`	Add a new callback for a specific event type.
`removeCallback`	Remove the callback for the given event type and previously added with addCallback().

Overloaded operators¶
`enter`	These operators are automatically called when a solver instance is used in a with statement.

Fields¶

LocalSolver.state¶

State of this LocalSolver environment. The returned value can be one of the following strings:

MODELING: Model is being built. This status is returned when the optimization model is not yet closed (or if it has been reopened).
RUNNING: The solve() method has been called. This value can only appear in the modeler when the solver calls an external function.
PAUSED: The solver and all its optimization algorithms are paused. This is the status of the solver when a callback is invoked.
STOPPED: State of the solver when the model is closed but not yet run or when the optimization is finished.

LocalSolver.model¶

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

Return type: LSModel

LocalSolver.solution¶

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.

Return type: LSSolution

LocalSolver.statistics¶

Statistics of this LocalSolver environment. Statistics are reset to zero before each resolution. Only allowed in states PAUSED or STOPPED.

Return type: LSStatistics

LocalSolver.param¶

Parameters of this LocalSolver environment.

Return type: LSParam

LocalSolver.nbPhases¶: Number of phases. Only allowed in states PAUSED or STOPPED.

LocalSolver.phases¶

Phases. This field returns a readonly map-like structure containing lsphases with the following features:

A count field to get the number of phases, e.g. phases.count().
An overloaded index [] operator to get a phase, e.g. phases[0]. The index must be between 0 and phases.count() - 1. Accessing a value outside these bounds throws an exception.
An overloaded iterator operator to iterate over the phases with a for statement.

Return type: map-like structure containing objects of type LSPhase.

Methods¶

LocalSolver.createPhase()¶

Creates and adds a new phase to this LocalSolver environment. Only allowed in state STOPPED.

Returns: New phase.
Return type: LSPhase

LocalSolver.solve()¶: Solves the model. This method returns only when the time limit, the iteration limit, the objective bounds are reached or when the method stop() is called. The model must be closed to launch the resolution.

LocalSolver.stop()¶

Aborts the resolution previously launched using solve(). If no resolution was launched, this method does nothing. Solution and statistics remain valid. This method can be called in any state, notably in state 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: stop()
See: addCallback()

LocalSolver.computeInconsistency()¶

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

Returns: The inconsistency core
Return type: LSInconsistency

LocalSolver.loadEnvironment(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.

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: saveEnvironment()

LocalSolver.saveEnvironment(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).

Parameters: filename – Name of the file.
See: loadEnvironment()

LocalSolver.addCallback(type, 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 must be a function accepting 0, 1 or 2 parameters that are respectively the LocalSolver environment and the type of the event. The type of the event must be a string among:

PHASE_STARTED: Event that occurs when a phase is started.
PHASE_ENDED: Event that occurs when a phase ends.
DISPLAY: Event that occurs regularly before, after and during the search to display useful information about the model and the resolution. The time between two such events can be tuned with the timeBetweenDisplays parameter.
TIME_TICKED: Event that occurs regularly during the resolution. The time between two such events can be tuned with the timeBetweenTicks parameter.
ITERATION_TICKED: Event that occurs regularly during the resolution. The number of iterations between two such events can be tuned with the iterationBetweenTicks parameter.

LocalSolver.removeCallback(type, callback)¶

Remove the callback for the given event type and previously added with addCallback().

Parameters

type – Type of the callback to remove. Must be a string among “PHASE_STARTED”, “PHASE_ENDED”, “DISPLAY”, “TIME_TICKED” or “ITERATION_TICKED”.
callback – Callback to remove. Must be exactly the same instance as the one provided for addCallback().

Returns

True if the callback was removed, false otherwise.

Return type

bool

Operators¶

LocalSolver.enter()¶

LocalSolver.exit()¶

These operators are automatically called when a solver instance is used in a with statement.

enter is called at the beginning of the with statement. It sets the solver as the current solver, the one that will be used when calling the mathematical operators and the keywords minimize, maximize and constraint.

exit restores the previous solver as the current solver (or none).