docs: add a table to guarantee selections

Author: avik-pal

docs/src/basics/sparsity_detection.md

@@ -6,6 +6,34 @@ to use this in an actual problem, see
 
 Notation wise we are trying to solve for `x` such that `nlfunc(x) = 0`.
 
+## Big Table for Determining Sparsity Detection and Coloring Algorithms
+
+| `f.sparsity`               | `f.jac_prototype` | `f.colorvec` | Sparsity Detection                               | Coloring Algorithm                        |
+| :------------------------- | :---------------- | :----------- | :----------------------------------------------- | :---------------------------------------- |
+| ❌                         | ❌                | `Any`        | `NoSparsityDetector()`                           | `NoColoringAlgorithm()`                   |
+| ❌                         | Not Structured    | `Any`        | `NoSparsityDetector()`                           | `NoColoringAlgorithm()`                   |
+| ❌                         | Structured        | ✅           | `KnownJacobianSparsityDetector(f.jac_prototype)` | `GreedyColoringAlgorithm(LargestFirst())` |
+| ❌                         | Structured        | ❌           | `KnownJacobianSparsityDetector(f.jac_prototype)` | `GreedyColoringAlgorithm(LargestFirst())` |
+| -                          | -                 | -            | -                                                | -                                         |
+| `AbstractMatrix`           | ❌                | ✅           | `KnownJacobianSparsityDetector(f.sparsity)`      | `ConstantColoringAlgorithm(f.colorvec)`   |
+| `AbstractMatrix`           | ❌                | ❌           | `KnownJacobianSparsityDetector(f.sparsity)`      | `GreedyColoringAlgorithm(LargestFirst())` |
+| `AbstractMatrix`           | Not Structured    | ✅           | `KnownJacobianSparsityDetector(f.sparsity)`      | `ConstantColoringAlgorithm(f.colorvec)`   |
+| `AbstractMatrix`           | Not Structured    | ❌           | `KnownJacobianSparsityDetector(f.sparsity)`      | `GreedyColoringAlgorithm(LargestFirst())` |
+| `AbstractMatrix`           | Structured        | `Any`        | 🔴                                               | 🔴                                        |
+| -                          | -                 | -            | -                                                | -                                         |
+| `AbstractSparsityDetector` | ❌                | `Any`        | `f.sparsity`                                     | `GreedyColoringAlgorithm(LargestFirst())` |
+| `AbstractSparsityDetector` | Not Structured    | ✅           | `f.sparsity`                                     | `ConstantColoringAlgorithm(f.colorvec)`   |
+| `AbstractSparsityDetector` | Not Structured    | ❌           | `f.sparsity`                                     | `GreedyColoringAlgorithm(LargestFirst())` |
+| `AbstractSparsityDetector` | Structured        | ✅           | `KnownJacobianSparsityDetector(f.jac_prototype)` | `ConstantColoringAlgorithm(f.colorvec)`   |
+| `AbstractSparsityDetector` | Structured        | ❌           | `KnownJacobianSparsityDetector(f.jac_prototype)` | `GreedyColoringAlgorithm(LargestFirst())` |
+
+1. `Structured` means either a `AbstractSparseMatrix` or `ArrayInterface.isstructured(x)` is true.
+2. ❌ means not provided (default)
+3. ✅ means provided
+4. 🔴 means an error will be thrown
+5. Providing a colorvec without specifying either sparsity or jac_prototype with a sparse or structured matrix will cause us to ignore the colorvec.
+6. The function calls demonstrated above are simply pseudo-code to show the general idea.
+
 ## Case I: Sparse Jacobian Prototype is Provided
 
 Let's say you have a Sparse Jacobian Prototype `jac_prototype`, in this case you can
@@ -27,19 +55,12 @@ prob = NonlinearProblem(
 If the `colorvec` is not provided, then it is computed on demand.
 
 !!! note
-    
+
     One thing to be careful about in this case is that `colorvec` is dependent on the
     autodiff backend used. `ADTypes.mode(ad) isa ADTypes.ForwardMode` will assume that the
     colorvec is the column colorvec, otherwise we will assume that the colorvec is the
     row colorvec.
 
-!!! warning
-    
-    Previously you could provide a `sparsity` argument to `NonlinearFunction` to specify
-    the jacobian prototype. However, to avoid confusion, this is now deprecated. Instead,
-    use the `jac_prototype` argument. `sparsity` must be used to exclusively specify the
-    sparsity detection algorithm.
-
 ## Case II: Sparsity Detection algorithm is provided
 
 If you don't have a Sparse Jacobian Prototype, but you know the which sparsity detection
@@ -59,7 +80,7 @@ for more information on sparsity detection algorithms.
 ## Case III: Sparse AD Type is being Used
 
 !!! warning
-    
+
     This is now deprecated. Please use the previous two cases instead.
 
 If you constructed a Nonlinear Solver with a sparse AD type, for example

src/internal/jacobian.jl

@@ -172,6 +172,13 @@ function construct_concrete_adtype(f::NonlinearFunction, ad::AbstractADType)
             end
             return ad # No sparse AD
         else
+            if !sparse_or_structured_prototype(f.jac_prototype)
+                if SciMLBase.has_colorvec(f)
+                    @warn "`colorvec` is provided but `jac_prototype` is not a sparse \
+                           or structured matrix. `colorvec` will be ignored."
+                end
+                return ad
+            end
             return AutoSparse(
                 ad;
                 sparsity_detector = KnownJacobianSparsityDetector(f.jac_prototype),
@@ -181,13 +188,14 @@ function construct_concrete_adtype(f::NonlinearFunction, ad::AbstractADType)
         end
     else
         if f.sparsity isa AbstractMatrix
-            if f.jac_prototype !== nothing && f.jac_prototype !== f.sparsity
-                throw(ArgumentError("`sparsity::AbstractMatrix` and `jac_prototype` cannot \
-                                     be both provided. Pass only `jac_prototype`."))
+            if f.jac_prototype !== f.sparsity
+                if f.jac_prototype !== nothing &&
+                   sparse_or_structured_prototype(f.jac_prototype)
+                    throw(ArgumentError("`sparsity::AbstractMatrix` and a sparse or \
+                                         structured `jac_prototype` cannot be both \
+                                         provided. Pass only `jac_prototype`."))
+                end
             end
-            Base.depwarn("`sparsity::typeof($(typeof(f.sparsity)))` is deprecated. \
-                          Pass it as `jac_prototype` instead.",
-                :NonlinearSolve)
             return AutoSparse(
                 ad;
                 sparsity_detector = KnownJacobianSparsityDetector(f.sparsity),
@@ -209,8 +217,7 @@ function construct_concrete_adtype(f::NonlinearFunction, ad::AbstractADType)
                 coloring_algorithm = GreedyColoringAlgorithm(LargestFirst())
             )
         else
-            if f.jac_prototype isa AbstractSparseMatrix ||
-               ArrayInterface.isstructured(f.jac_prototype)
+            if sparse_or_structured_prototype(f.jac_prototype)
                 if !(sparsity_detector isa NoSparsityDetector)
                     @warn "`jac_prototype` is a sparse matrix but sparsity = $(f.sparsity) \
                            has also been specified. Ignoring sparsity field and using \
@@ -254,3 +261,8 @@ end
 
 get_dense_ad(ad) = ad
 get_dense_ad(ad::AutoSparse) = ADTypes.dense_ad(ad)
+
+sparse_or_structured_prototype(::AbstractSparseMatrix) = true
+function sparse_or_structured_prototype(prototype::AbstractMatrix)
+    return ArrayInterface.isstructured(prototype)
+end