/* -*- mode: C++; indent-tabs-mode: nil; -*-

  *

  * This file is a part of LEMON, a generic C++ optimization library.

  *

  * Copyright (C) 2003-2010

  * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport

  * (Egervary Research Group on Combinatorial Optimization, EGRES).

  *

  * Permission to use, modify and distribute this software is granted

  * provided that this copyright notice appears in all copies. For

  * precise terms see the accompanying LICENSE file.

  *

  * This software is provided "AS IS" with no warranty of any kind,

  * express or implied, and with no claim as to its suitability for any

  * purpose.

  *

  */

 namespace lemon {

 /**

 [PAGE]sec_lp[PAGE] Linear Programming Interface

 Linear programming (LP) is one of the most important general methods of

 operations research. Countless optimization problems can be formulated

 and solved using LP techniques.

 Therefore, developing efficient LP solvers has been of high practical

 interest for a long time.

 Nowadays various efficient LP solvers are available, including both

 open source and commercial software packages.

 Therefore, LEMON does not implement its own solver, but it features

 wrapper classes for several known LP packages providing a common

 high-level interface for all of them.

 The advantage of this approach is twofold. First, our C++ interface is

 more comfortable than the typical native interfaces of the solvers.

 Second, changing the underlying solver in a certain application using

 LEMON's LP interface needs no effort. So, for example, one may try her

 idea using an open source solver, demonstrate its usability for a customer

 and if it works well, but the performance should be improved, then the

 customer may decide to purchase and use a better commercial solver.

 Currently, the following linear and mixed integer programming packages are

 supported: GLPK, Clp, Cbc, ILOG CPLEX and SoPlex.

 However, additional wrapper classes for new solvers can also be implemented

 quite easily.

 [SEC]sec_lp_basics[SEC] Basic LP Features

 The following example demonstrates how simple it is to formalize and solve

 an LP problem in LEMON. You can find the whole program in \ref lp_demo.cc.

 \dontinclude lp_demo.cc

 \skip Create

 \until }

 \until }

 \ref LpBase::Col "Lp::Col" type represents the columns, i.e. the (primal)

 variables of the LP problem. The numerical operators can be used to form

 expressions from columns, which are required for specifying rows

 (constraints) and the objective function. Due to the suitable operator

 overloads, a problem can be described in C++ conveniently, directly as it is

 expressed in mathematics.

 After specifying all the parameters of the problem, we can solve it using

 the \ref LpSolver::solve() "solve()" function. The status of the solution

 (namely OPTIMAL, UNBOUNDED, INFEASIBLE etc.) can be obtained using

 \ref LpSolver::primalType() "primalType()" and the results can be

 obtained using \ref LpSolver::primal() "primal()".

 The above problem has an optimal solution. If you execute this example,

 it will print out the following results.

 \code

   Objective function value: 67.5

   x1 = 7.5

   x2 = 10

 \endcode

 However, if you, for example, removed the lines that specify the rows,

 you would obtain an LP problem, for which the objective function value

 is unbounded over the feasible solutions. Thus the program would print

 out this line.

 \code

   Optimal solution found.

 \endcode

 If you would like to build linear expressions or constraints in more steps,

 then you can use the classes \ref LpBase::Expr "Lp::Expr" and

 \ref LpBase::Constr "Lp::Constr". For example, this line

 \code

   lp.addRow(x1 - 5 <= x2);

 \endcode

 can also be written as

 \code

   Lp::Expr e1, e2;

   e1 = x1;

   e1 -= 5;

   e2 = x2;

   Lp::Constr c = e1 <= e2;

   lp.addRow(c);

 \endcode

 These classes make it easy to build more complex expressions and constraints,

 e.g. using loops. For example, we can sum all the variables (columns) in an

 expression using the \ref LpBase::ColIt "Lp::ColIt" iterator, which can be

 used the same as node and arc iterators for graphs.

 \code

   Lp::Expr sum;

   for (Lp::ColIt col(lp); col != INVALID; ++col) {

     sum += col;

   }

 \endcode

 After solving the problem, you can query the value of any primal expression,

 not just the individual columns and the objective function.

 \todo Check this example after closing ticket #326.

 \code

   std::cout << lp.primal(sum) << std::endl;

 \endcode

 Of course, working with the dual problem is also supported by the LP

 interface. \ref LpBase::Row "Lp::Row" represents the rows, i.e. the dual

 variables of the LP problem.

 \code

   Lp::Row r = lp.addRow(x2 >= 3);

 \endcode

 The dual solutions of an LP problem can be obtained using the functions

 \ref LpSolver::dualType() "dualType()" and \ref LpSolver::dual "dual()"

 (after solving the problem).

 \code

   std::cout << lp.dual(r) << std::endl;

 \endcode

 \ref LpBase::DualExpr "Lp::DualExpr" can be used to build dual expressions

 from rows and \ref LpBase::RowIt "Lp::RowIt" can be used to list the rows.

 \code

   Lp::DualExpr dual_sum;

   for (Lp::RowIt row(lp); row != INVALID; ++row) {

     dual_sum += row;

   }

 \endcode

 The LP solver interface provides several other features, which are

 documented in the classes \ref LpBase and \ref LpSolver.

 For detailed documentation, see these classes in the reference manual.

 If you would like to use a specific solver instead of the default one,

 you can use \ref GlpkLp, \ref ClpLp, \ref CplexLp etc. instead of

 the class \ref Lp.

 [SEC]sec_lp_mip[SEC] Mixed Integer Programming

 LEMON also provides a similar high-level interface for mixed integer

 programming (MIP) solvers. The default MIP solver can be used through

 the class \ref Mip, while the concrete solvers are implemented in the

 classes \ref GlpkMip, \ref CbcMip, \ref CplexMip etc.

 The following example demonstrates the usage of the MIP solver interface.

 The whole program can be found in \ref mip_demo.cc.

 \dontinclude mip_demo.cc

 \skip Create

 \until }

 \until }

 \todo Check this demo file after closing ticket #326.

 E.g. could we write <tt>mip.sol()</tt> instead of <tt>mip.solValue()</tt>?

 Or could we write <tt>primalValue()</tt> for \c Lp in \c lp_demo.cc?

 In this program, the same problem is built as in the above example,

 with the exception that the variable \c x1 is specified to be

 \c INTEGER valued. \c x2 is set to \c REAL, which is the default option.

 \code

   // Set the type of the columns

   mip.colType(x1, Mip::INTEGER);

   mip.colType(x2, Mip::REAL);

 \endcode

 Because of this integrality requirement, the results will be different

 from the LP solution.

 \code

   Objective function value: 67

   x1 = 8

   x2 = 9

 \endcode

 The documentation of the MIP solver interface can be found in the

 reference manual at the class \ref MipSolver. The common parts of the

 LP and MIP interfaces are documented in their common ancestor class

 \ref LpBase.

 [SEC]sec_lp_optimization[SEC] Solving Complex Optimization Problems

 The LP and MIP solvers are powerful tools for solving various complex

 optimization problems, as well.

 The following example solves a maximum flow problem with linear

 programming, see the whole program in \re lp_maxflow_demo.cc.

 Several other graph optimization problems can also be expressed as

 linear programs and the interface provided in LEMON facilitates solving

 them easily (though usually not so efficiently as by a direct

 combinatorial method, if one exists). 

 \dontinclude lp_maxflow_demo.cc

 \skip DIGRAPH_TYPEDEFS

 \until solve()

 \note This problem can be solved much more efficiently using common

 combinatorial optimization methods, such as the \ref Preflow

 "preflow push-relabel algorithm".

 [TRAILER]

 */

 }