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

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

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

Type
   library(eplex)

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 cutpool
         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
     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 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:


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


    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)
    integrality - float
	CPX_PARAM_EPINT (CPLEX), XPRS_MIPTOL (XPRESS-MP),
            CbcIntegerTolerance (OSI,Cbc specific), IntFeasTol (Gurobi)
    iteration_limit - integer
	CPX_PARAM_ITLIM (CPLEX), XPRS_LPITERLIMIT (XPRESS-MP),
            OsiMaxNumIteration (OSI), IterationLimit (Gurobi)
    mipgap - float
	CPX_PARAM_EPGAP (CPLEX), XPRS_MIPRELSTOP (XPRESS-MP),
            SolverAllowableFractionGap (OSI), MIPGap (Gurobi)
    node_limit - integer
	CPX_PARAM_NODELIM (CPLEX), XPRS_MAXNODE (XPRESS-MP),
            CbcMaxNumNode (OSI, Cbc specific), NodeLimit (Gurobi)
    objdifference - float
	CPX_PARAM_OBJDIF (CPLEX), XPRS_MIPADDCUTOFF (XPRESS-MP) or
            CbcCutoffIncrement (OSI, Cbc specific)



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