Merge pull request #37 from ds4dm/LSTraits

Expose linear solver options

Project.toml

@@ -11,6 +11,7 @@ OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 SuiteSparse = "4607b0f0-06f3-5cda-b6b1-a6196a1729e9"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [compat]
 LDLFactorizations = "^0.4"

docs/make.jl

@@ -6,10 +6,13 @@ makedocs(
     format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true"),
     pages = [
         "Home" => "index.md",
-        "Problem formulation" => "formulation.md",
+        "User manual" => Any[
+            "Problem formulation" => "manual/formulation.md",
+            "Solving linear systems" => "manual/linear_systems.md"
+        ],
         "Reference" => Any[
-            "Linear solvers" => "man/linear_solvers.md"
-        ]
+            "Linear solvers" => "reference/linear_solvers.md"
+        ],
     ]
 )
 

docs/src/formulation.md → docs/src/manual/formulation.md

@@ -1,4 +1,4 @@
-# Formulations
+# Problem formulation
 
 ## Model input
 

docs/src/manual/linear_systems.md

@@ -0,0 +1,108 @@
+```@meta
+CurrentModule = Tulip.TLPLinearAlgebra
+```
+
+# Solving linear systems
+
+The interior-point algorithm in Tulip requires the solution, at each iteration, of the following symmetric quasi-definite _augmented system_
+```math
+\begin{bmatrix}
+    -(\Theta^{-1} + R_{p}) & A^{T}\\
+    A & R_{d}
+\end{bmatrix}
+\begin{bmatrix}
+    \Delta x\\
+    \Delta y
+\end{bmatrix}
+=
+\begin{bmatrix}
+    \xi_d\\
+    \xi_p
+\end{bmatrix}
+```
+where
+* ``\Delta x, \Delta y`` are primal and dual search directions,
+* ``A`` is the problem's constraint matrix,
+* ``\Theta``, ``R_p`` and ``R_d`` are positive diagonal matrices,
+* ``\xi_p, \xi_d`` are right-hand side vectors.
+
+The augmented system above can be reduced to the positive-definite _normal equations system_
+```math
+\begin{array}{rl}
+\left(
+    A (\Theta^{-1} + R_{p})^{-1} A^{T} + R_{d}
+\right)
+\Delta y
+& =
+\xi_{p} + A (Θ^{-1} + R_{p})^{-1} \xi_{d}\\
+\Delta x &= (Θ^{-1} + R_{p})^{-1} (A^{T} \Delta y - \xi_{d})
+\end{array}
+```
+When selected, this reduction is transparent to the interior-point algorithm.
+
+
+To enable the use of fast external libraries and/or specialized routines, the resolution of linear systems is performed by a _linear solver_ object.
+Linear solvers can be customized with the options below.
+
+## Linear solver options
+
+### System
+
+```@docs
+LinearSystem
+```
+
+```@docs
+DefaultSystem
+```
+
+```@docs
+AugmentedSystem
+```
+
+```@docs
+NormalEquations
+```
+
+
+### Backend
+
+```@docs
+LSBackend
+```
+
+```@docs
+DefaultBackend
+```
+
+```@docs
+Lapack
+```
+
+```@docs
+Cholmod
+```
+
+```@docs
+LDLFact
+```
+
+### 
+
+
+## Supported linear solvers
+
+Here is a list of currently supported linear solvers:
+
+| Linear solver type | `Tv` | System | `LSBackend` | Method |
+|:-------------------|:----:|:------:|:-------:|:-------|
+| [`DenseLinearSolver`](@ref) | `Real` | `NormalEquations` | `Lapack` | Cholesky
+| [`SparseIndefLinearSolver`](@ref) | `Float64` | `AugmentedSystem` | `Cholmod` | LDL
+| [`SparsePosDefLinearSolver`](@ref) | `Float64` | `NormalEquations` | `Cholmod` | Cholesky
+| [`LDLFLinearSolver`](@ref) | `Real` | `AugmentedSystem` | `LDLFact` | LDL
+
+### Default options
+If no option is specified, then the linear solver is chosen as follows:
+* ``A`` is dense: `DenseLinearSolver`
+* If ``A`` sparse and `Tv` is `Float64`: `SparseIndefLinearSolver`
+* All other cases: `LDLFLinearSolver`

docs/src/reference/linear_solvers.md

@@ -0,0 +1,82 @@
+```@meta
+CurrentModule = Tulip.TLPLinearAlgebra
+```
+
+### AbstractLinearSolver
+
+This is the base type from which all implementations should derive.
+
+```@docs
+AbstractLinearSolver
+```
+
+Custom linear solvers should inherit from the `AbstractLinearSolver` class,
+and extend the following two functions:
+
+```@docs
+update_linear_solver!
+```
+
+```@docs
+solve_augmented_system!
+```
+
+### DenseLinearSolver
+
+```@docs
+DenseLinearSolver
+```
+
+```@docs
+update_linear_solver!(::DenseLinearSolver{Tv},::AbstractVector{Tv},::AbstractVector{Tv},::AbstractVector{Tv}) where{Tv<:Real}
+update_linear_solver!(::DenseLinearSolver{Tv},::AbstractVector{Tv},::AbstractVector{Tv},::AbstractVector{Tv}) where{Tv<:BlasReal}
+```
+
+```@docs
+solve_augmented_system!(::Vector{Tv},::Vector{Tv},::DenseLinearSolver{Tv}, ::Vector{Tv}, ::Vector{Tv}) where{Tv<:Real}
+solve_augmented_system!(::Vector{Tv},::Vector{Tv},::DenseLinearSolver{Tv}, ::Vector{Tv}, ::Vector{Tv}) where{Tv<:BlasReal}
+```
+
+### SparseIndefLinearSolver
+
+```@docs
+SparseIndefLinearSolver
+```
+
+```@docs
+update_linear_solver!(::SparseIndefLinearSolver,::AbstractVector{Float64},::AbstractVector{Float64},::AbstractVector{Float64})
+```
+
+```@docs
+solve_augmented_system!(::Vector{Float64},::Vector{Float64},::SparseIndefLinearSolver, ::Vector{Float64}, ::Vector{Float64})
+```
+
+
+
+### SparsePosDefLinearSolver
+
+```@docs
+SparsePosDefLinearSolver
+```
+
+```@docs
+update_linear_solver!(::SparsePosDefLinearSolver,::AbstractVector{Float64},::AbstractVector{Float64},::AbstractVector{Float64})
+```
+
+```@docs
+solve_augmented_system!(::Vector{Float64},::Vector{Float64},::SparsePosDefLinearSolver, ::Vector{Float64}, ::Vector{Float64})
+```
+
+### LDLFLinearSolver
+
+```@docs
+LDLFLinearSolver
+```
+
+```@docs
+update_linear_solver!(::LDLFLinearSolver{Tv},::AbstractVector{Tv},::AbstractVector{Tv},::AbstractVector{Tv}) where{Tv<:Real}
+```
+
+```@docs
+solve_augmented_system!(::Vector{Tv},::Vector{Tv},::LDLFLinearSolver{Tv}, ::Vector{Tv}, ::Vector{Tv}) where{Tv<:Real}
+```