HexalyOptimizer Class

class hexaly.optimizer.HexalyOptimizer

This class contains the Hexaly Optimizer environment. It is the main class of the Hexaly Optimizer library. Here are described the basic steps for using Hexaly Optimizer:

  1. Build your model HxModel by creating some expressions HxExpression.

  2. If desired, parameterize and add phases to the solver HxParam, HxPhase.

  3. Run the solver HexalyOptimizer.

  4. Retrieve the best solution found by the solver HxSolution.

  5. Consult the statistics of the resolution HxStatistics.

Please consult HxVersion for copyright and version info.

Summary

Attributes

state

State of the solver.

model

Model associated to this environment.

param

Parameters of the model.

phases

List of the phases of the model.

solution

Best solution found.

statistics

Statistics.

Methods

solve

Solves the model.

stop

Aborts the resolution previously launched using solve().

get_state

Gets the state of this Hexaly Optimizer environment.

get_model

Gets the model associated to this Hexaly Optimizer environment.

get_param

Gets the parameters of this Hexaly Optimizer environment.

create_phase

Adds a new phase to this Hexaly Optimizer environment.

get_phase

Gets the phase with the given index.

get_nb_phases

Gets the number of phases.

get_solution

Gets the best solution found by the solver.

get_statistics

Gets the statistics of this Hexaly Optimizer environment.

save_environment

Export a complete environment or a model to a file.

load_environment

Import a complete environment from a file.

compute_inconsistency

Computes an inconsistency core for this model.

add_callback

Add a new callback for a specific event type.

remove_callback

Remove the callback for the given event type.

delete

Deletes the Hexaly Optimizer objects and releases the licence token.

Special methods

__str__

Returns a string representation of this Hexaly Optimizer environment.

Instance methods

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.

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 HxState.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:

solve()

See:

add_callback()

HexalyOptimizer.get_state()

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 HxState.RUNNING.

You can also use the shortcut member state

Returns:

State of HexalyOptimizer.

Return type:

.HxState

HexalyOptimizer.get_model()

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

You can also use the shortcut member model

Returns:

Model

Return type:

HxModel

HexalyOptimizer.get_param()

Gets the parameters of this Hexaly Optimizer environment.

You can also use the shortcut member param

Returns:

Parameters

Return type:

HxParam

HexalyOptimizer.create_phase()

Adds a new phase to this Hexaly Optimizer environment. Only allowed in states HxState.MODELING or HxState.STOPPED.

Returns:

Created phase.

Return type:

HxPhase

HexalyOptimizer.get_phase(phase_id)

Gets the phase with the given index.

You can also use the shortcut collection phases.

Parameters:

phase_id (int) – Index of the phase

Returns:

Phase

Return type:

HxPhase

HexalyOptimizer.get_nb_phases()

Gets the number of phases.

You can also use the shortcut collection phases.

Returns:

Number of phases.

Return type:

int

HexalyOptimizer.get_solution()

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 HxState.PAUSED or HxState.STOPPED.

You can also use the shortcut member solution

Returns:

The best solution.

Return type:

HxSolution

HexalyOptimizer.get_statistics()

Gets the statistics of this Hexaly Optimizer environment. Statistics are reset to zero before each resolution. Only allowed in states HxState.PAUSED or HxState.STOPPED. Note that for performance reasons, this function always returns the same object.

You can also use the shortcut member statistics

Returns:

Statistics.

Return type:

HxStatistics

HexalyOptimizer.save_environment(filename)

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, 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. 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 (str) – Name of the file.

Since:

3.0

HexalyOptimizer.load_environment(filename)

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

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

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 (str) – Name of the file.

Since:

3.0

HexalyOptimizer.compute_inconsistency()

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

Returns:

Inconsistency core

Return type:

HxInconsistency

Since:

6.0

HexalyOptimizer.add_callback(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 HxState.PAUSED”.

The same callback can be used for different events. Only allowed in states HxState.STOPPED or HxState.MODELING.

The callback function must accept 2 parameters that are respectively the Hexaly Optimizer environment and the type of the event.

Parameters:
  • type (HxCallbackType) – Event to watch.

  • callback (function) – User callback. Cannot be null.

Since:

4.0

HexalyOptimizer.remove_callback(type, callback)

Remove the callback for the given event type.

Parameters:
  • type (HxCallbackType) – Event

  • callback (function) – User callback to delete

Returns:

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

Return type:

bool

Since:

4.0

HexalyOptimizer.delete()

Deletes the Hexaly Optimizer objects and releases the licence token. It deletes the native memory used by Hexaly Optimizer and makes the Hexaly Optimizer licence available for another Hexaly Optimizer model. This method is automatically called by the garbage collector of Python when it detects that this Hexaly Optimizer object is no longer needed or reachable. This method is also automatically called when you use Hexaly Optimizer in a with statement.

Instance attributes

All get/set methods have their attribute counterpart. You can use them as shortcuts to improve the readability or your models and codes.

HexalyOptimizer.state

State of the solver. This attribute is read-only. It is a shortcut for get_state().

HexalyOptimizer.model

Model associated to this environment. This attribute is read-only. It is a shortcut for get_model().

HexalyOptimizer.param

Parameters of the model. This attribute is read-only. It is a shortcut for get_param().

HexalyOptimizer.phases

List of the phases of the model. This attribute is read-only. The returned object is iterable, supports the len function and can be indexed with integers. It is a shortcut for get_phase() and get_nb_phases() methods. Please note, that you still have to use create_phase() to add phases.

HexalyOptimizer.solution

Best solution found. This attribute is read-only. It is a shortcut for get_solution().

HexalyOptimizer.statistics

Statistics. This attribute is read-only. It is a shortcut for get_statistics().

Special operators and methods

HexalyOptimizer.__str__()

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.

Return type:

str