Dont use benchmarktools

Author: avik-pal

Project.toml

@@ -60,7 +60,6 @@ julia = "1.6"
 ArrayInterfaceBandedMatrices = "2e50d22c-5be1-4042-81b1-c572ed69783d"
 ArrayInterfaceBlockBandedMatrices = "5331f1e9-51c7-46b0-a9b0-df4434785e0a"
 BandedMatrices = "aae01518-5342-5314-be14-df237901396f"
-BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 BlockBandedMatrices = "ffab5731-97b5-5995-9138-79e8c1846df0"
 IterativeSolvers = "42fd0dbc-a981-5370-80f2-aaf504508153"
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
@@ -85,5 +84,4 @@ test = [
     "Symbolics",
     "Zygote",
     "StaticArrays",
-    "BenchmarkTools",
 ]

docs/src/index.md

@@ -37,6 +37,67 @@ function g(x) # out-of-place
 end
 ```
 
+## High Level API
+
+We need to perform the following steps to utilize SparseDiffTools:
+
+1. Specify a Sparsity Detection Algorithm. There are 3 possible choices currently:
+    1. `NoSparsityDetection`: This will ignore any AD choice and compute the dense Jacobian
+    2. `JacPrototypeSparsityDetection`: If you already know the sparsity pattern, you can
+       specify it as `JacPrototypeSparsityDetection(; jac_prototype=<sparsity pattern>)`.
+    3. `SymbolicsSparsityDetection`: This will use `Symbolics.jl` to automatically detect
+       the sparsity pattern. (Note that `Symbolics.jl` must be explicitly loaded before
+       using this functionality.)
+2. Now choose an AD backend from `ADTypes.jl`:
+    1. If using a Non `*Sparse*` type, then we will not use sparsity detection.
+    2. All other sparse AD types will internally compute the proper sparsity pattern, and
+       try to exploit that.
+3. Now there are 2 options:
+    1. Precompute the cache using `sparse_jacobian_cache` and use the `sparse_jacobian` or
+       `sparse_jacobian!` functions to compute the Jacobian. This option is recommended if
+       you are repeatedly computing the Jacobian for the same function.
+    2. Directly use `sparse_jacobian` or `sparse_jacobian!` to compute the Jacobian. This
+       option should be used if you are only computing the Jacobian once.
+
+```julia
+using Symbolics
+
+sd = SymbolicsSparsityDetection()
+adtype = AutoSparseFiniteDiff()
+x = rand(30)
+y = similar(x)
+
+# Option 1
+## OOP Function
+cache = sparse_jacobian_cache(adtype, sd, g, x; fx=y) # Passing `fx` is needed if size(y) != size(x)
+J = sparse_jacobian(adtype, cache, g, x)
+### Or
+J_preallocated = similar(J)
+sparse_jacobian!(J_preallocated, adtype, cache, g, x)
+
+## IIP Function
+cache = sparse_jacobian_cache(adtype, sd, f, y, x)
+J = sparse_jacobian(adtype, cache, f, y, x)
+### Or
+J_preallocated = similar(J)
+sparse_jacobian!(J_preallocated, adtype, cache, f, y, x)
+
+# Option 2
+## OOP Function
+J = sparse_jacobian(adtype, sd, g, x)
+### Or
+J_preallocated = similar(J)
+sparse_jacobian!(J_preallocated, adtype, sd, g, x)
+
+## IIP Function
+J = sparse_jacobian(adtype, sd, f, y, x)
+### Or
+J_preallocated = similar(J)
+sparse_jacobian!(J_preallocated, adtype, sd, f, y, x)
+```
+
+## Lower Level API
+
 For this function, we know that the sparsity pattern of the Jacobian is a
 `Tridiagonal` matrix. However, if we didn't know the sparsity pattern for
 the Jacobian, we could use the `Symbolics.jacobian_sparsity` function to automatically

test/test_sparse_jacobian.jl

@@ -21,7 +21,7 @@ x = randn(Float32, 100);
 
 J_true = ForwardDiff.jacobian(fdiff, x);
 
-@info "`ForwardDiff.jacobian` time: $(@belapsed(ForwardDiff.jacobian($fdiff, $x)))s"
+@info "`ForwardDiff.jacobian` time: $(@elapsed(ForwardDiff.jacobian(diff, x)))s"
 
 # SparseDiffTools High-Level API
 J_sparsity = Symbolics.jacobian_sparsity(fdiff, similar(x), x);
@@ -44,15 +44,15 @@ SPARSITY_DETECTION_ALGS = [JacPrototypeSparsityDetection(jac_prototype = J_spars
                 @test J ≈ J_true
                 @inferred sparse_jacobian!(J, difftype, cache, fdiff, x)
 
-                t₁ = @belapsed sparse_jacobian!($J, $difftype, $cache, $fdiff, $x)
+                t₁ = @elapsed sparse_jacobian!(J, difftype, cache, fdiff, x)
                 @info "$(nameof(typeof(difftype)))() `sparse_jacobian!` (only differentiation) time: $(t₁)s"
 
                 J = sparse_jacobian(difftype, cache, fdiff, x)
 
                 @test J ≈ J_true
                 # @inferred sparse_jacobian(difftype, cache, fdiff, x)
 
-                t₂ = @belapsed sparse_jacobian($difftype, $cache, $fdiff, $x)
+                t₂ = @elapsed sparse_jacobian(difftype, cache, fdiff, x)
                 @info "$(nameof(typeof(difftype)))() `sparse_jacobian` (with matrix allocation) time: $(t₂)s"
             end
 
@@ -62,7 +62,7 @@ SPARSITY_DETECTION_ALGS = [JacPrototypeSparsityDetection(jac_prototype = J_spars
                 @test J ≈ J_true
                 # @inferred sparse_jacobian(difftype, sd, fdiff, x)
 
-                t₁ = @belapsed sparse_jacobian($difftype, $sd, $fdiff, $x)
+                t₁ = @elapsed sparse_jacobian(difftype, sd, fdiff, x)
                 @info "$(nameof(typeof(difftype)))() `sparse_jacobian` (complete) time: $(t₁)s"
 
                 cache = sparse_jacobian_cache(difftype, sd, fdiff, x)
@@ -73,7 +73,7 @@ SPARSITY_DETECTION_ALGS = [JacPrototypeSparsityDetection(jac_prototype = J_spars
                 @test J ≈ J_true
                 @inferred sparse_jacobian!(J, difftype, sd, fdiff, x)
 
-                t₂ = @belapsed sparse_jacobian!($J, $difftype, $sd, $fdiff, $x)
+                t₂ = @elapsed sparse_jacobian!(J, difftype, sd, fdiff, x)
                 @info "$(nameof(typeof(difftype)))() `sparse_jacobian!` (with matrix coloring) time: $(t₂)s"
             end
         end
@@ -92,15 +92,15 @@ SPARSITY_DETECTION_ALGS = [JacPrototypeSparsityDetection(jac_prototype = J_spars
                 @test J ≈ J_true
                 @inferred sparse_jacobian!(J, difftype, cache, fdiff, y, x)
 
-                t₁ = @belapsed sparse_jacobian!($J, $difftype, $cache, $fdiff, $y, $x)
+                t₁ = @elapsed sparse_jacobian!(J, difftype, cache, fdiff, y, x)
                 @info "$(nameof(typeof(difftype)))() `sparse_jacobian!` (only differentiation) time: $(t₁)s"
 
                 J = sparse_jacobian(difftype, cache, fdiff, y, x)
 
                 @test J ≈ J_true
                 # @inferred sparse_jacobian(difftype, cache, fdiff, y, x)
 
-                t₂ = @belapsed sparse_jacobian($difftype, $cache, $fdiff, $y, $x)
+                t₂ = @elapsed sparse_jacobian(difftype, cache, fdiff, y, x)
                 @info "$(nameof(typeof(difftype)))() `sparse_jacobian` (with jacobian allocation) time: $(t₂)s"
             end
 
@@ -110,7 +110,7 @@ SPARSITY_DETECTION_ALGS = [JacPrototypeSparsityDetection(jac_prototype = J_spars
                 @test J ≈ J_true
                 # @inferred sparse_jacobian(difftype, sd, fdiff, y, x)
 
-                t₁ = @belapsed sparse_jacobian($difftype, $sd, $fdiff, $y, $x)
+                t₁ = @elapsed sparse_jacobian(difftype, sd, fdiff, y, x)
                 @info "$(nameof(typeof(difftype)))() `sparse_jacobian` (complete) time: $(t₁)s"
 
                 J = SparseDiffTools.__init_𝒥(cache)
@@ -120,7 +120,7 @@ SPARSITY_DETECTION_ALGS = [JacPrototypeSparsityDetection(jac_prototype = J_spars
                 @test J ≈ J_true
                 @inferred sparse_jacobian!(J, difftype, sd, fdiff, y, x)
 
-                t₂ = @belapsed sparse_jacobian!($J, $difftype, $sd, $fdiff, $y, $x)
+                t₂ = @elapsed sparse_jacobian!(J, difftype, sd, fdiff, y, x)
                 @info "$(nameof(typeof(difftype)))() `sparse_jacobian!` (with matrix coloring) time: $(t₂)s"
             end
         end