EplexInstance:eplex_solver_setup(+Objective, ?Cost, ++ListOfOptions, ++Priority, +TriggerModes)

Objective

Objective function: min(CostExpr) or max(CostExpr)

Cost

Variable bounded by the optimal solution

ListOfOptions

List of solver options

Priority

Scheduling priority

TriggerModes

List of conditions for re-triggering solver

Description

Setup a new external solver state for the eplex instance EplexInstance. The solver state will be associated with EplexInstance; EplexInstance must not already have a solver state associated with it. This predicate allow various options to be specified when setting up the solver state. ListOfOptions allows a list of solver options to be specified, and Priority and TriggerModes allows the solver state to be set up as a demon so that the external solver is automatically invoked when the conditions for re-triggering specified in TriggerModes are met. The external solver can also be invoked explicitly via eplex_solve/1.

Declaratively, this can be seen as a compound constraint representing all the individual linear constraints that have been set so far and are going to be set up later for EplexInstance. Operationally, when the external solver is invoked, the delayed constraints posted to EplexInstance are collected and taken into account.

CostExpr is a linear cost expression (or quadratic, if supported by the external solver).

If the solution is optimal, Cost will be bounded by the external solver: For a minimization problem, each solution's cost becomes a lower bound, for maximization an upper bound on Cost. This technique allows for repeated re-solving with reduced bounds or added constraints.

ListOfOptions is the same as in the low-level primitive lp_demon_setup/6, except that EplexInstance is implicitly associated with the new external solver state, so the collect_from option of lp_demon_setup/6 is not allowed (it is set to collect_from(pool(EplexInstance)) by the predicate). See below for more details.

Priority is the scheduling priority with which the solver gets woken up. This priority determines whether the solver is run before or after other constraints. It is recommended to choose a priority that lies below the priority of more efficient propagation constraints, e.g. 5. 0 can also be specified, in which case the default priority for the predicate (5 unless changed) is used.

TriggerModes specifies under which conditions the external solver will be re-triggered. If no condition is specified, then the solver must be explicitly triggered, usually via eplex_solve/1. The conditions are the same as in the low-level primitive lp_demon_setup/6 called by this predicate. See below (after ListOfOptions descriptions) for more details.

Note: Some external solvers need to write temporary files when they are solving a problem. These are written to the temporary directory specified in ECLiPSe's tmp_dir setting (get_flag/2, set_flag/2).

ListOfOptions are:

initial_solve(+YesNo)

Specifies if an initial solve (call to the external solver) should be performed immediately after problem setup. YesNo is one of the atoms yes or no, the default is yes if any trigger condition is specified in TriggerModes, no if no trigger condition is specified.

method(+Method)

Use the specified method (default, primal, dual, net_primal, net_dual, barrier, barrier_primal, barrier_dual) to solve the problem. Note that some of the methods may not be available on all external solvers. When solving a MIP this specifies the start algorithm (the one that is used to solve the initial relaxation). See the external solver's manual for a description of these methods. The meaning of the default method depends on the external solver.

solution(+YesNo)

Make the solutions available each time the problem has been (re-)solved successfully. YesNo is one of the atoms yes or no, the default is yes.

dual_solution(+YesNo)

Make the dual solutions available each time the problem has been (re-)solved successfully. YesNo is one of the atoms yes or no, the default is no.

slack(+YesNo)

Make the constraint slacks available each time the problem has been (re-)solved successfully. YesNo is one of the atoms yes or no, the default is no.

reduced_cost(+YesNo)

Make the reduced costs available each time the problem has been (re-)solved successfully. YesNo is one of the atoms yes or no, the default is no.

keep_basis(+YesNo)

Store the basis each time the problem has been solved successfully, and use this basis as a starting point for re-solving next time. This option only affects performance. YesNo is one of the atoms yes or no, the default is no.

demon_tolerance(RealTol, IntTol)

Specify how far outside a variable's range an lp-solution can fall before lp_demon_setup/6 re-triggers. RealTol and IntTol are floats and default to 0.00001 and 0.5 respectively.

sos1(VarList)

VarList is a list of variables which the solver should treat as variables of a type 1 special ordered set (SOS), i.e. at most one of the variables in the set can be non-zero.

sos2(VarList)

VarList is a list of variables which the solver should treat as variables of a type 2 special ordered set (SOS), i.e. at most two of the variables in the set can be non-zero.

presolve(+YesNo)

Specify if the external solver should perform presolve for this problem. With presolving, the external solver will transform the problem before solving it. This can lead to significantly faster times to find solutions. However, as the problem has been transformed, some external solvers have restriction on accessing or changing the problem state. In addition, if the solver is repeatedly called because the problem is frequently modified, then presolve may not be an advantage. YesNo is one of the atoms yes or no, the default is determined by the global setting of presolve, which can be changed via lp_set/2. The initial default is yes. Note that the presolve setting cannot be changed for a problem once it is set.

suboptimal_handler(+Goal)

Specifies a user defined goal Goal to handle the case when the external solver returned a suboptimal solution (because the problem was aborted). Goal would be run in place of raising the default eplex_suboptimal event.

unbounded_handler(+Goal)

Specifies a user defined goal Goal to handle the case when the problem is unbounded. Goal would be run in place of raising the default eplex_unknown event.

unknown_handler(+Goal)

Specifies a user defined goal Goal to handle the case when the external solver was not able to determine if the problem is unbounded or infeasible. Goal would be run in place of raising the default eplex_unknown event.

abort_handler(+Goal)

Specifies a user defined goal Goal to handle the case when the external solver aborted without finding any solution. Goal would be run in place of raising the default eplex_abort event.

use_var_names(+YesNo)

Specify if variable names (set using set_var_name/2 of the var_name library) should be passed to the external solver. If a particular variable does not have a name, a solver's default name would be used. Note that for XPRESS-MP, there is a limit on the length of the name, which can be changed between 8 and 64 in steps of 8 with the parameter mpsnamelength (XPRS_MPSNAMELENGTH). Variable names longer than this limit are truncated to the limit. YesNo is one of the atoms yes or no, the default is no.

mip_use_copy(+YesNo)

Some external solvers do not allow a MIP problem to be modified once the MIP search has been started. Eplex works around this problem by making a copy of the problem and solving that, so that the original problem can still be modified. This can be turned off to avoid the overhead of making this copy, in which case the MIP problem cannot be modified. This option is used only when solving a MIP problem, and the external solver does not allow a MIP problem to be modified; otherwise it is ignored. YesNo is one of the atoms yes or no, the default is yes so that the problem can be modified.

write_before_solve(+Format,+File)

This option is most useful for debugging purposes. If given, Eplex will ask the external solver to dump the problem each time the solver is invoked by calling lp_write/3. This allows the problem in an eplex_probe/2 or lp_probe/3 to be dumped. Format and File are simply passed to lp_write/3.

post_equality_when_unified(+YesNo)

This option determines if an equality constraint between two variables will be posted to the solver when these variables are unified. Setting YesNo to no means that the constraint will not be posted. Note that this can lead to the solver's problem becoming inconsistent with ECLiPSe's. YesNo is one of the atoms yes or no, the default is yes.

TriggerModes can be a list of the following specifiers:

inst

re-trigger if a problem variable gets instantiated.

ModuleName:Index

re-trigger when the suspension list given by ModuleName:Index is woken for any of the problem variables. The format for ModuleName:Index is the same as for specifying the suspension list in suspend/3,4.

deviating_inst

re-trigger if a problem variable gets instantiated to a value that differs from its lp-solution more than a tolerance.

bounds

re-trigger each time a variable bound changes.

deviating_bounds

re-trigger each time a variable bound changes such that its lp-solution gets excluded more than a tolerance.

new_constraint

re-trigger each time a new constraint appears.

trigger(Atom)

re-trigger each time the symbolic trigger Atom is pulled by invoking schedule_suspensions/1

pre(Goal)

an additional condition to be used together with other triggers. When the demon is triggered, it first executes PreGoal. Only if that succeeds, does the appropriate external solver get invoked. This provides a way of reducing the number of (possibly expensive) solver invocations when given preconditions are not met.

post(Goal)

this is not a trigger condition, but specifies a goal to be executed after solver success, but before the Cost variable gets constrained. It is intended as a hook for exporting solution information, e.g. copying solutions from the solver state into variable attributes (eg. tentative value), or computing weights for labeling heuristics from the solver state.

The tolerances mentioned can be specified in lp_setup/4 or lp_set/3 as demon_tolerance.

If several trigger conditions are specified, then any of them will trigger the solver.

When a solver demon runs frequently on relatively small problems, it can be important for efficiency to switch off the presolve option to reduce overheads.

See Also

$= / 2, $=< / 2, $>= / 2, =:= / 2, >= / 2, =< / 2, integers / 1, eplex_solver_setup / 1, eplex_probe / 2, eplex_solve / 1, eplex_get / 2, eplex_var_get / 3, lp_demon_setup / 6, lp_setup / 4, get_flag / 2, set_flag / 2