[ library(eplex) | Reference Manual | Alphabetic Index ]

eplex_get(++ParamName, -Value)

EplexInstance:eplex_get(++ParamName, -Value)

Retrieve information about solver state and results for eplex instance EplexInstance.

ParamName: Name of parameter (atom)
Value: Returned value for ParamName

Description

Retrieve information about solver state and the logically most recent results for the eplex instance EplexInstance. ParamName is the same as that for lp_get/3, which retrieves the same information via the solver state.

vars

Returns a term ''(X1,...,Xn) whose arity is the number of variables involved in the solver's constraint set, and whose arguments are these variables.

ints

Returns a list [Xi1,...,Xik] which is the subset of the problem variables that the solver considers to be integers.

constraints_norm

Returns a list of the problem constraints (excluding any cutpool constraints) in normalised form. They may be simplified with respect to the originals that were passed to the problem.

constraints

Returns a list of the problem constraints (excluding any cutppol constraints) in denormalised (readable) form. They may be simplified with respect to the originals that were passed to the problem.

objective

Returns a term min(E) or max(E), representing objective function and optimisation direction. E is a linear expression: any quadratic components will not be retrieved.

num_cols

Returns the number of columns (i.e. variables) in the matrix of the solver state.

num_rows

Returns the number of rows (i.e. constraints) in the matrix of the solver state.

num_nonzeros

Returns the number of non-zero coefficients in the matrix of the solver state.

num_ints

Returns the number of columns (i.e. variables) constrained to be integers in the matrix of the solver state.

num_quads

Returns the number of non-zero coefficients in the quadratic coefficient matrix (Q-matrix) of the solver state.

method

Returns the method that is specified to solve the problem. If an auxiliary method can be given for the method, and this auxiliary method is not default, the method will be returned as Method(Aux), e.g. barrier(none). The method will be default unless otherwise specified by the the user (at setup or via eplex_setup/2 or lp_setup/3). In that case, the external solver's defaults and any settings done via optimizer_param(_) will be used.

node_method

Applicable to MIP problems only. Returns the method that is specified to solve the problem at the nodes of the branch-and-bound tree. If an auxiliary method can be given for the method, and this auxiliary method is not default, the method will be returned as Method(Aux), e.g. barrier(none). The method will be default unless otherwise specified by the the user (at setup or via eplex_setup/2 or lp_setup/3). In that case, the external solver's defaults and any settings done via optimizer_param(_) will be used.

status

Status that was returned by the most recent invocation of the external solver.

cost

Objective value (i.e. cost/profit) of the current solution. Fails if no solution has been computed yet.

best_bound

The best bound (for minimisation, the lower bound) on the optimal objective value for the current problem. Together with the worst_bound, this specifies the range for the optimal objective value. Note that a non-empty range does not mean that the problem is feasible unless an objective value (cost) is also available. The best_bound is the same as the current objective value if the problem has been solved to optimality. It can be better than the objective value either because a) (for MIP problems only) the problem has been optimised to within the mipgap tolerance, or b) the problem was not solved to optimality, i.e. it was aborted before the optimal solution was found.

worst_bound

The worst bound (for minimisation, the upper bound) on the optimal objective value for the current problem. Together with the best_bound, this specifies the range for the optimal objective value. Note that a non-empty range does not mean that the problem is feasible unless an objective value (cost) is also available. The worst_bound is the same as the current objective value if a solution has been computed for the problem, whether the problem was solved to optimality or not. Depending on the problem type and method used to solve the problem, a worst bound can be returned for a problem even if the solving of the problem was aborted before a solution was obtained.

typed_solution

Returns a term ''(X1,...,Xn) whose arguments are the properly typed (integer or float) solution values for the corresponding problem variables (vars). The floating point solutions are the same as returned by solution, the integers are obtained by rounding the corresponding floating-point solution to the nearest integer. To instantiate the problem variables to their solutions, unify this term with the corresponding term containing the variables. Note that this unification could fail if two problem variables Xa and Xb were unified after the solution was lasted computed, as the solutions values in the Xa and Xb positions could be different, even though they are now represented by one variable. Fails if no solution has been computed yet.

    instantiate_solution(Handle) :-
        lp_get(Handle, vars, Vars),
        lp_get(Handle, typed_solution, Values),
        Vars = Values.

slack

Returns a list of floating-point values representing the constraint slacks in the logically last solve. The problem consists of normal constraints followed by any added cutpool constraints, and the order corresponds to the list order in constraints for normal constraints, and to cutpool_info(last_added,Info) for the cutpool constraints. Fails if no solution has been computed yet.

slack(Indexes)

Returns a list of floating-point values representing the slack values for the constraints represented by Indexes. Indexes are a list of constraint indices (as returned by lp_add_constraints/4 for normal constraints, and lp_add_cutpool_constraints/4 for cutpool constraints), and the order of the returned list corresponds to the order in Indexes. Fails if no slack value has been computed yet for any of the constraints in Indexes -- note that values are only computed for cutpool constraints if they were added to the problem.

dual_solution

Returns a list of floating-point values representing the dual solutions in the logically last solve. The problem consists of normal constraints followed by any added cutpool constraints, and the order corresponds to the list order in constraints for normal constraints, and to cutpool_info(last_added,Info) for the cutpool constraints. Fails if no solution has been computed yet.

dual_solution(Indexes)

Returns a list of floating-point values representing the dual solutions for the constraints represented by Indexes. Indexes are a list of constraint indices (as returned by lp_add_constraints/4 normal constraints, and lp_add_cutpool_constraints/4 for cutpool constraints), and the order of the returned list corresponds to the order in Indexes. Fails if no dual solution has been computed yet for any of the constraints in Indexes -- note that values are only computed for cutpool constraints if they were added to the problem.

constraints(Indexes)

Returns a list of problem constraints as specified by Indexes in denormalised form. The constraints can be either normal constraints or cutpool constraints.

constraints_norm(Indexes)

Returns a list of problem constraints as specified by Indexes in normalised form. The constraints can be either normal constraints or cutpool constraints.

cutpool_info(Select,Info)

Returns the information specified by Info for the cutpool constraints specified by Select. The returned information is either i) a pair of lists Indexes-Values where Indexes is the index for the constraint in the corresponding position of Values, or ii) a list of Indexes if the information requested is index. Info can be:

index: the indexes for the selected constraints. A list of Indexes are returned.
active: the current active status of the selected constraints. The status is either 0 (not active) or 1 (active). A pair of lists Indexes-ActiveStatus is returned.
add_initially: the current add_initially status of the selected constraints. The status is either 0 (not add) or 1 (add). Note that although inactive constraints have a add_initially status, they will not be added to a problem. A pair of lists Indexes-AddInitially is returned.
binding_state: the binding state for the selected constraints in the logically last solve for the problem. A pair of lists Indexes-BindingStates is returned. To get this information, the slack values must be available from the last solve. The state can be: a) binding - the constraint was satisfied and binding, i.e. it is within tolerance of its RHS value in the normalised form. b) satisfied - the constraint was satisfied but not binding. c) inactive - the constraint was inactive.
constraints_norm: the normalised form of the constraints for the selected constraints is returned in a pair of lists Indexes-Constraints.
constraints: the denormalised form of the constraints for the selected constraints is returned in a pair of lists Indexes-Constraints.

The constraints are selected by Select, which can be:

cstr(Idx): The cutpool constraint as specified by Idx.
group(Name): The cutpool constraints in the group Name. Both active and non-active constraints are returned. Note that the name of the default group is the atom nil ([]).
last_added: The cutpool constraints that were added to the problem in the logically previous solve of the problem. The constraints were either added initially, or were added because they were violated in an intermediate invocation.
last_notadded: The cutpool constraints that were not added to the problem in the logically previous solve of the problem, i.e. they were not violated.
last_inactive: The cutpool constraints that were inactive during the logically last solve of the problem. This does not include any constraints that were added since the last solve.

demon_tolerance

Returns a comma-separated pair (RealTol,IntTol) of floating-point values which specify how far outside a variable's range an lp-solution can fall before lp_demon_setup/5 re-triggers. The tolerances differ for real (default 0.00001) and integer (default 0.5) variables.

simplex_iterations

Returns the external solver's count of simplex iterations.

node_count

Returns the external MIP solver's node count. Note that this may or may not include the initial root node.

statistics

Returns a list of counter values [Successes, Failures, Aborts], indicating how often lp_solve/2 was invoked on the Handle, and how many invocations succeeded, failed and aborted respectively.

timeout

Returns the time-out value for the solver state. This is the amount of CPU time in seconds that the external solver will be allow to spend solving the problem before timing out. The value is 0 if no time-out has been set.

optimizer_param(Param)

Returns the value of the external solver's parameter Param for the problem represented by Handle. The external solver has a number of parameters that affect the way they work, and this queries their values. If Param is not a valid parameter for the solver, an out of range exception is raised. See below for more details on the parameters.

post_equality_when_unified

Returns the value (yes or no) if an equality constraint will be posted to a solver if two variables in the solver's problem are unified.

pool

Returns the name of the eplex instance (if any) associated with the solver state. Fails otherwise. Only useful if called with lp_get/3.

handle

Returns the solver state handle (if any) associated with the eplex instance. Fails otherwise. Only useful if called with eplex_get/2.

Note that reduced_cost, slack, dual_solution can only be retrieved when previously requested in the option list of lp_setup/4 or with lp_set/3. An out of range error will be raised otherwise.

For the external solver's control parameter specified by optimizer_param(Param), Param must be an atom. The Value returned is either an integer, float or atom, depending on the parameter. The parameter is generally specific to a solver and version, and also, they may be problem specific, or global, again depending on the solver version. In all cases, the value returned by lp_get/3 is the current value for the parameter for the problem Handle. Refer to the solver documentation for details on the parameters. The names of the parameters are derived from the names of the parameters in the external solver. For CPLEX, take the parameter name from the CPLEX manual (or cplex.h), remove the CPX_PARAM_ prefix and convert the rest to lower case, e.g.

        CPX_PARAM_NODELIM becomes nodelim.

For XPRESS-MP (version 13 and newer), take the parameter name from the manual (or xpresso.h), remove the XPRS_ prefix (if present) and convert the rest to lower case, e.g.

	XPRS_MAXNODE becomes maxnode.

For Gurobi, take the parameter name from the manual and convert it to all lower case, e.g.

	IntFeasTol becomes intfeastol.

For solvers used via the OSI, there are a few generic parameters supported via OSI, and depending on the actual solver, there may be some additional solver-specific parameters. For the generic parameters, take the parameter name, remove the Osi prefix and convert the rest to lower case, e.g.

        OsiPrimalTolerance becomes primaltolerance

For GLPK, use the names of the parameter structure fields, e.g.

        tol_bnd     from glp_smcp
        ord_alg     from glp_iptcp
        tol_int     from glp_iocp
        msg_lev     for all components

The following parameter names are additional aliases that work for most solvers:

feasibility_tol - float: CPX_PARAM_EPRHS (CPLEX), XPRS_FEASTOL (XPRESS-MP), OsiPrimalTolerance (OSI), FeasibilityTol (Gurobi) or tol_bnd (GLPK)
integrality - float: CPX_PARAM_EPINT (CPLEX), XPRS_MIPTOL (XPRESS-MP), CbcIntegerTolerance (OSI,Cbc specific), IntFeasTol (Gurobi) or tol_int (GLPK)
iteration_limit - integer: CPX_PARAM_ITLIM (CPLEX), XPRS_LPITERLIMIT (XPRESS-MP), OsiMaxNumIteration (OSI), IterationLimit (Gurobi) or it_lim (GLPK)
mipgap - float: CPX_PARAM_EPGAP (CPLEX), XPRS_MIPRELSTOP (XPRESS-MP), SolverAllowableFractionGap (OSI), MIPGap (Gurobi) or mip_gap (GLPK)
node_limit - integer: CPX_PARAM_NODELIM (CPLEX), XPRS_MAXNODE (XPRESS-MP), CbcMaxNumNode (OSI, Cbc specific), NodeLimit (Gurobi) or limit on tree node creation (GLPK)
objdifference - float: CPX_PARAM_OBJDIF (CPLEX), XPRS_MIPADDCUTOFF (XPRESS-MP) or CbcCutoffIncrement (OSI, Cbc specific)

Exceptions

(5) type error: EplexInstance does not a solver setup for it.
(40) stale object handle: Solver state had been previously destroyed.

eplex_get(++ParamName, -Value)

EplexInstance:eplex_get(++ParamName, -Value)

Description

Exceptions

See Also