documentation

ZIB-IOL · Sep 18, 2024 · 2f1745d · 2f1745d
1 parent a3c3794
commit 2f1745d
Show file tree

Hide file tree

Showing 3 changed files with 34 additions and 25 deletions.
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,3 +1,4 @@
 [deps]
+AbsSmoothFrankWolfe = "6d364d26-5f85-487f-81b3-ae189dbb3e92"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,6 +1,10 @@
 using Documenter
 using AbsSmoothFrankWolfe
 
+generated_path = joinpath(@__DIR__, "src")
+base_url = "https://github.com/ZIB-IOL/AbsSmoothFrankWolfe.jl/tree/main/"
+isdir(generated_path) || mkdir(generated_path)
+
 open(joinpath(generated_path, "index.md"), "w") do io
     # Point to source license file
     println(
@@ -18,13 +22,13 @@ open(joinpath(generated_path, "index.md"), "w") do io
 end
 
 makedocs(;
-    sitename = "AbsSmoothFW.jl",
-    modules = [AbsSmoothFW],
+    sitename = "AbsSmoothFrankWolfe.jl",
+    modules = [AbsSmoothFrankWolfe],
     format = Documenter.HTML(),
     pages = [
-            "Home" => "index.md",
+            "Home" => "index.md"
    ],
 )
 
-deploydocs(; repo = "github.com/ZIB-IOL/AbsSmoothFW.jl", push_preview=true)
+deploydocs(; repo = "github.com/ZIB-IOL/AbsSmoothFrankWolfe.jl/tree/main", push_preview=true)
 
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -1,3 +1,7 @@
+```@meta
+EditURL = "https://github.com/ZIB-IOL/AbsSmoothFrankWolfe.jl/tree/main/README.md"
+```
+
 # AbsSmoothFrankWolfe.jl
 
 [![CI](https://github.com/ZIB-IOL/AbsSmoothFW.jl/actions/workflows/CI.yml/badge.svg)](https://github.com/ZIB-IOL/AbsSmoothFW.jl/actions/workflows/CI.yml)
@@ -12,10 +16,17 @@ Abs-Smooth Frank-Wolfe algorithms are designed to solve optimization problems of
 
 ## Installation
 
-The most recent release is available on the main branch:
+The most recent release is available via the julia package manager, e.g., with
+
+```julia
+using Pkg
+Pkg.add("AbsSmoothFrankWolfe")
+```
+
+or the main branch:
 
 ```julia
-Pkg.add(url="https://github.com/ZIB-IOL/AbsSmoothFW.jl")
+Pkg.add(url="https://github.com/ZIB-IOL/AbsSmoothFrankWolfe.jl")
 ```
 
 ## Getting started
@@ -24,30 +35,23 @@ Let's say we want to minimize the [LASSO](https://www.jstor.org/stable/2346178?s
 This is what the code looks like:
 
 ```julia
-julia> using FrankWolfe,SparseArrays,LinearAlgebra,JuMP,HiGHS,ADOLC
+julia> using AbsSmoothFrankWolfe,FrankWolfe,LinearAlgebra,JuMP,HiGHS
 
 julia> import MathOptInterface
 
 julia> const MOI = MathOptInterface
 
-julia> include("../src/aasm.jl")
-
-julia> include("../src/as_frank_wolfe.jl")
-
-julia> include("../src/abs_linear.jl")
-
-julia> include("../src/abs_lmo.jl")
-
-julia> n = 5 # lenght(x)
+julia> n = 5 # choose lenght(x)
 
-julia> p = 3 # lenght(y)
+julia> p = 3 # choose lenght(y)
 
 julia> rho = 0.5
 
-julia> A = rand(p,n)
+julia> A = rand(p,n) # randomly choose matrix A
 
-julia> y = rand(p)
+julia> y = rand(p) # randomly choose y
 
+#define the LASSO function
 julia>  function f(x)
 
  	return 0.5*(norm(A*x - y))^2 + rho*norm(x)
@@ -63,7 +67,7 @@ julia> lb_x = [-5 for in in x_base]
 julia> ub_x = [5 for in in x_base]
 
 # call the abs-linear form of f
-julia> abs_normal_form = abs_linear(x_base,f)
+julia> abs_normal_form = AbsSmoothFrankWolfe.abs_linear(x_base,f)
 
 # gradient formula in terms of abs-linearization
 julia> alf_a = abs_normal_form.Y
@@ -74,14 +78,14 @@ julia> z = abs_normal_form.z
 
 julia> s = abs_normal_form.num_switches
 
-julia> sigma_z = signature_vec(s,z)
+julia> sigma_z = AbsSmoothFrankWolfe.signature_vec(s,z)
 
 julia> function grad!(storage, x)
     c = vcat(alf_a', alf_b'.* sigma_z)
     @. storage = c
 end
 
-# define the model
+# define the model using JuMP with HiGHS as inner solver
 julia> o = Model(HiGHS.Optimizer)
 
 julia> MOI.set(o, MOI.Silent(), true)
@@ -92,9 +96,9 @@ julia> @variable(o, lb_x[i] <= x[i=1:n] <= ub_x[i])
 julia> dualgap_asfw = Inf
 
 # abs-smooth lmo
-julia> lmo_as = AbsSmoothLMO(o, x_base, f, n, s, lb_x, ub_x, dualgap_asfw)
+julia> lmo_as = AbsSmoothFrankWolfe.AbsSmoothLMO(o, x_base, f, n, s, lb_x, ub_x, dualgap_asfw)
 
-# define termination criteria
+# define termination criteria using Frank-Wolfe 'callback' function
 julia> function make_termination_callback(state)
  return function callback(state,args...)
   return state.lmo.dualgap_asfw[1] > 1e-2
@@ -104,7 +108,7 @@ end
 julia> callback = make_termination_callback(FrankWolfe.CallbackState)
 
 # call abs-smooth-frank-wolfe
-julia> x, v, primal, dual_gap, traj_data = as_frank_wolfe(
+julia> x, v, primal, dual_gap, traj_data = AbsSmoothFrankWolfe.as_frank_wolfe(
     f, 
     grad!, 
     lmo_as,