v0.8.0 docs

oxfordcontrol · May 22, 2024 · 38381bc · 38381bc
1 parent fba7a33
commit 38381bc
Show file tree

Hide file tree

Showing 11 changed files with 105 additions and 28 deletions.
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "ClarabelDocs"
 uuid = "5bffead5-e986-4d40-a894-38d9eb53c10f"
 authors = ["Paul Goulart <[email protected]>"]
-version = "0.6"
+version = "0.8"
 
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

diff --git a/docs/pages.jl b/docs/pages.jl
@@ -52,6 +52,7 @@ pages = [
           ],
           "C/C++" => "user_guide_c_cpp.md",
           "R" => "user_guide_r.md",
+          "Chordal Decomposition" => "user_guide_chordal.md",
       ],
       #"Method" => "method.md",
       "Examples" => examples,

diff --git a/docs/src/_common/getting_started_constraints.md b/docs/src/_common/getting_started_constraints.md
@@ -1,4 +1,4 @@
-The Clarabel interface expects constraints to be presented in the single vectorized form ``Ax + s = b, s \in \mathcal{K}``, where ``\mathcal{K} = \mathcal{K}_1 \times \dots \times \mathcal{K}_p`` and each ``\mathcal{K}_i`` is one of the solver's [supported cone types](@ref api-cone-types).
+The Clarabel interface expects constraints to be presented in the single vectorized form ``Ax + s = b, s \in \mathcal{K}``, where ``\mathcal{K} = \mathcal{K}_1 \times \dots \times \mathcal{K}_p`` and each ``\mathcal{K}_i`` is one of the solver's supported cone types.
 
 
 

diff --git a/docs/src/api_jl.md b/docs/src/api_jl.md
@@ -8,7 +8,7 @@ Clarabel.setup!
 Clarabel.solve!
 ```
 
-## [Supported Cone Types](@id api-cones)
+## [SupportedCone](@id api-cones)
 
 ```@docs
 Clarabel.SupportedCone

diff --git a/docs/src/citing.md b/docs/src/citing.md
@@ -1 +1,50 @@
-A paper describing the Clarabel solver algorithm and implementation will be forthcoming soon.   Until then, we ask that you cite this documentation if you have found Clarabel.jl useful in your work.
+If you find Clarabel useful in your work, please consider citing one or more of the following papers.  For the solver itself:
+
+```
+@misc{Clarabel_2024,
+      title={Clarabel: An interior-point solver for conic programs with quadratic objectives}, 
+      author={Paul J. Goulart and Yuwen Chen},
+      year={2024},
+      eprint={2405.12762},
+      archivePrefix={arXiv},
+      primaryClass={math.OC}
+}
+```
+A preprint is available [here](http://arxiv.org/abs/2405.12762).
+
+
+If you use Clarabel to solve SDPs with decomposable structure:
+
+```
+@InProceedings{Garstka_2020,
+  author  = {Michael Garstka and Mark Cannon and Paul Goulart},
+  title   = {A clique graph based merging strategy for decomposable {SDPs}},
+  year    = {2020},
+  note    = {21th IFAC World Congress},
+  number  = {2},
+  pages   = {7355-7361},
+  volume  = {53},
+  doi     = {10.1016/j.ifacol.2020.12.1255},
+  issn    = {2405-8963},
+  journal = {IFAC-PapersOnLine},
+}
+```
+
+A preprint is available [here](https://arxiv.org/abs/1911.05615).
+
+
+If you use Clarabel to solve problems with generalized power cones:
+
+```
+@misc{chen2023efficient,
+      title={An Efficient IPM Implementation for A Class of Nonsymmetric Cones}, 
+      author={Yuwen Chen and Paul Goulart},
+      year={2023},
+      eprint={2305.12275},
+      archivePrefix={arXiv},
+      primaryClass={math.OC}
+}
+```
+
+
+A preprint is available [here](https://arxiv.org/abs/2305.12275).
diff --git a/docs/src/contributing.md b/docs/src/contributing.md
@@ -2,6 +2,6 @@
 
 Contributions are always welcome:
 
-* Please report any issues and bugs that you encounter in [Issues](https://github.com/oxfordcontrol/clarabel/issues)
+* Please report any issues and bugs that you encounter in [Issues](https://github.com/oxfordcontrol/clarabel/issues).
 
-* As an open source project we are also interested in any projects and applications that use Clarabel.jl. Please let us know via email to: [[email protected]](mailto:[email protected])
+* As an open source project we are also interested in any projects and applications that use Clarabel. Please let us know via email to: [[email protected]](mailto:[email protected]).
diff --git a/docs/src/julia/getting_started_jl.md b/docs/src/julia/getting_started_jl.md
@@ -46,6 +46,7 @@ Documenter.md_include(
   plaintext = true)
 ````
 
+
 We can then define our constraint data as
 
 ```julia
@@ -125,11 +126,14 @@ This takes an internal copy of all data parameters and initializes internal vari
 Now you can solve your problem using:
 ```julia
 solution = Clarabel.solve!(solver)
+solution.x   # primal solution
+solution.z   # dual solution
+solution.s   # slacks
 ```
 
 ## Results
 
-Once the solver algorithm terminates you can inspect the solution using the `solution` object.   The primal solution will be in `solution.x` and the dual solution in `solution.z`. The outcome of the solve is specified in `solution.status` and will be one of the following :
+Once the solver algorithm terminates you can inspect the solution using the `solution` object.  The outcome of the solve is specified in `solution.status` and will be one of the following :
 
 ### Status Codes
 

diff --git a/docs/src/julia/linear_solvers.md b/docs/src/julia/linear_solvers.md
@@ -14,13 +14,12 @@ Symbol | Package | Description
 ---  | :--- | :---
 :qdldl | [QDLDL.jl](https://github.com/osqp/QDLDL.jl)   | Default solver
 :mkl   | [Pardiso.jl](https://github.com/JuliaSparse/Pardiso.jl) | Intel MKL Pardiso
+:panua | [Pardiso.jl](https://github.com/JuliaSparse/Pardiso.jl) | Panua Pardiso
+:ma57 | [HSL.jl](https://github.com/JuliaSmoothOptimizers/HSL.jl) | HSL MA57
 :cholmod | Julia native [ldlt](https://docs.julialang.org/en/v1/stdlib/LinearAlgebra/#LinearAlgebra.ldlt) solver | SuiteSparse.CHOLMOD
 
 !!! note
-    To use the MKL Pardiso solver you must install the respective libraries and the corresponding Julia wrapper. For more information about installing these, visit the [Pardiso.jl](https://github.com/JuliaSparse/Pardiso.jl) repository page.   You must 
-    also bring Pardiso into scope first (i.e. `using Pardiso`) before Clarabel.
+    To use the Pardiso solvers you must install the respective libraries and the corresponding Julia wrapper. For more information about installing these, visit the [Pardiso.jl](https://github.com/JuliaSparse/Pardiso.jl) repository page.   You must also bring Pardiso into scope first (i.e. `using Pardiso`) before solving.
+    The same is true for the HSL MA57 solver, which requires the HSL library and the Julia wrapper [HSL.jl].
 
-
-QDLDL is a single threaded solver written in pure Julia, and is generally adequate for problems of small to medium size.   The MKL Pardiso solver is multi-threaded and may be preferred for very large problem instances, or problems in which the problem data is extremely dense.
-
-Support for additional linear system solvers may be implemented in future releases.   
+QDLDL is a single threaded solver written in pure Julia, and is generally adequate for problems of small to medium size.  
diff --git a/docs/src/python/getting_started_py.md b/docs/src/python/getting_started_py.md
@@ -121,19 +121,28 @@ Finally, populate the solver with problem data and solve:
 solver = clarabel.DefaultSolver(P,q,A,b,cones,settings)
 
 solution = solver.solve()
+solution.x  # primal solution
+solution.z  # dual solution
+solution.s  # primal slacks
 ```
 
 ## Results
 
-Once the solver algorithm terminates you can inspect the solution using the `solution` output.   The primal solution will be in `solution.x` and the dual solution in `solution.z`.  The outcome of the solve is specified in `solution.status` and will be one of the following :
+The outcome of the solve is specified in `solver.solution.status` and will be one of the following :
 
 Status Code  | Description
 ---  | :---
-Solved             |  Solution found
-PrimalInfeasible   |  Problem is primal infeasible
-DualInfeasible     |  Problem is dual infeasible
-MaxIterations      |  Solver halted after reaching iteration limit
-MaxTime            |  Solver halted after reaching time limit
+Unsolved               |  Default value, only occurs prior to calling `solve`
+Solved                 |  Solution found
+PrimalInfeasible       |  Problem is primal infeasible
+DualInfeasible         |  Problem is dual infeasible
+AlmostSolved           |  Solution found (reduced accuracy)
+AlmostPrimalInfeasible |  Problem is primal infeasible (reduced accuracy)
+AlmostDualInfeasible   |  Problem is dual infeasible (reduced accuracy)
+MaxIterations          |  Solver halted after reaching iteration limit
+MaxTime                |  Solver halted after reaching time limit
+NumericalError         |  Solver terminated with a numerical error
+InsufficientProgress   |  Solver terminated due to lack of progress
 
 The total solution time is available in `solution.solve_time`.  
 

diff --git a/docs/src/rust/getting_started_rs.md b/docs/src/rust/getting_started_rs.md
@@ -1,6 +1,8 @@
 # Getting Started
 
-This section describes the process of creating a Clarabel.rs model, populating its settings and problem data, solving the problem and obtaining and understanding results.   It is assumed here that you are building your project using `cargo`.
+This section describes the process of creating a Clarabel.rs model, populating its settings and problem data, solving the problem and obtaining and understanding results.  It is assumed here that you are building your project using `cargo`.
+
+Full documentation for the Rust API is available in the [API Reference](@ref api-ref-rust).
 
 The first step is to make the Clarabel solver a dependency in your project by adding:
 
@@ -158,22 +160,30 @@ solver.solve();
 
 ## Results
 
-Once the solver algorithm terminates you can inspect the solution using the `solution` field of the solver.   The primal solution will be in `solution.x` and the dual solution in `solution.z`, e.g.
+Once the solver algorithm terminates you can inspect the solution using the `solution` field of the solver.  
 
 ```rust
-println!("Solution = {:?}", solver.solution.x);
+println!("Solution status = {:?}", solver.solution.status);
+println!("Primal solution = {:?}", solver.solution.x);
+println!("Dual solution   = {:?}", solver.solution.z);
+println!("Primal slacks   = {:?}", solver.solution.s);
 ```
 
 The outcome of the solve is specified in `solver.solution.status` and will be one of the following :
 
 Status Code  | Description
 ---  | :---
-Unsolved           |  Default value, only occurs prior to calling `solve`
-Solved             |  Solution found
-PrimalInfeasible   |  Problem is primal infeasible
-DualInfeasible     |  Problem is dual infeasible
-MaxIterations      |  Solver halted after reaching iteration limit
-MaxTime            |  Solver halted after reaching time limit
+Unsolved               |  Default value, only occurs prior to calling `solve`
+Solved                 |  Solution found
+PrimalInfeasible       |  Problem is primal infeasible
+DualInfeasible         |  Problem is dual infeasible
+AlmostSolved           |  Solution found (reduced accuracy)
+AlmostPrimalInfeasible |  Problem is primal infeasible (reduced accuracy)
+AlmostDualInfeasible   |  Problem is dual infeasible (reduced accuracy)
+MaxIterations          |  Solver halted after reaching iteration limit
+MaxTime                |  Solver halted after reaching time limit
+NumericalError         |  Solver terminated with a numerical error
+InsufficientProgress   |  Solver terminated due to lack of progress
 
 The total solution time is available in `solver.solution.solve_time`.  
 

diff --git a/docs/src/user_guide_chordal.md b/docs/src/user_guide_chordal.md
@@ -0,0 +1,5 @@
+### [Chordal Decomposition](@id user-guide-chordal)
+
+Clarabel implements a chordal decomposition and clique merging method to solve large-scale semidefinite programming problems.   If the problem has favorable structure, this method can decompose a sparse positive semidefiniteness constraint on a large semidefinite cone into a collection of semidefinite constraints on a collection of smaller cones.  This can lead to significant computational savings in terms of both memory and time. 
+
+Clarabel uses the same decomposition strategy as [COSMO.jl](https://oxfordcontrol.github.io/COSMO.jl/stable/decomposition/).   For details see our [paper](https://arxiv.org/abs/1911.05615) on clique merging techniques and this [presentation](https://vimeo.com/439962112) by Michael Garstka.
Original file line number	Diff line number	Diff line change
		@@ -1,4 +1,4 @@
		The Clarabel interface expects constraints to be presented in the single vectorized form ``Ax + s = b, s \in \mathcal{K}``, where ``\mathcal{K} = \mathcal{K}_1 \times \dots \times \mathcal{K}_p`` and each ``\mathcal{K}_i`` is one of the solver's [supported cone types](@ref api-cone-types).
		The Clarabel interface expects constraints to be presented in the single vectorized form ``Ax + s = b, s \in \mathcal{K}``, where ``\mathcal{K} = \mathcal{K}_1 \times \dots \times \mathcal{K}_p`` and each ``\mathcal{K}_i`` is one of the solver's supported cone types.



Expand Down