complete Readme.md, add tests, add function overloads to src

README.md

@@ -1,7 +1,6 @@
 # ProxTV
 
 [![Stable Documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://nathanemac.github.io/ProxTV.jl/stable)
-[![In development documentation](https://img.shields.io/badge/docs-dev-blue.svg)](https://nathanemac.github.io/ProxTV.jl/dev)
 [![Build Status](https://github.com/nathanemac/ProxTV.jl/workflows/Test/badge.svg)](https://github.com/nathanemac/ProxTV.jl/actions)
 [![Test workflow status](https://github.com/nathanemac/ProxTV.jl/actions/workflows/Test.yml/badge.svg?branch=main)](https://github.com/nathanemac/ProxTV.jl/actions/workflows/Test.yml?query=branch%3Amain)
 [![Lint workflow Status](https://github.com/nathanemac/ProxTV.jl/actions/workflows/Lint.yml/badge.svg?branch=main)](https://github.com/nathanemac/ProxTV.jl/actions/workflows/Lint.yml?query=branch%3Amain)
@@ -12,13 +11,47 @@
 
 [![All Contributors](https://img.shields.io/github/all-contributors/nathanemac/ProxTV.jl?labelColor=5e1ec7&color=c0ffee&style=flat-square)](#contributors)
 
+ProxTV.jl is a Julia package that provides a collection of exact and inexact proximal operators. This includes the Total Variation (TV) regularization with any p-norm.
+
+This package is a Julia implementation of the ProxTV package for MATLAB and Python which is available [here](https://github.com/albarji/proxTV). Behind those implementations, there is a C++ library that provides the core of the proximal operators.
+
+## How to Use
+
+The package is designed to be easy to use and to provide a consistent interface for all the implemented proximal operators.
+
+### Installation
+
+You can install ProxTV.jl using the Julia package manager. From the Julia REPL, type `]` to enter the Pkg REPL mode and run:
+
+```julia
+pkg> add ProxTV
+```
+
+### Example
+
+Here is an example of how to use ProxTV.jl to compute the proximal operator of the Total Variation (TV) regularization with a p-norm on a 1D signal.
+
+```julia
+
+using ProxTV
+
+n = rand(10:100)
+lambda = 0.15
+y = rand(n)
+x = zeros(n)
+p = 1.32 # inexact prox computation : no closed-form for p = 1.32
+ProxTV.TV(y, lambda, x, p)
+```
+
+Other examples can be found in the [documentation](https://nathanemac.github.io/ProxTV.jl/stable).
+
 ## How to Cite
 
 If you use ProxTV.jl in your work, please cite using the reference given in [CITATION.cff](https://github.com/nathanemac/ProxTV.jl/blob/main/CITATION.cff).
 
 ## Contributing
 
-If you want to make contributions of any kind, please first that a look into our [contributing guide directly on GitHub](docs/src/90-contributing.md) or the [contributing page on the website](https://nathanemac.github.io/ProxTV.jl/dev/90-contributing/).
+If you want to make contributions of any kind, please first that a look into our [contributing guide directly on GitHub](docs/src/90-contributing.md).
 
 ---
 

src/libproxtv.jl

@@ -52,6 +52,7 @@ function PN_LPinf(y, lambda, x, info, n, ws)
   )::Int32
 end
 
+# original PN_LPp function
 function PN_LPp(y, lambda, x, info, n, p, ws, positive, objGap)
   @ccall libproxtv.PN_LPp(
     y::Ptr{Float64},
@@ -66,6 +67,25 @@ function PN_LPp(y, lambda, x, info, n, p, ws, positive, objGap)
   )::Int32
 end
 
+# overloaded PN_LPp function with less inputs
+function PN_LPp(y, lambda, x, p, objGap)
+  n = length(y)                  # works for nD signals
+  info = []                      # stores the information about the execution of the function
+  ws = ProxTV.newWorkspace(n)    # define a workspace for memory management
+  positive = all(x -> x >= 0, y) # 0 if false, 1 if true
+  @ccall libproxtv.PN_LPp(
+    y::Ptr{Float64},
+    lambda::Float64,
+    x::Ptr{Float64},
+    info::Ptr{Float64},
+    n::Int32,
+    p::Float64,
+    ws::Ptr{Workspace},
+    positive::Int32,
+    objGap::Float64,
+  )::Int32
+end
+
 function PN_LPp_v2(y, lambda, x, info, n, p, ws, positive)
   @ccall libproxtv.PN_LPp_v2(
     y::Ptr{Float64},
@@ -124,50 +144,21 @@ function TV(y, lambda, x, info, n, p, ws)
   )::Int32
 end
 
-# # overloaded TV function
-# function TV(y, lambda, x, p, ws)
-#   n = length(y) # works for nD signals
-#   info = []
-#   if ws != C_NULL
-#     @warn "Workspace was defined but ignored because of potential memory leak"
-#     ws == C_NULL
-#   end
-#   @ccall libproxtv.TV(
-#     y::Ptr{Float64},
-#     lambda::Float64,
-#     x::Ptr{Float64},
-#     info::Ptr{Float64},
-#     n::Int32,
-#     p::Float64,
-#     ws::Ptr{Workspace},
-#   )::Int32
-# end
-
-# # overloaded TV function
-# function TV(y, lambda, x, p)
-#   @warn "Workspace was not defined. Defining a default workspace : Potential memory leak."
-#   n = length(y) # works for nD signals
-#   info = []
-#   # define a workspace allowing local memory management
-#   ws = newWorkspace(n)
-#   println("Workspace allocated")
-#   try
-#     # Appel de la fonction TV avec le workspace
-#     result = @ccall libproxtv.TV(
-#         y::Ptr{Float64},
-#         lambda::Float64,
-#         x::Ptr{Float64},
-#         info::Ptr{Float64},
-#         n::Int32,
-#         p::Float64,
-#         ws::Ptr{Workspace}  # Passe le workspace alloué
-#     )::Int32
-#   finally
-#     # Libère le workspace une fois l'opération terminée
-#     freeWorkspace(ws)
-#   end
-#   return result
-# end
+# overloaded TV function with less inputs
+function TV(y, lambda, x, p)
+  n = length(y)                  # works for nD signals
+  info = []                      # stores the information about the execution of the function
+  ws = ProxTV.newWorkspace(n)    # define a workspace for memory management
+  @ccall libproxtv.TV(
+    y::Ptr{Float64},
+    lambda::Float64,
+    x::Ptr{Float64},
+    info::Ptr{Float64},
+    n::Int32,
+    p::Float64,
+    ws::Ptr{Workspace},
+  )::Int32
+end
 
 function PN_TV1(y, lambda, x, info, n, sigma, ws)
   @ccall libproxtv.PN_TV1(

test/runtests.jl

@@ -3,18 +3,23 @@ using Test
 using LinearAlgebra
 
 @testset "ProxTV.jl" begin
-  # test on a basic function :
+  # test on a simple function :
   n = 4
   x = rand(n)
   p = 2.0
   @test isapprox(ProxTV.LPnorm(x, n, p), norm(x), atol = 1e-5)
 
-  # test on a more advanced function :
-  lambda = 0.18
-  info = []
-  y = rand(n)
-  x = zeros(n)
-  ws = ProxTV.newWorkspace(n)
-  @test ProxTV.TV(y, lambda, x, info, n, p, ws) == 1 # 1 is the expected return value of the function
+  # test on more advanced functions :
 
+  n = rand(10:100)
+  lambda = 0.15
+  y = rand(n, n)
+  x = zeros(n, n)
+  ws = ProxTV.newWorkspace(n * n)
+  objGap = 1e-5
+  p = 1.32 # inexact prox computation : no closed-form for p = 1.32.
+
+  @test ProxTV.PN_LPp(y, lambda, x, p, objGap) == 1 # 1 is the expected return value of the function. This means that the function has been executed successfully.
+
+  @test ProxTV.TV(y, lambda, x, p) == 1
 end