[documentation] Explain how to change detector and coloring_algorithm in sparse backends

Author: amontoison

.github/workflows/CI.yml

@@ -28,7 +28,7 @@ jobs:
         with:
           version: ${{ matrix.version }}
           arch: ${{ matrix.arch }}
-      - uses: actions/cache@v1
+      - uses: actions/cache@v4
         env:
           cache-name: cache-artifacts
         with:

docs/Project.toml

@@ -10,6 +10,8 @@ OptimizationProblems = "5049e819-d29b-5fba-b941-0eee7e64c1c6"
 Percival = "01435c0c-c90d-11e9-3788-63660f8fbccc"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 SolverBenchmark = "581a75fa-a23a-52d0-a590-d6201de2218a"
+SparseConnectivityTracer = "9f842d2f-2579-4b1d-911e-f412cf18a3f5"
+SparseMatrixColorings = "0a514795-09f3-496d-8182-132a7b665d35"
 Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
 
 [compat]
@@ -22,4 +24,6 @@ OptimizationProblems = "0.8"
 Percival = "0.7"
 Plots = "1"
 SolverBenchmark = "0.6"
+SparseConnectivityTracer = "0.6.14"
+SparseMatrixColorings = "0.4.14"
 Zygote = "0.6.62"

docs/src/sparse.md

@@ -8,7 +8,8 @@ using ADNLPModels, NLPModels
 f(x) = (x[1] - 1)^2
 T = Float64
 x0 = T[-1.2; 1.0]
-lvar, uvar = zeros(T, 2), ones(T, 2)
+nvar, ncon = 2, 1
+lvar, uvar = zeros(T, nvar), ones(T, nvar)
 lcon, ucon = -T[0.5], T[0.5]
 c!(cx, x) = begin
   cx[1] = x[2]
@@ -22,26 +23,48 @@ nlp = ADNLPModel!(f, x0, lvar, uvar, c!, lcon, ucon, backend = :optimized)
 ```
 
 ```@example ex1
-x = rand(T, 2)
+x = rand(T, nvar)
 J = jac(nlp, x)
 ```
 
 ```@example ex1
-x = rand(T, 2)
+x = rand(T, nvar)
 H = hess(nlp, x)
 ```
 
+## Options for sparsity pattern detection and coloring
+
 The backends available for sparse derivatives (`SparseADJacobian`, `SparseEnzymeADJacobian`, `SparseADHessian`, `SparseReverseADHessian`, and `SparseEnzymeADHessian`) allow for customization through keyword arguments such as `detector` and `coloring_algorithm`.
 These arguments specify the sparsity pattern detector and the coloring algorithm, respectively.
 
 - A **`detector`** must be of type `ADTypes.AbstractSparsityDetector`.
   The default detector is `TracerSparsityDetector()` from the package `SparseConnectivityTracer.jl`.
   Prior to version 0.8.0, the default was `SymbolicSparsityDetector()` from `Symbolics.jl`.
+  A `TracerLocalSparsityDetector()` is also available and can be used if the sparsity pattern of Jacobians and Hessians depends on `x`.
+
+```@example ex1
+import SparseConnectivityTracer.TracerLocalSparsityDetector
+
+set_adbackend!(
+  nlp,
+  jacobian_backend = ADNLPModels.SparseADJacobian(nvar, f, ncon, c!, detector=TracerLocalSparsityDetector()),
+  hessian_backend = ADNLPModels.SparseADHessian(nvar, f, ncon, c!, detector=TracerLocalSparsityDetector()),
+)
+```
 
 - A **`coloring_algorithm`** must be of type `SparseMatrixColorings.GreedyColoringAlgorithm`.
   The default algorithm is `GreedyColoringAlgorithm{:direct}()` for `SparseADJacobian`, `SparseEnzymeADJacobian` and `SparseADHessian`, while it is `GreedyColoringAlgorithm{:substitution}()` for `SparseReverseADHessian` and `SparseEnzymeADHessian`.
   These algorithms are provided by the package `SparseMatrixColorings.jl`.
 
+```@example ex1
+using SparseMatrixColorings
+
+set_adbackend!(
+  nlp,
+  hessian_backend = ADNLPModels.SparseADHessian(nvar, f, ncon, c!, coloring_algorithm=GreedyColoringAlgorithm{:substitution}()),
+)
+```
+
 The `GreedyColoringAlgorithm{:direct}()` performs column coloring for Jacobians and star coloring for Hessians.
 In contrast, `GreedyColoringAlgorithm{:substitution}()` applies acyclic coloring for Hessians. The `:substitution` mode generally requires fewer colors than `:direct`, thus fewer directional derivatives are needed to reconstruct the sparse Hessian.
 However, it necessitates storing the compressed sparse Hessian, while `:direct` coloring only requires storage for one column of the compressed Hessian.