Include sparsity detection in the README

Author: ChrisRackauckas

README.md

@@ -29,30 +29,35 @@ end
 ```
 
 For this function, we know that the sparsity pattern of the Jacobian is a
-`Tridiagonal` matrix. We represent our sparsity by that matrix:
+`Tridiagonal` matrix. However, if we didn't know the sparsity pattern for
+the Jacobian, we could use the `sparsity!` function to automatically
+detect the sparsity pattern. We declare that it outputs a length 30 vector
+and takes in a length 30 vector, and it spits out a `Sparsity` object
+which we can turn into a `SparseMatrixCSC`:
 
 ```julia
-sparsity_pattern = Tridiagonal(ones(29),ones(30),ones(29))
+sparsity_pattern = sparsity!(f,output,input)
+jac = Float64.(sparse(sparsity_pattern))
 ```
 
 Now we call `matrix_colors` to get the color vector for that matrix:
 
 ```julia
-colors = matrix_colors(sparsity_pattern)
+colors = matrix_colors(jac)
 ```
 
 Since `maximum(colors)` is 3, this means that finite differencing can now
 compute the Jacobian in just 4 `f`-evaluations:
 
 ```julia
-J = DiffEqDiffTools.finite_difference_jacobian(f, rand(30), color=colors)
+DiffEqDiffTools.finite_difference_jacobian!(jac, f, rand(30), color=colors)
 @show fcalls # 4
 ```
 
 In addition, a faster forward-mode autodiff call can be utilized as well:
 
 ```julia
-forwarddiff_color_jacobian!(sparsity_pattern, f, x, color = colors)
+forwarddiff_color_jacobian!(jac, f, x, color = colors)
 ```
 
 If one only need to compute products, one can use the operators. For example,
@@ -83,6 +88,36 @@ gmres!(res,J,v)
 
 ## Documentation
 
+### Automated Sparsity Detection
+
+Automated sparsity detection is provided by the `sparsity!` function whose
+syntax is:
+
+```julia
+`sparsity!(f, Y, X, args...; sparsity=Sparsity(length(X), length(Y)), verbose=true)`
+```
+
+The arguments are:
+
+- `f`: the function
+- `Y`: the output array
+- `X`: the input array
+- `args`: trailing arguments to `f`. They are considered subject to change, unless wrapped as `Fixed(arg)`
+- `S`: (optional) the sparsity pattern
+- `verbose`: (optional) whether to describe the paths taken by the sparsity detection.
+
+The function `f` is assumed to take arguments of the form `f(dx,x,args...)`.
+`sparsity!` returns a `Sparsity` object which describes where the non-zeros
+of the Jacobian occur. `sparse(::Sparsity)` transforms the pattern into
+a sparse matrix.
+
+This function utilizes non-standard interpretation, which we denote
+combinatoric concolic analysis, to directly realize the sparsity pattern from the program's AST. It requires that the function `f` is a Julia function. It does not
+work numerically, meaning that it is not prone to floating point error or
+cancelation. It allows for branching and will automatically check all of the
+branches. However, a while loop of indeterminate length which is dependent
+on the input argument is not allowed.
+
 ### Matrix Coloring
 
 Matrix coloring allows you to reduce the number of times finite differencing

src/program_sparsity/program_sparsity.jl

@@ -3,7 +3,7 @@ struct Fixed
 end
 
 """
-`sparsity!(f, Y, X, args...; sparsity=Sparsity(length(X), length(Y)), verboase=true)`
+`sparsity!(f, Y, X, args...; sparsity=Sparsity(length(X), length(Y)), verbose=true)`
 
 Execute the program that figures out the sparsity pattern of
 the jacobian of the function `f`.

test/test_integration.jl

@@ -23,7 +23,8 @@ function second_derivative_stencil(N)
   A
 end
 
-sparsity_pattern = sparsity!(f,ones(30),ones(30))
+output = ones(30); input = ones(30)
+sparsity_pattern = sparsity!(f,output,input)
 true_jac = Float64.(sparse(sparsity_pattern))
 colors = matrix_colors(true_jac)
 @test colors == repeat(1:3,10)