HexalyOptimizer Class¶

class HexalyOptimizer¶

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

Build your model (HxModel) by creating some expressions (HxExpression).

If desired, parameterize and add phases to the optimizer (HxParam, HxPhase).

Run the optimizer (HexalyOptimizer).

Retrieve the best solution found by the optimizer (HxSolution).

Consult the statistics of the resolution (HxStatistics).

Note that this API is not thread safe: If multiple threads access and modify a same Hexaly Optimizer environment, it must be synchronized.

Please consult HxVersion for copyright and version info.

Summary¶

Functions¶
`HexalyOptimizer`	Constructs a complete HexalyOptimizer environment and takes a token license.
`~HexalyOptimizer`	Deletes this Hexaly Optimizer environment and all associated objects.
`getState`	Gets the state of this Hexaly Optimizer environment.
`getModel`	Gets the model associated to this HexalyOptimizer environment.
`getParam`	Gets the parameters of this HexalyOptimizer 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 HexalyOptimizer environment.
`getPhase`	Gets the phase with the given index.
`getNbPhases`	Gets the number of phases.
`getSolution`	Gets the best solution found by the optimizer.
`getStatistics`	Gets the statistics of this Hexaly Optimizer environment.
`toString`	Returns a string representation of this Hexaly Optimizer 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¶

HexalyOptimizer::HexalyOptimizer()¶: Constructs a complete HexalyOptimizer 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 Hexaly Optimizer environment is called.

HexalyOptimizer::~HexalyOptimizer()¶: Deletes this Hexaly Optimizer 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.

HxState HexalyOptimizer::getState() const¶

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

Returns:: State of HexalyOptimizer

HxModel HexalyOptimizer::getModel() const¶

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

Returns:: Model

HxParam HexalyOptimizer::getParam() const¶

Gets the parameters of this HexalyOptimizer environment.

Returns:: Parameters

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

HxInconsistency HexalyOptimizer::computeInconsistency() const¶

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

Returns:: The inconsistency core

void HexalyOptimizer::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:: HexalyOptimizer::solve()
See:: HexalyOptimizer::addCallback()

HxPhase HexalyOptimizer::createPhase()¶

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

Returns:: Created phase.

HxPhase HexalyOptimizer::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 HexalyOptimizer::getNbPhases() const¶

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

Returns:: Number of phases.

HxSolution HexalyOptimizer::getSolution() const¶

Gets the best solution found by the optimizer. If the optimizer 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.

HxStatistics HexalyOptimizer::getStatistics() const¶

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

Returns:: Statistics.
See:: HxStatistics

std::string HexalyOptimizer::toString() const¶

Returns a string representation of this Hexaly Optimizer 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 Hexaly Optimizer.

void HexalyOptimizer::saveEnvironment(const std::string &filename) const¶

Export a complete environment or a model to a file.

Currently, this function supports 2 file formats :

HXB : 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. This format was also known as LSB which corresponds to its former file extension (.lsb). It is still supported by this method but it is deprecated.
HXM : with this format, only the model is exported in the Hexaly modeling 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:: HexalyOptimizer::loadEnvironment()
Since:: 3.0

void HexalyOptimizer::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 HXB.

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

void HexalyOptimizer::addCallback(HxCallbackType type, HxCallback *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 optimizer 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 optimizer but you can’t remove a constraint.

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

Parameters: