various fixes to docs and docstrings (#21)

* various fixes to docs and docstrings

* address comments

* showing ProxAlg docs

* fixed docs deps

* update docs

Author: lostella

docs/Project.toml

@@ -3,3 +3,5 @@ AbstractOperators = "d9c5613a-d543-52d8-9afd-8f241a8c3f1c"
 DSP = "717857b8-e6f2-59f4-9121-6e50c889abd2"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
+ProximalAlgorithms = "140ffc9f-1907-541a-a177-7475e0a401e9"
+StructuredOptimization = "46cd3e9d-64ff-517d-a929-236bc1a1fc9d"

docs/make.jl

@@ -1,7 +1,8 @@
-using Documenter, StructuredOptimization, LinearAlgebra, DSP, FFTW, AbstractOperators
+using Documenter, StructuredOptimization, 
+LinearAlgebra, DSP, FFTW, AbstractOperators, ProximalAlgorithms
 
 makedocs(
-  modules = [StructuredOptimization],
+  modules = [StructuredOptimization,ProximalAlgorithms],
   format = Documenter.HTML(),
   sitename = "StructuredOptimization",
   authors = "Niccolò Antonello and Lorenzo Stella",

docs/src/solvers.md

@@ -19,18 +19,15 @@
 ## Specifying solver and options
 
 You can pick the algorithm to use as `Solver` object from the
-[`ProximalAlgorithms.jl`](https://github.com/kul-forbes/ProximalAlgorithms.jl))
-package. Currently, the following algorithms are supported:
-
-* `ProximalAlgorithms.ForwardBackward`, also known as *proximal gradient*
-method [[1]](http://www.mit.edu/~dimitrib/PTseng/papers/apgm.pdf), [[2]](http://epubs.siam.org/doi/abs/10.1137/080716542). Nesterov acceleration can be enabled, which significantly
-improves its performance for convex problems.
-* `ProximalAlgorithms.ZeroFPR`, a Newton-type forward-backward algorithm,
-proposed in [[3]](https://arxiv.org/abs/1606.06256), using L-BFGS
-directions to accelerate convergence.
-* `ProximalAlgorithms.PANOC`, another Newton-type forward-backward algorithm,
-proposed in [[4]](https://doi.org/10.1109/CDC.2017.8263933), also using
-L-BFGS directions.
+[`ProximalAlgorithms.jl`](https://github.com/kul-forbes/ProximalAlgorithms.jl)
+package. Currently, the following algorithms are supported.
+
+```@docs
+ForwardBackward
+ZeroFPR
+PANOC
+```
+
 
 ## Parse and solve
 

src/StructuredOptimization.jl

@@ -8,6 +8,9 @@ using AbstractOperators
 using ProximalOperators
 using ProximalAlgorithms
 
+import ProximalAlgorithms:ForwardBackward, ZeroFPR, PANOC
+export ForwardBackward, ZeroFPR, PANOC
+
 include("syntax/syntax.jl")
 include("calculus/precomposeNonlinear.jl") # TODO move to ProximalOperators?
 include("arraypartition.jl") # TODO move to ProximalOperators?

src/solvers/build_solve.jl

@@ -18,7 +18,7 @@ julia> A, b = randn(10,4), randn(10);
 
 julia> p = problem( ls(A*x - b ) , norm(x) <= 1 );
 
-julia> build(p, PG());
+julia> StructuredOptimization.parse_problem(p, ForwardBackward());
 ```
 """
 function parse_problem(terms::Tuple, solver::T) where T <: ForwardBackwardSolver
@@ -65,14 +65,9 @@ julia> A, b = randn(10,4), randn(10);
 
 julia> p = problem(ls(A*x - b ), norm(x) <= 1);
 
-julia> solve(p, ProximalAlgorithms.ForwardBackward());
+julia> solve(p, ForwardBackward());
 
 julia> ~x
-4-element Array{Float64,1}:
- -0.6427139974173074
- -0.29043653211431103
- -0.6090539651510192
-  0.36279278640995494
 ```
 """
 function solve(terms::Tuple, solver::ForwardBackwardSolver)

src/solvers/minimize.jl

@@ -1,37 +1,32 @@
-export @minimize 
+export @minimize
 
 """
-`@minimize cost [st ctr] [with slv_opt]`
+    @minimize cost [st ctr] [with slv_opt]
 
-Minimize a given problem with cost function `cost`, constraints `ctr` and solver options `slv_opt`. 
+Minimize a given problem with cost function `cost`, constraints `ctr` and solver options `slv_opt`.
 
 # Example
 
 ```julia
-julia> A, b = randn(10,4), randn(10);
+julia> using StructuredOptimization
+
+julia> A, b, x = randn(10,4), randn(10), Variable(4);
 
 julia> @minimize ls(A*x-b) + 0.5*norm(x);
-    it |      gamma |        fpr |        tau |        FBE |
- ------|------------|------------|------------|------------|
-     1 | 2.9152e-02 | 2.7656e+00 | 1.0000e+00 | 5.5181e+00 |
-     9 | 2.9152e-02 | 9.9682e-05 | 1.0000e+00 | 4.4086e+00 |
+
+julia> ~x  # access array with solution
 
 julia> @minimize ls(A*x-b) st x >= 0.;
-    it |      gamma |        fpr |        tau |        FBE |
- ------|------------|------------|------------|------------|
-     1 | 5.8304e-02 | 1.0068e+00 | 1.0000e+00 | 6.6282e+00 |
-     3 | 5.8304e-02 | 9.5210e-16 | 1.0000e+00 | 6.5654e+00 |
 
-julia> it, slv = @minimize ls(A*x-b) st norm(x) == 2.0 with PG(maxit = 5);
-    it |      gamma |        fpr |
- ------|------------|------------|
-     1 | 6.1373e-02 | 2.2090e+01 |
-     5 | 3.0686e-02 | 5.5190e-01 |
+julia> ~x  # access array with solution
 
-```
+julia> @minimize ls(A*x-b) st norm(x) == 2.0 with ForwardBackward(fast=true);
 
-Returns as output a tuple containing the number of iterations and the constructed solver.
+julia> ~x  # access array with solution
+```
 
+Returns as output a tuple containing the optimization variables and the number
+of iterations spent by the solver algorithm.
 """
 macro minimize(cf::Union{Expr, Symbol})
 	cost = esc(cf)