WIP: break everything, new docs

docs/make.jl

@@ -4,7 +4,12 @@ makedocs(
     format = :html,
     sitename = "MathProgBase",
     pages = [
-        "index.md",
+        "Introduction" => "index.md",
+        "Linear Programming" => "linearprog.md",
+        "Mixed-Integer Programming" => "mixedintprog.md",
+        "Quadratic Programming" => "quadprog.md",
+        "Solver Interface" => "solverinterface.md",
+        "Choosing Solver" => "choosingsolver.md"
     ]
 )
 

docs/src/choosingsolver.md

@@ -0,0 +1,10 @@
+# Choosing Solvers
+
+Solvers and solver-specific parameters are specified by [`AbstractMathProgSolver`](@ref) objects, which are provided by particular solver packages. For example, the `Clp` package exports a `ClpSolver` object, which can be passed to [`linprog`](@ref) as follows::
+
+```julia
+    using Clp
+    linprog([-1,0],[2 1],'<',1.5, ClpSolver())
+```
+
+Options are passed as keyword arguments, for example, `ClpSolver(LogLevel=1)`. See the [Clp](https://github.com/mlubin/Clp.jl), [Cbc](https://github.com/mlubin/Cbc.jl), [GLPKMathProgInterface](https://github.com/JuliaOpt/GLPKMathProgInterface.jl), and [Gurobi](https://github.com/JuliaOpt/Gurobi.jl) packages for more information.

docs/src/index.md

@@ -1 +1,7 @@
-# MathProgBase documentation
+# MathProgBase
+
+Solver-independent functions and low-level interfaces for Mathematical Programming
+
+[MathProgBase.jl](https://github.com/JuliaOpt/MathProgBase.jl) provides high-level one-shot functions for linear and mixed-integer programming, as well as a solver-independent low-level interface for implementing advanced techniques that require efficiently solving a sequence of linear programming problems.
+
+To use MathProgBase, an external solver must be installed. See [Choosing Solvers](@ref).

docs/src/linearprog.md

@@ -0,0 +1,11 @@
+# Linear Programming
+
+```@meta
+	CurrentModule = MathProgBase
+```
+
+```@docs
+linprog
+buildlp
+solvelp
+```

docs/src/mixedintprog.md

@@ -0,0 +1,5 @@
+# Mixed-integer Programming
+
+```@docs
+mixintprog
+```

docs/src/quadprog.md

@@ -0,0 +1,9 @@
+# Quadratic Programming
+
+```@meta
+	CurrentModule = MathProgBase
+```
+
+```@docs
+quadprog
+```

docs/src/solverinterface.md

@@ -0,0 +1,107 @@
+# Solver Interface
+
+```@meta
+CurrentModule = MathProgBase
+```
+
+```@docs
+AbstractMathProgModel
+AbstractMathProgSolver
+```
+
+## Basic Methods
+
+```@docs
+optimize!
+freemodel!
+```
+
+## Variables
+
+```@docs
+VariableReference
+candelete(::AbstractMathProgModel,::VariableReference)
+isvalid(::AbstractMathProgModel,::VariableReference)
+delete!(::AbstractMathProgModel,::VariableReference)
+addvariables!
+addvariable!
+```
+
+## Constraints
+
+How to add constraints.
+```@docs
+ConstraintReference
+candelete(::AbstractMathProgModel,::ConstraintReference)
+isvalid(::AbstractMathProgModel,::ConstraintReference)
+delete!(::AbstractMathProgModel,::ConstraintReference)
+addconstraint!
+```
+
+## Sets
+
+
+
+List of sets.
+```@docs
+NonNegative
+NonPositive
+Zero
+Interval
+Integers
+Binaries
+```
+## Attributes
+
+These are used to get and set properties of the model.
+
+```@docs
+AbstractAttribute
+cangetattribute
+getattribute
+cansetattribute
+setattribute!
+```
+
+### Scalar Attributes
+
+```@docs
+ObjectiveValue
+ObjectiveBound
+RelativeGap
+SolveTime
+Sense
+SimplexIterations
+BarrierIterations
+NodeCount
+RawSolver
+ResultCount
+```
+
+### Variable Attributes
+
+These attributes are associated with variables. Calls to `getattribute` and `setattribute!` should include a single `VariableReference` or a vector of `VariableReference` objects.
+
+```@docs
+VariableStart
+VariableLowerBoundDualStart
+VariableUpperBoundDualStart
+VariableLowerBound
+VariableUpperBound
+VariablePrimal
+VariableLowerBoundDual
+VariableUpperBoundDual
+```
+
+
+## Termination Status
+
+The `TerminationStatus` attribute is meant to explain the reason why the solver stopped executing. The value of the attribute is of type `TerminationStatusCode`.
+
+```@docs
+TerminationStatusCode
+```
+
+## Duals
+
+We take the convention that duals on variable lower bounds should be nonnegative, duals on variable upper bounds should be nonpositive, and duals on closed convex cones should belong to the dual cone.

src/HighLevelInterface/HighLevelInterface.jl

@@ -1,8 +1,3 @@
-module HighLevelInterface
-
-using ..SolverInterface
-using ..MathProgBase
-
 function warn_no_inf(T)
     if !(isinf(typemin(T)) && isinf(typemax(T)))
         Base.warn_once("Element type $T does not have an infinite value. Note that this may artifically introduce ranged (two-sided) constraints. To avoid this, consider casting the problem data to Float64.")
@@ -12,5 +7,3 @@ end
 include("linprog.jl")
 include("mixintprog.jl")
 include("quadprog.jl")
-
-end

src/HighLevelInterface/linprog.jl

@@ -29,6 +29,50 @@ function no_lp_solver()
           """)
 end
 
+"""
+    buildlp(c::InputVector, A::AbstractMatrix, sense::InputVector, b::InputVector, lb::InputVector, ub::InputVector, solver::AbstractMathProgSolver)
+
+Builds the linear programming problem as defined in [`linprog`](@ref) and accepts the following arguments:
+
+*    ``c`` is the objective vector, always in the sense of minimization
+
+*    ``A`` is the constraint matrix
+
+*    ``sense`` is a vector of constraint sense characters ``'<'``, ``'='``, and ``'>'``
+
+*    ``b`` is the right-hand side vector
+
+*    ``l`` is the vector of lower bounds on the variables
+
+*    ``u`` is the vector of upper bounds on the variables, and
+
+*    ``solver`` specifies the desired solver, see [Choosing Solvers](@ref).
+
+A scalar is accepted for the ``b``, ``sense``, ``l``, and ``u`` arguments, in which case its value is replicated. The values ``-Inf`` and ``Inf`` are interpreted to mean that there is no corresponding lower or upper bound.
+
+This variant of [`buildlp`](@ref) allows to specify two-sided linear constraints (also known as range constraints) similar to [`linprog`](@ref), and accepts the following arguments:
+
+    buildlp(c::InputVector, A::AbstractMatrix, rowlb::InputVector, rowub::InputVector, lb::InputVector, ub::InputVector, solver::AbstractMathProgSolver)
+
+*    ``c`` is the objective vector, always in the sense of minimization
+
+*    ``A`` is the constraint matrix
+
+*    ``rowlb`` is the vector of row lower bounds
+
+*    ``rowub`` is the vector of row upper bounds
+
+*    ``lb`` is the vector of lower bounds on the variables
+
+*    ``ub`` is the vector of upper bounds on the variables, and
+
+*    ``solver`` specifies the desired solver, see [Choosing Solvers](@ref).
+
+A scalar is accepted for the ``l``, ``u``, ``lb``, and ``ub`` arguments, in which case its value is replicated. The values ``-Inf`` and ``Inf`` are interpreted to mean that there is no corresponding lower or upper bound. Equality constraints are specified by setting the row lower and upper bounds to the same value.
+
+The [`buildlp`](@ref) function returns an [`AbstractLinearQuadraticModel`](@ref) that can be input to [`solvelp`](@ref) in order to obtain a solution.
+"""
+
 function buildlp(c::InputVector, A::AbstractMatrix, rowlb::InputVector, rowub::InputVector, lb::InputVector, ub::InputVector, solver::AbstractMathProgSolver)
     m = LinearQuadraticModel(solver)
     nrow,ncol = size(A)
@@ -73,6 +117,23 @@ function buildlp(c::InputVector, A::AbstractMatrix, rowlb::InputVector, rowub::I
     return m
 end
 
+"""
+Solves the linear programming problem as defined in [`linprog`](@ref) and accepts the following argument:
+
+*    `m` is an [`AbstractLinearQuadraticModel`](@ref) (e.g., as returned by [`buildlp`](@ref)).
+
+The [`solvelp`](@ref) function returns an instance of the type::
+
+```julia
+type LinprogSolution
+    status
+    objval
+    sol
+    attrs
+end
+```
+
+"""
 function solvelp(m)
     optimize!(m)
     stat = status(m)
@@ -101,7 +162,123 @@ function solvelp(m)
         return LinprogSolution(stat, nothing, [], Dict())
     end
 end
+"""
+
+    linprog(c::InputVector, A::AbstractMatrix, rowlb::InputVector, rowub::InputVector, lb::InputVector, ub::InputVector, solver::AbstractMathProgSolver)
+
+This function allows one to specify two-sided linear constraints (also known as range constraints) to solve the linear programming problem:
+
+```math
+\\begin{align*}
+\\text{min}_{x} \\quad & c^{T} x \\\\
+\\text{s.t.}    \\quad & rowlb \\leq A^{T} x \\leq rowub \\\\
+                \\quad & l \\leq x \\leq u \\\\
+
+\\end{align*}
+```
+
+where:
+
+*    ``c`` is the objective vector, always in the sense of minimization
+
+*    ``A`` is the constraint matrix
+
+*    ``rowlb`` is the vector of row lower bounds
+
+*    ``rowub`` is the vector of row upper bounds
+
+*    ``lb`` is the vector of lower bounds on the variables
+
+*    ``ub`` is the vector of upper bounds on the variables, and
+
+*    ``solver`` specifies the desired solver, see [Choosing Solvers](@ref).
+
+A scalar is accepted for the ``l``, ``u``, ``rowlb``, and ``rowub`` arguments, in which case its value is replicated. The values ``-Inf`` and ``Inf`` are interpreted to mean that there is no corresponding lower or upper bound. Equality constraints are specified by setting the row lower and upper bounds to the same value.
+
+A variant usage of this function is to consider the linear programming problem in the following form,
+
+    linprog(c::InputVector, A::AbstractMatrix, sense::InputVector, b::InputVector, lb::InputVector, ub::InputVector, solver::AbstractMathProgSolver)
+
+```math
+\\begin{align*}
+\\text{min}_{x} \\quad & c^{T}x \\\\
+\\text{s.t.}    \\quad & A_{i}^{T} \\, \\text{sense}_{i} \\, b_{i} \\quad \\forall i \\\\
+                \\quad & l \\leq x \\leq u
+\\end{align*}
+```
+
+where:
+
+* ``c``: is the objective vector, always in the sense of minimization
+
+* ``A``: is the constraint matrix, with rows a_i (viewed as column-oriented vectors)
+
+* sense: is a vector of constraint sense characters ``<``, ``=``, and ``>``
+
+* ``b``: is the right-hand side vector
+
+* ``l``: is the vector of lower bounds on the variables
+
+* ``u`` is the vector of upper bounds on the variables, and solver specifies the desired solver, see [Choosing Solvers](@ref).
+
+
+A shortened version is defined as::
+
+    linprog(c, A, lb, ub, solver) = linprog(c, A, lb, ub, 0, Inf, solver)
+
+!!! note
+    The function [`linprog`](@ref) calls two independent functions for building and solving the linear programming problem, namely [`buildlp`](@ref) and [`solvelp`](@ref).
+
+The [`linprog`](@ref) function returns an instance of the type::
+
+```julia
+    type LinprogSolution
+        status
+        objval
+        sol
+        attrs
+    end
+```
+
+where `status` is a termination status symbol, one of `:Optimal`, `:Infeasible`, `:Unbounded`, `:UserLimit` (iteration limit or timeout), `:Error` (and maybe others).
+
+If `status` is `:Optimal`, the other members have the following values:
+
+* `objval` -- optimal objective value
+* `sol` -- primal solution vector
+* `attrs` -- a dictionary that may contain other relevant attributes such as:
+
+  - `redcost` -- dual multipliers for active variable bounds (zero if inactive)
+  - `lambda` -- dual multipliers for active linear constraints (equalities are always active)
+
+If `status` is `:Infeasible`, the `attrs` member will contain an `infeasibilityray` if available; similarly for `:Unbounded` problems, `attrs` will contain an `unboundedray` if available.
+
+  - `colbasis` -- optimal simplex basis statuses for the variables (columns) if available. Possible values are `:NonbasicAtLower`, `:NonbasicAtUpper`, `:Basic`, and `:Superbasic` (not yet implemented by any solvers)
+  - `rowbasis` -- optimal simplex basis statuses for the constraints (rows) if available (not yet implemented by any solvers)
+
+For example, we can solve the two-dimensional problem (see ``test/linprog.jl``):
+
+```math
+    \\begin{align*}
+    \\text{min}_{x,y} \\quad & -x \\\\
+    \\text{s.t.}      \\quad & 2x + y \\leq 1.5 \\\\
+                      \\quad & x \\geq 0, y \\geq 0
+    \\end{align*}
+```
+
+```julia
+    using MathProgBase, Clp
+
+    sol = linprog([-1,0],[2 1],'<',1.5, ClpSolver())
+    if sol.status == :Optimal
+        println("Optimal objective value is \$(sol.objval)")
+        println("Optimal solution vector is: [\$(sol.sol[1]), \$(sol.sol[2])]")
+    else
+        println("Error: solution status \$(sol.status)")
+    end
+```
 
+"""
 function linprog(c::InputVector, A::AbstractMatrix, rowlb::InputVector, rowub::InputVector, lb::InputVector, ub::InputVector, solver::AbstractMathProgSolver)
     m = buildlp(c, A, rowlb, rowub, lb, ub, solver)
     return solvelp(m)