Switch to SCT in the tutorial, make coloring part of API (#258)

Author: gdalle

DifferentiationInterface/docs/Project.toml

@@ -16,6 +16,7 @@ Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 PolyesterForwardDiff = "98d1487c-24ca-40b6-b7ab-df2af84e126b"
 PrettyTables = "08abe8d2-0d0c-5749-adfa-8a2ac140af0d"
 ReverseDiff = "37e2e3b7-166d-5795-8a7a-e32c996b4267"
+SparseConnectivityTracer = "9f842d2f-2579-4b1d-911e-f412cf18a3f5"
 Symbolics = "0c5d862f-8b57-4792-8d23-62f2024744c7"
 Tapir = "07d77754-e150-4737-8c94-cd238a1fb45b"
 Tracker = "9f7883ad-71c0-57eb-9f7f-b5c9e6d3789c"

DifferentiationInterface/docs/src/api.md

@@ -92,10 +92,11 @@ check_twoarg
 check_hessian
 ```
 
-## Translation
+## Miscellaneous
 
 ```@docs
 DifferentiateWith
+GreedyColoringAlgorithm
 ```
 
 ## Internals

DifferentiationInterface/docs/src/tutorial.md

@@ -143,32 +143,26 @@ It provides benchmarking utilities to compare backends and help you select the o
 
 To compute sparse Jacobians or Hessians, you need three ingredients (read [this survey](https://epubs.siam.org/doi/10.1137/S0036144504444711) to understand why):
 
-1. A sparsity pattern detector
-2. A coloring algorithm
-3. An underlying AD backend
-
-ADTypes.jl v1.0 defines the [`AutoSparse`](@ref) wrapper, which brings together these three ingredients.
-At the moment, this new wrapper is not well-supported in the ecosystem, which is why DifferentiationInterface.jl provides the necessary objects to get you started:
-
-1. [`DifferentiationInterface.SymbolicsSparsityDetector`](@ref) (requires [Symbolics.jl](https://github.com/JuliaSymbolics/Symbolics.jl) to be loaded)
-2. [`DifferentiationInterface.GreedyColoringAlgorithm`](@ref)
-
-!!! warning
-    These objects are not part of the public API, so they can change unexpectedly between versions.
-
-!!! info
-    The symbolic backends have built-in sparsity handling, so `AutoSparse(AutoSymbolics())` and `AutoSparse(AutoFastDifferentiation())` do not need additional configuration.
-
+1. An underlying (dense) AD backend
+2. A sparsity pattern detector like:
+    - `TracerSparsityDetector`, implemented by [SparseConnectivityTracer.jl](https://github.com/adrhill/SparseConnectivityTracer.jl) (our default recommendation)
+    - [`DifferentiationInterface.SymbolicsSparsityDetector`](@ref), implemented by DifferentiationInterface.jl with [Symbolics.jl](https://github.com/JuliaSymbolics/Symbolics.jl) but not part of the public API (it will soon be [transferred](https://github.com/JuliaSymbolics/Symbolics.jl/pull/1134))
+3. A coloring algorithm like:
+    - [`GreedyColoringAlgorithm`](@ref), implemented by DifferentiationInterface.jl
+
+ADTypes.jl v1.0 provides the [`AutoSparse`](@ref) wrapper to combine these three ingredients, and DifferentiationInterface.jl re-exports it.
 Here's an example:
 
 ```@example tuto
-import Symbolics
+using SparseConnectivityTracer
 
-sparsity_detector = DifferentiationInterface.SymbolicsSparsityDetector()
-coloring_algorithm = DifferentiationInterface.GreedyColoringAlgorithm()
 dense_backend = AutoForwardDiff()
 
-sparse_backend = AutoSparse(dense_backend; sparsity_detector, coloring_algorithm)
+sparse_backend = AutoSparse(
+    dense_backend;
+    sparsity_detector=TracerSparsityDetector(),
+    coloring_algorithm=GreedyColoringAlgorithm(),
+)
 ```
 
 See how the computed Hessian is sparse, whereas the underlying backend alone would give us a dense matrix:
@@ -183,4 +177,8 @@ hessian(f, dense_backend, x)
 
 The sparsity detector and coloring algorithm are called during the preparation step, which can be fairly expensive.
 If you plan to compute several Jacobians or Hessians with the same pattern but different input vectors, you should reuse the `extras` object created by `prepare_jacobian` or `prepare_hessian`.
-After preparation, the sparse computation itself will be much faster than the dense one, and require fewer calls to the function. 
+After preparation, the sparse computation itself will be much faster than the dense one, and require fewer calls to the function.
+
+!!! info
+    The symbolic backends have built-in sparsity handling, so `AutoSparse(AutoSymbolics())` and `AutoSparse(AutoFastDifferentiation())` do not need additional configuration for detection or coloring.
+    However they still benefit from preparation.

DifferentiationInterface/src/DifferentiationInterface.jl

@@ -100,6 +100,8 @@ export check_available, check_twoarg, check_hessian
 
 export DifferentiateWith
 
+export GreedyColoringAlgorithm
+
 # Re-export backends from ADTypes
 export AutoChainRules
 export AutoDiffractor

DifferentiationInterface/src/sparse/detector.jl

@@ -6,7 +6,7 @@ Sparsity detection algorithm based on the [Symbolics.jl tracing system](https://
 Compatible with the [ADTypes.jl sparsity detection framework](https://sciml.github.io/ADTypes.jl/stable/#Sparsity-detector).
 
 !!! danger
-    This functionality is implemented in an extension, and requires Symbolics.jl to be loaded.
+    This functionality is implemented in an extension, and requires [Symbolics.jl](https://github.com/JuliaSymbolics/Symbolics.jl) to be loaded.
 
 # See also
 

DifferentiationInterface/test/runtests.jl

@@ -1,7 +1,7 @@
 using ADTypes
 using DifferentiationInterface
 using Pkg
-using SparseConnectivityTracer: SparseConnectivityTracer
+using SparseConnectivityTracer
 using Test
 
 push!(Base.LOAD_PATH, Base.active_project())
@@ -41,8 +41,8 @@ else
 end
 
 function MyAutoSparse(backend::AbstractADType)
-    coloring_algorithm = DifferentiationInterface.GreedyColoringAlgorithm()
-    sparsity_detector = SparseConnectivityTracer.TracerSparsityDetector()
+    coloring_algorithm = GreedyColoringAlgorithm()
+    sparsity_detector = TracerSparsityDetector()
     return AutoSparse(backend; sparsity_detector, coloring_algorithm)
 end
 

DifferentiationInterfaceTest/test/runtests.jl

@@ -2,7 +2,7 @@ using ADTypes
 using DifferentiationInterface
 using DifferentiationInterfaceTest
 using Pkg
-using SparseConnectivityTracer: SparseConnectivityTracer
+using SparseConnectivityTracer
 using Test
 
 DI_PATH = joinpath(@__DIR__, "..", "..", "DifferentiationInterface")
@@ -11,8 +11,8 @@ if isdir(DI_PATH)
 end
 
 function MyAutoSparse(backend::AbstractADType)
-    coloring_algorithm = DifferentiationInterface.GreedyColoringAlgorithm()
-    sparsity_detector = SparseConnectivityTracer.TracerSparsityDetector()
+    coloring_algorithm = GreedyColoringAlgorithm()
+    sparsity_detector = TracerSparsityDetector()
     return AutoSparse(backend; sparsity_detector, coloring_algorithm)
 end