Merge pull request #26 from ds4dm/UserGuide

User guide

CITATION.bib

@@ -0,0 +1,8 @@
+@TechReport{Tulip.jl,
+    title = {{Tulip}.jl: an open-source interior-point linear optimization
+    solver with abstract linear algebra},
+    url = {https://www.gerad.ca/fr/papers/G-2019-36},
+    Journal = {Les Cahiers du Gerad},
+    Author = {Anjos, Miguel F. and Lodi, Andrea and Tanneau, Mathieu},
+    year = {2019}
+}

README.md

@@ -1,31 +1,69 @@
+# Tulip
 
+| **Documentation** | **Build Status** | **Coverage** |
+|:-----------------:|:----------------:|:----------:|
+| [![](https://img.shields.io/badge/docs-dev-blue.svg)](https://ds4dm.github.io/Tulip.jl/dev/) | [![Build Status](https://travis-ci.org/ds4dm/Tulip.jl.svg?branch=master)](https://travis-ci.org/ds4dm/Tulip.jl) | [![codecov.io](https://codecov.io/github/ds4dm/Tulip.jl/coverage.svg?branch=master)](http://codecov.io/github/ds4dm/Tulip.jl?branch=master)
 
-# Tulip
 
-Tulip is an Interior-Point solver  written entirely in Julia.
-It uses a standard Primal-Dual Predictor-Corrector algorithm to solve Linear Programs (LPs).
+## Overview
+Tulip is an open-source interior-point solver for linear optimization, written in pure Julia.
+It implements the homogeneous primal-dual interior-point algorithm with multiple centrality corrections, and therefore handles unbounded and infeasible problems.
+Tulip’s main feature is that its algorithmic framework is disentangled from linear algebra implementations.
+This allows to seamlessly integrate specialized routines for structured problems.
+
+## Installation
+
+Just install like any Julia package
+
+```julia
+] add Tulip
+```
+
+## Usage
+
+The recommended way of using Tulip is through [JuMP](https://github.com/JuliaOpt/JuMP.jl) and/or [MathOptInterface](https://github.com/JuliaOpt/MathOptInterface.jl) (MOI).
+
+The low-level interface is still under development and will change in the future.
+The user-exposed MOI interface is more stable.
+
+### Using with JuMP
+Tulip follows the syntax convention `PackageName.Optimizer`:
+
+```julia
+using JuMP
+import Tulip
+
+model = Model(with_optimizer(Tulip.Optimizer))
+```
 
-[![Build Status](https://travis-ci.org/ds4dm/Tulip.jl.svg?branch=master)](https://travis-ci.org/ds4dm/Tulip.jl)
+### Using with MOI
 
-[![codecov.io](http://codecov.io/github/ds4dm/Tulip.jl/coverage.svg?branch=master)](http://codecov.io/github/ds4dm/Tulip.jl?branch=master)
+The type `Tulip.Optimizer` is parametrized by the type of numerical data.
+This allows to solve problem in higher numerical precision.
+See the documentation for more details.
 
-[![](https://img.shields.io/badge/docs-dev-blue.svg)](https://ds4dm.github.io/Tulip.jl/dev/)
+```julia
+import MathOptInterface
+MOI = MathOptInterface
+import Tulip
 
-# Overview
+model = Tulip.Optimizer{Float64}()   # Create a model in Float64 precision
+model = Tulip.Optimizer()            # Defaults to the above call
+model = Tulip.Optimizer{BigFloat}()  # Create a model in BigFloat precision
+```
 
-Tulip solves LPs of the form:
+## Citing `Tulip.jl`
 
-$$
-    \begin{array}{rrl}
-    (P) \ \ \ 
-    \displaystyle \min_{x} & c^{T}x\\
-    s.t.
-    & Ax &=b\\
-    & x & \leq u\\
-    & x & \geq 0\\
-    \end{array}
-$$
-where $x, c, u \in \mathbb{R}^{n}$, $A \in \mathbb{R}^{m \times n}$ and $b \in \mathbb{R}^{m}$.
-Some $u_{i}$ may may take infinite value, i.e., the corresponding variable $x_{i}$ has no upper bound.
+If you use Tulip in your work, we kindly ask that you cite the following reference.
+The PDF is freely available [here](https://www.gerad.ca/fr/papers/G-2019-36/view), and serves as a user manual for advanced users.
 
-It uses a primal-dual predictor-corrector interior point.
+```
+@TechReport{Tulip.jl,
+    title = {{Tulip}.jl: an open-source interior-point linear optimization
+    solver with abstract linear algebra},
+    url = {https://www.gerad.ca/fr/papers/G-2019-36},
+    Journal = {Les Cahiers du Gerad},
+    Author = {Anjos, Miguel F. and Lodi, Andrea and Tanneau, Mathieu},
+    year = {2019}
+}
+```

docs/make.jl

@@ -3,8 +3,10 @@ using Documenter, Tulip
 makedocs(
     sitename = "Tulip.jl",
     authors = "Mathieu Tanneau",
+    format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true"),
     pages = [
-        "Home" => "index.md"
+        "Home" => "index.md",
+        "Problem formulation" => "formulation.md"
     ]
 )
 

docs/src/formulation.md

@@ -0,0 +1,37 @@
+# Formulations
+
+## Model input
+
+Tulip takes as input LP problems of the form
+```math
+    \begin{array}{rrcll}
+    (P) \ \ \ 
+    \displaystyle \min_{x} && c^{T}x & + \ c_{0}\\
+    s.t.
+    & l^{b}_{i} \leq & a_{i}^{T} x & \leq u^{b}_{i} & \forall i = 1, ..., m\\
+    & l^{x}_{j} \leq & x_{j} & \leq u^{x}_{j} & \forall j = 1, ..., n\\
+    \end{array}
+```
+where ``l^{b,x}, u^{b, x} \in \mathbb{R} \cup \{ - \infty, + \infty \}``, i.e., some of the bounds may be infinite.
+
+This original formulation is then converted to standard form.
+
+## Standard form
+
+Internally, Tulip solves LPs of the form
+```math
+    \begin{array}{rl}
+    (P) \ \ \ 
+    \displaystyle \min_{x}
+    & c^{T} x + \ c_{0}\\
+    s.t.
+    & A x = b\\
+    & x \leq u\\
+    & x \geq 0
+    \end{array}
+```
+where ``x, c, u \in \mathbb{R}^{n}``, ``A \in \mathbb{R}^{m \times n}`` and ``b \in \mathbb{R}^{m}``.
+Some ``u_{j}`` may may take infinite value, i.e., the corresponding variable ``x_{j}`` has no upper bound.
+
+The original problem is automatically reformulated into standard form before the optimization is performed.
+This transformation is transparent to the user.

docs/src/index.md

@@ -4,23 +4,28 @@ CurrentModule = Tulip
 
 # Tulip.jl
 
-```@contents
-```
+
+## Overview
+
+Tulip is an open-source interior-point solver for linear programming.
+
 
 ## Installation
 
-As of now, `Tulip.jl` is still un-registered, so to install it simply do
+Tulip is 100% Julia, so install it just like any Julia package:
 ```julia
-]
-add https://github.com/ds4dm/Tulip.jl
+julia> ]
+pkg> add Tulip
 ```
 
-## Basic usage
+No additional building step is required.
 
-Coming soon.
 
 ## Citing `Tulip.jl`
 
+If you use Tulip in your work, we kindly ask that you cite the following reference.
+The PDF is freely available [here](https://www.gerad.ca/fr/papers/G-2019-36/view), and serves as a user manual for advanced users.
+
 ```
 @TechReport{Tulip.jl,
     title = {{Tulip}.jl: an open-source interior-point linear optimization