
lp_setup(+NormConstraints, +Objective, ++ListOfOptions, -Handle)

   Create a new external solver state for the constraints NormConstraints.

Arguments
   NormConstraints     normalised constraints
   Objective           Objective function: min(CostExpr) or max(CostExpr)
   ListOfOptions       List of solver options
   Handle              handle to solver state

Type
   library(eplex)

Description

    Create a new solver state for the set of constraints NormConstraints
    (see normalise_cstrs/3 for how to obtain a set of normalised
    constraints).  Apart from the explicitly listed constraints, the
    variable's ranges will be taken into account as the variable bounds for
    the simplex algorithm.  Undeclared variables are implicitly declared as
    reals.


    However, when variables have been declared integers by other solvers (e.g.
    integers/1 of the ic library) that is not taken into account by the
    solver by default.  This means that the solver will only work on the
    relaxed problem (ie. ignoring the integrality constraints),
    unless specified otherwise in the options.


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


    Options is a list of options (see below). Unless explicitly specified
    otherwise, each option should occur no more than once.



    A solver-handle Handle is returned which is used to refer to the solver
    subsequently.


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


The solver Options are:

integers(+ListOfVars)
    Consider the specified variables to be integers (whether or not
    they have been declared such).
    This option will instruct the external solver to use its own MIP solver
    (ie. branch-and-bound search happens within the external solver).

reals(+ListOfVars)
    Consider the specified variables to be problem variables, but does
    not otherwise constrain the variables. This option allows variables to
    be added to the problem without requiring them to occur in other
    constraints. 

method(+Method)
    Use the specified method (default, auto, primal, dual, net,
    barrier, sifting, concurrent, concurrent_det) (representing Primal
    Simplex, Dual Simplex, Network Simplex, Barrier, Sifting etc) to solve
    the problem. For MIP problems, 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.
 
    For some of the methods, an additional `auxiliary' method may be 
    specified in brackets. These are:


      net(Simplex): 
      specifies the Simplex method (primal or dual) to 
      follow the network optimisation. For LP problems only.

      barrier(Crossover): 
      specifies how the crossover to a basic solution from the barrier
      solution is performed. Crossover can be primal, 
      dual, or none. none means no crossover is
      performed. 

      sifting(SubMethod): 
      specifies the method for solving the sifting subproblem. 
      SubMethod can be primal, dual, net, barrier.


    For all the auxiliary methods, default can also be specified.
    This is equivalent to not specifying an auxiliary method at all. 

    Note that not every method is available on every external solver.
    The default method would use the solver's default method, or any
    selections done via solver-specific optimizer_param(_) settings.


node_method(+Method)
    For MIP problems only. Use the specified method (default, primal,
    dual, net, barrier, sifting) to solve the subproblem at each node
    of the MIP search-tree, except the root node, which is specified by
    method option above. See method option for more description of
    the methods. Note that there are less choices in the specifications of
    the auxiliary methods that in the method option, due to limitations in
    the solvers. If a specified auxiliary method cannot be used, `default'
    will be used instead.


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. If the problem is a MIP, then depending on
    the external solver, this is either unavailable or are the values for
    the optimal LP node. 
    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. If the problem is a MIP, then depending on
    the external solver, this is either unavailable or are the values for
    the optimal LP node. 
    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.


    mipstart(+Option)
    Use the previous solution values as a warm-start heuristics for
    the MIP search.  This only has an effect for certain solvers (e.g.
    Gurobi), if there are integrality constraints, and if there is a 
    previous solution available.  Possible values are none
    (no mipstart values, the default), all (use previous
    solution for all variables), or integers (use previous
    solution for all variables that are now constrained to be integral).  


    cache_iis(YesNo)
     Specify if an IIS should be computed immediately for an infeasible problem
     (if supported by the external solver), and store it so that it can bee retrieved by
     eplex_get_iis/4 or lp_get_iis/5 (called from within a user-defined infeasible 
     handler). This will be done before the problem can be modified and make the computing 
     of the IIS impossible. The IIS will only be available before the problem is solved
     again, and also before the infeasible solve is backtracked. This option has no effect  
     if the external solver does not support the computation of an IIS. Note that if this 
     option is set, eplex will always ask for an IIS to computed for an infeasible problem, 
     even if it is immediately backtracked by the infeasible handler failing, and that the 
     option is only needed if the problem instance in the external solver is modified 
     before eplex_get_iis/4 or lp_get_iis/5 is called. 
     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/5 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. This can occur multiple
    times, for different sets of variables.


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. This can occur multiple
    times, for different sets of variables.


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.  If the external solver supports per-problem optimizer_params, 
    their global defaults will be used for presolve(yes).

timeout(+TimeOut)
    Set the external solver to time-out after TimeOut seconds.
    TimeOut is a positive number. The solver will abort (in either
    the abort or suboptimal state, depending on if a suboptimal solution
    was found) if the optimal solution was not found within the time
    limit. This should be used instead of setting the solver-specific
    parameter for time-out directly. In cases where the solver expects an
    integer for the time-out interval, the time given is rounded up to the
    next integer value. The timeout is set by setting the external solver's
    timeout settings, and the exact behaviour may be solver dependent.

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_unbounded event.

infeasible_handler(+Goal)
    Specifies a user defined goal Goal to handle the case when the
    external solver found that the problem is infeasible. Goal would be run
    in place of raising the default eplex_infeasible event.  Note
    that the default and logically correct behaviour is to fail, this
    handler is provided to allow the user to analyse the cause of the
    infeasibility. It is recommended that the handler should also fail
    after performing the analysis.

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 when it is first passed to the
    external solver, a default name determined by the solver 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 problem is solved. This allows the problem in an
        eplex_probe/2 or lp_probe/3 to be dumped. As in
        lp_write/3, Format is the format of the dumped
        file and File is its name. Note that the problem is dumped
        each time the external solver is invoked if the problem has cutpool
        constraints, where there may be multiple invocations of the solver
        per solver call. 
        The default without this option is that the problem would not be 
        dumped.

    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. 

sync_bounds(+YesNo)
    This option determines if the bounds of the problems variables are
    synchronised with other solvers (i.e. the generic bounds are obtained
    with get_var_bounds/3 and then passed to the external solver) before
    the external solver is invoked. This was always done for previous
    non-standalone version of eplex. For standalone eplex, as the bounds
    are communicated directly to the external solver, the synchronisation
    of variable bounds is not needed unless the user is using eplex
    co-operatively with other solvers (e.g. ic). Even in such cases, it may
    be more efficient to communicate these bounds changes by explicitly
    programming it, especially if the problem has many variables and bounds
    changes happen only to a few of the variables. Setting YesNo
    to yes should increase compatibility with previous code (but note that
    previous eplex obtained the bounds from a specific bounds keeper like
    ic rather than the generic bounds).  YesNo is one of the atoms
    yes or no, the default is no.




See Also
   lp_add / 3, lp_set / 3, lp_add_vars / 2, lp_add_constraints / 3, lp_solve / 2, lp_probe / 3, lp_get / 3, lp_get_iis / 5, normalise_cstrs / 3, lp_write / 3
