[ library(eplex) | The ECLiPSe Libraries | Reference Manual | Alphabetic Index ]

# lp_get(+Handle, ++ParamName, -Value)

Retrieve information about solver state and results for solver state Handle.

Handle
  Handle to an existing solver state
ParamName
  Name of parameter (atom or structure)
Value
  Returned value for ParamName

## Description

Retrieve information about solver state and results for the (logically) most recent solved solver state represented by `Handle`. `ParamName` is the same as that for eplex_get/2, which retrieves the same information via the EplexInstance. It can be one of:

`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 case of MIP solving, this is the start algorithm (the one that is used to solve the initial relaxation).

`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). Note that the method for solving the root (initial relaxation) node is specified by `method`.

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

`cost`
  Cost 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 specify 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 have been solved to optimality. It can be better than the objective value either because a) (for MIP problems only) the problem have 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 specify 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 have 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:

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

  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.

`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.

`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 would 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 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

The following parameter names are additional aliases that work for either solver:

`feasibility_tol`
  CPX_PARAM_EPRHS (CPLEX) or XPRS_FEASTOL (XPRESS-MP) or OsiPrimalTolerance (OSI) - float
`integrality`
  CPX_PARAM_EPINT (CPLEX) or XPRS_MIPTOL (XPRESS-MP) or CbcIntegerTolerance (OSI,Cbc specific) - float
`iteration_limit`
  CPX_PARAM_ITLIM (CPLEX) or XPRS_LPITERLIMIT (XPRESS-MP) or OsiMaxNumIteration (OSI) -integer
`node_limit`
  CPX_PARAM_NODELIM (CPLEX) or XPRS_MAXNODE (XPRESS-MP) or CbcMaxNumNode (OSI, Cbc specific) -integer
`objdifference`
  CPX_PARAM_OBJDIF (CPLEX) or XPRS_MIPADDCUTOFF (XPRESS-MP) or CbcCutoffIncrement (OSI, Cbc specific) - float
`refactor`
  CPX_PARAM_REINV (CPLEX) or XPRS_INVERTFREQ (XPRESS-MP) -integer
`scrind`
  CPX_PARAM_SCRIND (CPLEX) or XPRS_OUTPUTLOG (XPRESS-MP) -integer

## See Also

lp_setup / 4, lp_set / 3, eplex_get / 2, lp_add_constraints / 4