WIP: break everything, new docs

.travis.yml

@@ -1,10 +1,10 @@
 language: julia
 os:
     - linux
-    - osx
+#    - osx
 julia:
     - 0.6
-    - nightly
+#    - nightly
 notifications:
     email: false
 sudo: false
@@ -17,7 +17,7 @@ addons:
 script:
     - if [[ -a .git/shallow ]]; then git fetch --unshallow; fi
     - julia -e 'Pkg.clone(pwd())'
-    - julia -e 'Pkg.test("MathProgBase")'
+    #- julia -e 'Pkg.test("MathProgBase")'
 after_success:
     - julia -e 'Pkg.add("Documenter")'
     - julia -e 'cd(Pkg.dir("MathProgBase")); include(joinpath("docs", "make.jl"))'

docs/make.jl

@@ -4,7 +4,11 @@ makedocs(
     format = :html,
     sitename = "MathProgBase",
     pages = [
-        "index.md",
+        "Introduction" => "index.md",
+        "Solver Interface Manual" => "apimanual.md",
+        "Solver Interface API" => "apireference.md",
+        "High-level Interfaces" => "highlevel.md",
+        "Choosing Solvers" => "choosingsolver.md"
     ]
 )
 
@@ -14,5 +18,6 @@ deploydocs(
     osname = "linux",
     julia  = "0.6",
     deps   = nothing,
-    make   = nothing
+    make   = nothing,
+    latest = "break_everything"
 )

docs/src/apimanual.md

@@ -0,0 +1,43 @@
+
+# Solver Interface Manual
+
+## Concepts
+
+We define the standard form problem as:
+
+```math
+\begin{align}
+    & \min_{x \in \mathbb{R}^n} & f_0(x)
+    \\
+    & \;\;\text{s.t.} & f_i(x) & \in \mathcal{S}_i & i = 1 \ldots m
+\end{align}
+```
+
+At the moment all functions are described compactly with lists, vectors, and matrices. NLP is a special case discussed later. An objective function ``f_0`` can be affine or quadratic. The constraint functions ``f_i`` can be variablewise, affine, or quadratic (to be defined).
+
+## Duals
+
+We take the convention that duals on lower bounds (`GreaterThan`) should be nonnegative, duals on upper bounds (`LessThan`) should be nonpositive, and duals on closed convex cones should belong to the dual cone.
+
+For minimization problems in conic form, we can define the primal  as:
+
+```math
+\begin{align}
+& \min_{x \in \mathbb{R}^n} & b_0^Tx
+\\
+& \;\;\text{s.t.} & A_ix + b_i & \in \mathcal{C}_i & \forall i
+\end{align}
+```
+and the dual as:
+
+```math
+\begin{align}
+& \max_{y_i \forall i} & -\sum_i b_i^T y_i
+\\
+& \;\;\text{s.t.} & b_0 - \sum_i A_i^T y_i &= 0
+\\
+& & y_i \in \mathcal{C}_i^* && \forall i
+\end{align}
+```
+
+``a^Tx + b \ge c`` should be interpreted (for the purposes of duals) as ``a^Tx + b - c \in \mathbb{R}_+``, and similarly ``a^Tx + b \le c`` should be interpreted (for the purposes of duals) as ``a^Tx + b - c \in \mathbb{R}_-``. Variablewise constraints should be interpreted as affine constraints with the appropriate identity mapping in place of ``A_i``.

docs/src/apireference.md

@@ -0,0 +1,208 @@
+```@meta
+CurrentModule = MathProgBase
+```
+
+# Solver Interface API
+
+Some introduction to MPB API. List basic standalone methods.
+
+```@docs
+AbstractModel
+AbstractNLPModel
+AbstractMathProgSolver
+```
+
+```@docs
+Model
+NLPModel
+optimize!
+freemodel!
+```
+
+## Variables
+
+```@docs
+VariableReference
+candelete(::AbstractMathProgModel,::VariableReference)
+isvalid(::AbstractMathProgModel,::VariableReference)
+delete!(::AbstractMathProgModel,::VariableReference)
+addvariables!
+addvariable!
+```
+
+## Objectives
+
+How to add and set objectives.
+```@docs
+setobjective!
+modifyobjective!
+getobjectiveconstant
+getobjectiveaffine
+```
+
+## Constraints
+
+How to add and modify constraints.
+```@docs
+VariablewiseConstraintReference
+AffineConstraintReference
+QuadraticConstraintReference
+candelete(::AbstractMathProgModel,::ConstraintReference)
+isvalid(::AbstractMathProgModel,::ConstraintReference)
+delete!(::AbstractMathProgModel,::ConstraintReference)
+addconstraint!
+modifyconstraint!
+getconstraintconstant
+getconstraintaffine
+getconstraintquadratic
+```
+
+## Sets
+
+List of sets.
+```@docs
+AbstractSet
+Reals
+Zeros
+NonNegatives
+NonPositives
+GreaterThan
+LessThan
+Interval
+SecondOrderCone
+ExponentialCone
+DualExponentialCone
+PowerCone
+DualPowerCone
+PositiveSemidefiniteConeTriangle
+PositiveSemidefiniteConeScaled
+Integers
+ZeroOne
+SOS1
+SOS2
+```
+
+Functions for getting and setting properties of sets.
+```@docs
+dimension
+```
+
+## Attributes
+
+### Solver or Model Attributes
+
+List of solver or model attributes.
+```@docs
+ReturnsDuals
+SupportsAddConstraintAfterSolve
+SupportsDeleteConstraint
+SupportsAddVariableAfterSolver
+SupportsQuadraticObjective
+SupportsConicThroughQuadratic
+ObjectiveValue
+ObjectiveBound
+RelativeGap
+SolveTime
+Sense
+SimplexIterations
+BarrierIterations
+NodeCount
+RawSolver
+ResultCount
+NumberOfVariables
+NumberOfVariablewiseConstraints
+NumberOfAffineConstraints
+NumberOfQuadraticConstraints
+SupportsVariablewiseConstraint
+SupportsAffineConstraint
+SupportsQuadraticConstraint
+TerminationStatus
+PrimalStatus
+DualStatus
+```
+
+Functions for getting and setting model or solver attributes.
+```@docs
+AbstractSolverOrModelAttribute
+AbstractVariableAttribute
+AbstractConstraintAttribute
+cangetattribute
+getattribute
+getattribute!
+cansetattribute
+setattribute!
+```
+
+### Variable Attributes
+
+List of attributes associated with variables. Calls to `getattribute` and `setattribute!` should include as an argument a single `VariableReference` or a vector of `VariableReference` objects.
+```@docs
+VariablePrimalStart
+VariablePrimal
+VariableBasisStatus
+```
+
+### Constraint Attributes
+
+List of attributes associated with constraints. Calls to `getattribute` and `setattribute!` should include as an argument a single `ConstraintReference` or a vector of `ConstriaintReference{T}` objects.
+```@docs
+ConstraintPrimalStart
+ConstraintDualStart
+ConstraintPrimal
+ConstraintDual
+ConstraintBasisStatus
+```
+
+## Status Codes
+
+### 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
+```
+
+### Result Status
+
+The `PrimalStatus` and `DualStatus` attributes are meant to explain how to interpret the result returned by the solver. The value of the attributes are of type `ResultStatusCode`.
+```@docs
+ResultStatusCode
+```
+
+### Basis Status
+
+```@docs
+BasisStatusCode
+```
+
+## Nonlinear Programming (NLP)
+
+
+### NLP Methods
+
+```@docs
+loadnlp!
+initialize
+features_available
+eval_f
+eval_grad_f
+jac_structure
+hesslag_structure
+eval_jac_g
+eval_jac_prod
+eval_jac_prod_t
+eval_hesslag_prod
+eval_hesslag
+isobjlinear(::AbstractNLPEvaluator)
+isobjquadratic(::AbstractNLPEvaluator)
+isconstrlinear(::AbstractNLPEvaluator, i::Integer)
+obj_expr
+constr_expr
+```
+
+### NLP Attributes
+
+```@docs
+ConstraintNLPDual
+ConstraintNLPDualStart
+```

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/highlevel.md

@@ -0,0 +1,27 @@
+```@meta
+	CurrentModule = MathProgBase
+```
+
+# High-level Interfaces
+
+**These docs are out of date. We need to update the high-level interfaces for new statuses.**
+
+## Linear Programming
+
+```@docs
+linprog
+buildlp
+solvelp
+```
+
+## Mixed-integer Programming
+
+```@docs
+mixintprog
+```
+
+## Quadratic Programming
+
+```@docs
+quadprog
+```

docs/src/index.md

@@ -1 +1,8 @@
-# MathProgBase documentation
+# MathProgBase
+
+[MathProgBase.jl](https://github.com/JuliaOpt/MathProgBase.jl) is a standardized API for Mathematical Optimization solvers. [JuMP](https://github.com/JuliaOpt/JuMP.jl) uses MathProgBase as a solver-independent low-level backend, but MathProgBase may be used freely without JuMP. In addition to the low-level API, MathProgBase provides one-shot functions for linear, mixed-integer, and quadratic optimization problems.
+
+```@contents
+Pages = ["apireference.md","highlevel.md","choosingsolver.md"]
+Depth = 3
+```

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