1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

/*!
Totsu ([凸](http://www.decodeunicode.org/en/u+51F8) in Japanese) means convex.

<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js"></script>

This crate for Rust provides **a first-order conic linear program solver** for convex optimization.

# Target problem

A common target problem is continuous scalar **convex optimization** such as LP, QP, QCQP, SOCP and SDP.
Each of those problems can be represented as a conic linear program:
\\[
\begin{array}{ll}
{\rm minimize} & c^T x \\\\
{\rm subject \ to} & A x + s = b \\\\
& s \in \mathcal{K},
\end{array}
\\]
where
* variables \\( x \in \mathbb{R}^n,\ s \in \mathbb{R}^m \\)
* \\( c \in \mathbb{R}^n \\) as an objective linear operator 
* \\( A \in \mathbb{R}^{m \times n} \\) and \\( b \in \mathbb{R}^m \\) as constraint linear operators 
* a nonempty, closed, convex cone \\( \mathcal{K} \\).

# Algorithm and design concepts

The author combines the two papers
[\[1\]](https://ieeexplore.ieee.org/abstract/document/6126441)
[\[2\]](https://arxiv.org/abs/1312.3039)
so that the homogeneous self-dual embedding matrix in [\[2\]](https://arxiv.org/abs/1312.3039)
is formed as a linear operator in [\[1\]](https://ieeexplore.ieee.org/abstract/document/6126441).

A core method [`solver::Solver::solve`] takes the following arguments:
* objective and constraint linear operators that implement [`solver::Operator`] trait and
* a projection onto a cone that implements [`solver::Cone`] trait.

Therefore solving a specific problem requires an implementation of those traits.
You can use pre-defined implementations: [`totsu` crate](https://crates.io/crates/totsu),
as well as construct a user-defined tailored version for the reason of functionality and efficiency.
This crate also contains several basic structs
that implement [`solver::Operator`] and [`solver::Cone`] trait.

Core linear algebra operations that [`solver::Solver`] requires
are abstracted by [`solver::LinAlg`] trait,
while subtrait [`LinAlgEx`] is used for the basic structs.
This crate contains a [`LinAlgEx`] implementor:
* [`FloatGeneric`] -
  `num::Float`-generic implementation (pure Rust but slow).

Other crates are also available:
* [`totsu_f64lapack` crate](https://crates.io/crates/totsu_f64lapack) -
  `f64`-specific implementation using BLAS/LAPACK.
* [`totsu_f32cuda` crate](https://crates.io/crates/totsu_f32cuda) -
  `f32`-specific implementation using CUDA(cuBLAS/cuSOLVER).

# Features

This crate can be used without the standard library (`#![no_std]`).
Use this in `Cargo.toml`:

```toml
[dependencies.totsu_core]
version = "0.*"
default-features = false
features = ["libm"]
```

# Examples

See [examples in GitHub](https://github.com/convexbrain/Totsu/tree/master/examples).

# References

1. T. Pock and A. Chambolle.
   "Diagonal preconditioning for first order primal-dual algorithms in convex optimization."
   2011 International Conference on Computer Vision. IEEE, 2011.
1. B. O’donoghue, et al.
   "Conic optimization via operator splitting and homogeneous self-dual embedding."
   Journal of Optimization Theory and Applications 169.3 (2016): 1042-1068.
1. N. Parikh and S. Boyd.
   "Proximal algorithms."
   Foundations and Trends in optimization 1.3 (2014): 127-239.
1. Mosek ApS.
   "MOSEK modeling cookbook."
   (2020).
1. S. Boyd and L. Vandenberghe.
   "Convex Optimization."
   (2004).
*/

#![no_std]

pub mod solver;

//

mod linalg_ex;

pub use linalg_ex::*;

//

mod floatgeneric;

pub use floatgeneric::*;

//

mod matop;

pub use matop::*;

//

mod cone_zero;
mod cone_rpos;
mod cone_soc;
mod cone_rotsoc;
mod cone_psd;

pub use cone_zero::*;
pub use cone_rpos::*;
pub use cone_soc::*;
pub use cone_rotsoc::*;
pub use cone_psd::*;