Merge pull request #10 from oxfordcontrol/pg/v0.5.0

Pg/v0.5.0

docs/make_examples_julia.jl

@@ -16,8 +16,12 @@ end
 # not compilation time
 oldstream = stdout
 redirect_stdout(devnull)  #shh!!
-include(joinpath(@__DIR__, "../examples/jl", "example_QP.jl"))
-include(joinpath(@__DIR__, "../examples/jl/", "example_SOCP.jl"))
+include(joinpath(@__DIR__, "../examples/jl", "example_intro.jl"))
+include(joinpath(@__DIR__, "../examples/jl", "example_qp.jl"))
+include(joinpath(@__DIR__, "../examples/jl/", "example_socp.jl"))
+include(joinpath(@__DIR__, "../examples/jl/", "example_expcone.jl"))
+include(joinpath(@__DIR__, "../examples/jl/", "example_powcone.jl"))
+include(joinpath(@__DIR__, "../examples/jl/", "example_sdp.jl"))
 include(joinpath(@__DIR__, "./src/literate/", "arbitrary_precision.jl"))
 include(joinpath(@__DIR__, "./src/literate/", "convex_jl.jl"))
 redirect_stdout(oldstream)

docs/pages.jl

@@ -1,15 +1,33 @@
 examples = [
-      "Basic QP Example" => Any[
-                "Problem Description" => "./examples/example_QP.md",
-                "Julia" => "./examples/jl/example_QP.md",
-                "Rust" => "./examples/rs/example_QP.md",
-                "Python" => "./examples/py/example_QP.md",
+      "Quadratic Program (QP)" => Any[
+            "Problem Description" => "./examples/example_qp.md",
+            "Julia" => "./examples/jl/example_qp.md",
+            "Rust" => "./examples/rs/example_qp.md",
+            "Python" => "./examples/py/example_qp.md",
       ]
-      "Basic SOCP Example" => Any[
-                "Problem Description" => "./examples/example_SOCP.md",
-                "Julia" => "./examples/jl/example_SOCP.md",
-                "Rust" => "./examples/rs/example_SOCP.md",
-                "Python" => "./examples/py/example_SOCP.md",
+      "Second-Order Cone Program (SOCP)" => Any[
+            "Problem Description" => "./examples/example_socp.md",
+            "Julia" => "./examples/jl/example_socp.md",
+            "Rust" => "./examples/rs/example_socp.md",
+            "Python" => "./examples/py/example_socp.md",
+      ]
+      "Exponential Cone Program" => Any[
+            "Problem Description" => "./examples/example_expcone.md",
+            "Julia" => "./examples/jl/example_expcone.md",
+            "Rust" => "./examples/rs/example_expcone.md",
+            "Python" => "./examples/py/example_expcone.md",
+      ]
+      "Power Cone Program" => Any[
+            "Problem Description" => "./examples/example_powcone.md",
+            "Julia" => "./examples/jl/example_powcone.md",
+            "Rust" => "./examples/rs/example_powcone.md",
+            "Python" => "./examples/py/example_powcone.md",
+      ]
+      "Semidefinite Program (SDP)" => Any[
+            "Problem Description" => "./examples/example_sdp.md",
+            "Julia" => "./examples/jl/example_sdp.md",
+            "Rust" => "./examples/rs/example_sdp.md",
+            "Python" => "./examples/py/example_sdp.md",
       ]
 ]
 
@@ -39,6 +57,7 @@ pages = [
       "Citing Clarabel" => "citing.md",
       "Contributing" => "contributing.md",
       "API Reference" => Any[
+          "Supported Cone Types" => "api_cone_types.md",
           "Solver Settings" => "api_settings.md",
           "Julia API" => "api_jl.md",
           "Rust API \u29C9" => "api_rs.md"

docs/src/_common/getting_started_constraints.md

@@ -1,12 +1,4 @@
-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 cones defined below:
-
-Cone Type| Description
------      |   :-----
-`ZeroConeT`    | The set ``\{ 0 \}^{dim}`` that contains the origin
-`NonnegativeConeT` | The nonnegative orthant ``\{ x \in \mathbb{R}^{dim} : x_i \ge 0, \forall i=1,\dots,\mathrm{dim} \}``
-`SecondOrderConeT` | The second-order (Lorenz) cone ``\{ (t,x) \in \mathbb{R}^{dim}  :  \|x\|_2   \leq t \}``
-`ExponentialConeT` | The exponential cone ``\{(x, y, z) : y > 0,~~ ye^{x/y} ≤ z \}``
-`PowerConeT` | The power cone ``\{(x, y, z) : x^\alpha y^{(1-\alpha)} \geq  \|z\|,~ (x,y) \geq 0 \}`` with ``\alpha \in (0,1)``
+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).
 
 
 

docs/src/api_cone_types.md

@@ -0,0 +1,13 @@
+# [Supported Cone Types](@id api-cone-types)
+
+
+Clarabel natively supports optimization problems with conic constraints defined on the following cones:
+
+Cone Type| Constructor | Definition 
+-----      |   :----- | :-----
+Zero cone | `ZeroConeT(n)`    | ``\{ 0 \}^{n}``
+Nonnegative orthant | `NonnegativeConeT(n)` | ``\{ x \in \mathbb{R}^{n} : x_i \ge 0, \forall i=1,\dots,\mathrm{n} \}``
+Second order cone | `SecondOrderConeT(n)` | ``\{ (t,x) \in \mathbb{R}^{n}  :  \|x\|_2   \leq t \}``
+Exponential Cone | `ExponentialConeT()` | ``\{(x, y, z) : y > 0,~~ ye^{x/y} ≤ z \}``
+Power cone | `PowerConeT(a)` |  ``\{(x, y, z) : x^a y^{(1-a)} \geq  \|z\|,~ (x,y) \geq 0 \}`` with ``a \in (0,1)``
+Positive semidefinite cone (triangular part) | `PSDTriangleConeT(n)` | Upper triangular part of the positive semidefinite cone ``\mathbb{S}^{n}_+``. The elements ``x`` of this cone represent the columnwise stacking of the upper triangular part of a positive semidefinite matrix ``X \in \mathbb{S}^{n}_+``, so that ``x \in \mathbb{R}^d`` with ``d = {n(n+1)}/{2}.``

docs/src/api_settings.md

@@ -14,8 +14,6 @@ and interfaces all support the same set of options with identical field names.
 
 The full set of options follows below.
 
-
-
 ## [Settings](@id api-settings)
 
 ```@docs

docs/src/examples/example_QP.md

@@ -1,4 +1,4 @@
-# Basic QP Example
+# QP Example
 
 Suppose that we want to solve the following 2-dimensional quadratic programming problem:
 

docs/src/examples/example_SOCP.md

@@ -1,4 +1,4 @@
-# Basic SOCP Example
+# SOCP Example
 
 Suppose that we want to solve the following 2-dimensional optimization problem:
 

docs/src/examples/example_expcone.md

@@ -0,0 +1,49 @@
+# Exponential Cone Example
+
+In this example we show how to model optimization problems with exponential cone constraints.   The exponential cone is defined as 
+```math 
+\begin{aligned}
+\mathcal{K}_{exp} =& \{(x, y, z) \mid y \geq 0,~ ye^{x/y} \le z\} ~\cup~ \\
+& \{ (x,y,z) \mid   x \leq 0, y = 0, z \geq 0 \}
+\end{aligned}
+```
+
+We will solve the following optimization problem:
+
+```math
+\begin{array}{ll} \text{maximize} &x\\[2ex]
+\text{subject to} &  
+\begin{array}{rl}
+y e^{x / y} &\!\le~z \\ 
+y \!&=~1\\ 
+z \!&=~e^5.
+\end{array}
+\end{array}
+``` 
+
+### Objective function
+
+The Clarabel solver's default configuration expects problems to be posed as minimization problems, so we define:
+
+```math
+P = 0
+\textrm{~~~and~~~}
+q = -
+\begin{bmatrix} 1 & 0 & 0
+\end{bmatrix}^T.
+```
+
+
+### Constraints
+
+The solver's default configuration expects constraints in the form $Ax + s = b$, where $s$ is in a cone or composition of cones.   In this case we can write 
+```math
+\begin{bmatrix} 0 \\ 0 \\ 0
+\end{bmatrix}
+ - I
+\begin{bmatrix} x \\ y \\ z 
+\end{bmatrix} = s
+\in \mathcal{K}_{exp},
+```   
+and then append the two additional equality constraints.
+

docs/src/examples/example_powcone.md

@@ -0,0 +1,34 @@
+# Power Cone Example
+
+In this example we show how to model optimization problems with 3-dimensional power cone constraints.   The power cone is defined as 
+```math 
+`\mathcal{K}_{pow}(\alpha) = \{(x, y, z) \mid x^\alpha y^{(1-\alpha)} 
+\geq  |z|, (x,y) \geq 0 \} 
+```
+with $\alpha \in (0,1)$.
+
+We will solve the following optimization problem:
+
+```math
+\begin{array}{ll} \text{maximize} & x_1^{0.6} y^{0.4} + x_2^{0.1}\\[2ex]
+\text{subject to} &  
+\begin{array}{rl}
+(x_1, y, x_2) &\ge 0 \\
+x_1 + 2y  + 3x_2 &= 3
+\end{array}
+\end{array}
+``` 
+which is equivalent to
+
+```math
+\begin{array}{ll} \text{maximize} & z_1 + z_2\\[2ex]
+\text{subject to} &  
+\begin{array}{rl}
+(x1, y, z1) &\in~\mathcal{K}_{pow}(0.6) \\
+(x2, 1, z2) &\in~\mathcal{K}_{pow}(0.1) \\ 
+x_1 + 2y  + 3x_2 &=~3.
+\end{array}
+\end{array}
+``` 
+
+

docs/src/examples/example_sdp.md

@@ -0,0 +1,90 @@
+# Semidefinite Program (SDP) Example
+
+In this example we show how to model semidefinite programming problems, i.e. problems defined with constraints on the symmetric positive semidefinite cone.
+
+Given some symmetric matrix $X \in \mathbb{R}^{n\times n}$, Clarabel takes only the upper triangular vector of $n(n+1)/2$ entries when imposing semidefinite constraints.   For example, given a $3 \times 3$ symmetric matrix variable  
+```math 
+X = \begin{bmatrix}
+x_1 & x_2 & x_4 \\ 
+x_2 & x_3 & x_5 \\ 
+x_4 & x_5 & x_6
+\end{bmatrix}
+```
+we would take as our decision variable the 6 element vector 
+```math
+x = 
+\begin{bmatrix}
+x_1 & x_2 & x_3 & x_4 & x_5 & x_6
+\end{bmatrix}.
+```
+
+We define an operation 
+```math
+\textrm{vec}(X) = 
+\begin{bmatrix}
+x_1 & \sqrt{2}x_2 & x_3 & \sqrt{2}x_4 & \sqrt{2}x_5 & x_6
+\end{bmatrix}
+```
+on symmetric matrices such that inner products are preserved, i.e. $\textrm{tr}(AB) = 
+\textrm{vec}(A)^T\textrm{vec}(B)$, and will use the relationship 
+```math 
+S \in \mathbb{R}^{n} \quad \Longleftrightarrow \quad \textrm{vec}(S) \in \mathcal{K}_{\text{tri}}^n
+```
+where $\mathcal{K}_{\text{tri}}^n$ is the positive semidefinite triangle cone.
+
+### Problem statement
+
+We will solve the following optimization problem:
+
+```math
+\begin{array}{ll} \text{minimize} &\textrm{trace}(X)\\[2ex]
+\text{subject to} &  
+\begin{gathered}
+\langle A,X\rangle = 1 \\
+X \succeq 0
+\end{gathered}
+\end{array}
+``` 
+
+where $X = X^T \in\mathbb{R}^{3\times 3}$ and the symmetric matrix $A$ is defined as 
+```math 
+A = \begin{bmatrix}
+1 & 2 & 4 \\ 
+2 & 3 & 5 \\ 
+4 & 5 & 6
+\end{bmatrix}
+```
+
+### Objective function
+
+We can model the trace of the matrix $X$ by defining our objective function as 
+```math
+\frac{1}{2}x^TPx + q^Tx  
+```
+with $P = 0$ and 
+$q = \begin{bmatrix}
+1 & 0 & 1 & 0 & 0 & 1
+\end{bmatrix}^T$,
+where the elements of $q$ are chosen to select those elements of $x$ corresonding to the diagonal of the matrix $X$.  
+
+### Constraints
+
+The solver's default configuration expects constraints in the form $Ax + s = b$.   In this we can write our semidefiniteness constraint as 
+```math
+-\text{vec}(X) = s \in \mathcal{K}_{\text{tri}}^n
+```   
+where $\mathcal{K}_{\text{tri}}^n$ is the cone of vectors representing the triangular part of matrices in $\mathbb{S}_+^n$.
+
+
+For the equality constraint can we must be careful to rewrite the inner product on $X$ in a form that is an equivalent linear function of $x$.  We therefore write 
+```math 
+\begin{aligned}
+  \langle A,X\rangle &= \textrm{vec}(A)^T\textrm{vec}(X) \\
+  &= \begin{bmatrix}
+1 & (2\cdot 2) & 3 & (2\cdot 4) & (2\cdot 5) & 6
+\end{bmatrix}
+\begin{bmatrix}
+x_1 \\ x_2 \\ x_3 \\ x_4 \\ x_5 \\ x_6
+\end{bmatrix} = 1.
+\end{aligned}
+```

docs/src/examples/jl/.gitignore

@@ -1 +1 @@
-example_*.md
+example_*.md

docs/src/examples/jl/README.md

@@ -1 +1 @@
-Julia examples in this directory are automatically built from the <repo>/examples/jl using the Literate.jl package during documentation build.
+Julia examples in this directory are automatically built from the <repo>/examples/jl using the Literate.jl package during documentation build.   

docs/src/examples/py/example_QP.md

@@ -1,6 +1,6 @@
 ````@eval
 using Documenter
 Documenter.md_include(
-  source = "examples/py/example_QP.py",
+  source = "examples/py/example_qp.py",
   language = :python)
 ````

docs/src/examples/py/example_SOCP.md

@@ -1,6 +1,6 @@
 ````@eval
 using Documenter
 Documenter.md_include(
-  source = "examples/py/example_SOCP.py",
+  source = "examples/py/example_socp.py",
   language = :python)
 ````

docs/src/examples/py/example_expcone.md

@@ -0,0 +1,6 @@
+````@eval
+using Documenter
+Documenter.md_include(
+  source = "examples/py/example_expcone.py",
+  language = :python)
+````

docs/src/examples/py/example_powcone.md

@@ -0,0 +1,6 @@
+````@eval
+using Documenter
+Documenter.md_include(
+  source = "examples/py/example_powcone.py",
+  language = :python)
+````

docs/src/examples/py/example_sdp.md

@@ -0,0 +1,6 @@
+````@eval
+using Documenter
+Documenter.md_include(
+  source = "examples/py/example_sdp.py",
+  language = :python)
+````

docs/src/examples/rs/example_QP.md

@@ -3,6 +3,6 @@ Complete Cargo projects for all Rust examples can be found in [examples/rs](http
 ````@eval
 using Documenter
 Documenter.md_include(
-  source = "examples/rs/example_QP/src/main.rs",
+  source = "examples/rs/example_qp/src/main.rs",
   language = :rust)
 ````

docs/src/examples/rs/example_SOCP.md

@@ -3,6 +3,6 @@ Complete Cargo projects for all Rust examples can be found in [examples/rs](http
 ````@eval
 using Documenter
 Documenter.md_include(
-  source = "examples/rs/example_SOCP/src/main.rs",
+  source = "examples/rs/example_socp/src/main.rs",
   language = :rust)
 ````

docs/src/examples/rs/example_expcone.md

@@ -0,0 +1,8 @@
+Complete Cargo projects for all Rust examples can be found in [examples/rs](https://github.com/oxfordcontrol/ClarabelDocs/tree/main/examples/rs).
+
+````@eval
+using Documenter
+Documenter.md_include(
+  source = "examples/rs/example_expcone/src/main.rs",
+  language = :rust)
+````

docs/src/examples/rs/example_powcone.md

@@ -0,0 +1,8 @@
+Complete Cargo projects for all Rust examples can be found in [examples/rs](https://github.com/oxfordcontrol/ClarabelDocs/tree/main/examples/rs).
+
+````@eval
+using Documenter
+Documenter.md_include(
+  source = "examples/rs/example_powcone/src/main.rs",
+  language = :rust)
+````

docs/src/examples/rs/example_sdp.md

@@ -0,0 +1,8 @@
+Complete Cargo projects for all Rust examples can be found in [examples/rs](https://github.com/oxfordcontrol/ClarabelDocs/tree/main/examples/rs).
+
+````@eval
+using Documenter
+Documenter.md_include(
+  source = "examples/rs/example_sdp/src/main.rs",
+  language = :rust)
+````

docs/src/literate/arbitrary_precision.jl

@@ -18,7 +18,7 @@ solver   = Clarabel.Solver{BigFloat}()
 #=
 ### Objective and constraint data
 
-We next put the objective function into the standard Clarabel.jl form.   Here we use the same problem data as in the [Basic QP Example](@ref), but in `BigFloat` format :
+We next put the objective function into the standard Clarabel.jl form.   Here we use the same problem data as in the [QP Example](@ref), but in `BigFloat` format :
 =#
 
 P = sparse(BigFloat[3. 0.;0. 2.].*2)

docs/src/literate/convex_jl.jl

@@ -18,7 +18,7 @@ For problems with quadratic objective functions, JuMP is generally preferred whe
 
 ## Arbitrary Precision Arithmetic
 
-Clarabel.jl supports arbitrary precision arithmetic for Convex.jl.   Here is the [Basic QP Example](@ref) implemented using `BigFloat` types.
+Clarabel.jl supports arbitrary precision arithmetic for Convex.jl.   Here is the [QP Example](@ref) implemented using `BigFloat` types.
 
 =#