diff --git a/docs/make.jl b/docs/make.jl index e1e0778b..69ea203a 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,4 +1,5 @@ using SparseConnectivityTracer +using ADTypes using Documenter using DocumenterMermaid @@ -13,7 +14,7 @@ DocMeta.setdocmeta!( ) makedocs(; - modules=[SparseConnectivityTracer], + modules=[SparseConnectivityTracer, ADTypes], authors="Adrian Hill ", sitename="SparseConnectivityTracer.jl", format=Documenter.HTML(; diff --git a/docs/src/dev/adding_overloads.md b/docs/src/dev/adding_overloads.md index 888aa146..7cd82b85 100644 --- a/docs/src/dev/adding_overloads.md +++ b/docs/src/dev/adding_overloads.md @@ -44,15 +44,15 @@ Depending on the type of function you're dealing with, you will have to specify | Function | Meaning | |:-------------------------------------------|:--------------------------------------------------------| - | `is_der1_zero_global(::typeof{f}) = false` | $\frac{\partial f}{\partial x} \neq 0$ for some $x$ | - | `is_der2_zero_global(::typeof{f}) = false` | $\frac{\partial^2 f}{\partial x^2} \neq 0$ for some $x$ | + | `is_der1_zero_global(::typeof(f)) = false` | $\frac{\partial f}{\partial x} \neq 0$ for some $x$ | + | `is_der2_zero_global(::typeof(f)) = false` | $\frac{\partial^2 f}{\partial x^2} \neq 0$ for some $x$ | Optionally, to increase the sparsity of [`TracerLocalSparsityDetector`](@ref), you can additionally implement | Function | Meaning | |:---------------------------------------------|:---------------------------------------------------------| - | `is_der1_zero_local(::typeof{f}, x) = false` | $\frac{\partial f}{\partial x} \neq 0$ for given $x$ | - | `is_der2_zero_local(::typeof{f}, x) = false` | $\frac{\partial^2 f}{\partial x^2} \neq 0$ for given $x$ | + | `is_der1_zero_local(::typeof(f), x) = false` | $\frac{\partial f}{\partial x} \neq 0$ for given $x$ | + | `is_der2_zero_local(::typeof(f), x) = false` | $\frac{\partial^2 f}{\partial x^2} \neq 0$ for given $x$ | These fall back to @@ -66,21 +66,21 @@ Depending on the type of function you're dealing with, you will have to specify | Function | Meaning | |:------------------------------------------------|:-------------------------------------------------------------------| - | `is_der1_arg1_zero_global(::typeof{f}) = false` | $\frac{\partial f}{\partial x} \neq 0$ for some $x,y$ | - | `is_der2_arg1_zero_global(::typeof{f}) = false` | $\frac{\partial^2 f}{\partial x^2} \neq 0$ for some $x,y$ | - | `is_der1_arg2_zero_global(::typeof{f}) = false` | $\frac{\partial f}{\partial y} \neq 0$ for some $x,y$ | - | `is_der2_arg2_zero_global(::typeof{f}) = false` | $\frac{\partial^2 f}{\partial y^2} \neq 0$ for some $x,y$ | - | `is_der_cross_zero_global(::typeof{f}) = false` | $\frac{\partial^2 f}{\partial x \partial y} \neq 0$ for some $x,y$ | + | `is_der1_arg1_zero_global(::typeof(f)) = false` | $\frac{\partial f}{\partial x} \neq 0$ for some $x,y$ | + | `is_der2_arg1_zero_global(::typeof(f)) = false` | $\frac{\partial^2 f}{\partial x^2} \neq 0$ for some $x,y$ | + | `is_der1_arg2_zero_global(::typeof(f)) = false` | $\frac{\partial f}{\partial y} \neq 0$ for some $x,y$ | + | `is_der2_arg2_zero_global(::typeof(f)) = false` | $\frac{\partial^2 f}{\partial y^2} \neq 0$ for some $x,y$ | + | `is_der_cross_zero_global(::typeof(f)) = false` | $\frac{\partial^2 f}{\partial x \partial y} \neq 0$ for some $x,y$ | Optionally, to increase the sparsity of [`TracerLocalSparsityDetector`](@ref), you can additionally implement | Function | Meaning | |:-----------------------------------------------------|:--------------------------------------------------------------------| - | `is_der1_arg1_zero_local(::typeof{f}, x, y) = false` | $\frac{\partial f}{\partial x} \neq 0$ for given $x,y$ | - | `is_der2_arg1_zero_local(::typeof{f}, x, y) = false` | $\frac{\partial^2 f}{\partial x^2} \neq 0$ for given $x,y$ | - | `is_der1_arg2_zero_local(::typeof{f}, x, y) = false` | $\frac{\partial f}{\partial x} \neq 0$ for given $x,y$ | - | `is_der2_arg2_zero_local(::typeof{f}, x, y) = false` | $\frac{\partial^2 f}{\partial x^2} \neq 0$ for given $x,y$ | - | `is_der_cross_zero_local(::typeof{f}, x, y) = false` | $\frac{\partial^2 f}{\partial x \partial y} \neq 0$ for given $x,y$ | + | `is_der1_arg1_zero_local(::typeof(f), x, y) = false` | $\frac{\partial f}{\partial x} \neq 0$ for given $x,y$ | + | `is_der2_arg1_zero_local(::typeof(f), x, y) = false` | $\frac{\partial^2 f}{\partial x^2} \neq 0$ for given $x,y$ | + | `is_der1_arg2_zero_local(::typeof(f), x, y) = false` | $\frac{\partial f}{\partial x} \neq 0$ for given $x,y$ | + | `is_der2_arg2_zero_local(::typeof(f), x, y) = false` | $\frac{\partial^2 f}{\partial x^2} \neq 0$ for given $x,y$ | + | `is_der_cross_zero_local(::typeof(f), x, y) = false` | $\frac{\partial^2 f}{\partial x \partial y} \neq 0$ for given $x,y$ | These fall back to @@ -97,19 +97,19 @@ Depending on the type of function you're dealing with, you will have to specify | Function | Meaning | |:-----------------------------------------------|:----------------------------------------------------------| - | `is_der1_out1_zero_local(::typeof{f}) = false` | $\frac{\partial f_1}{\partial x} \neq 0$ for some $x$ | - | `is_der2_out1_zero_local(::typeof{f}) = false` | $\frac{\partial^2 f_1}{\partial x^2} \neq 0$ for some $x$ | - | `is_der1_out2_zero_local(::typeof{f}) = false` | $\frac{\partial f_2}{\partial x} \neq 0$ for some $x$ | - | `is_der2_out2_zero_local(::typeof{f}) = false` | $\frac{\partial^2 f_2}{\partial x^2} \neq 0$ for some $x$ | + | `is_der1_out1_zero_local(::typeof(f)) = false` | $\frac{\partial f_1}{\partial x} \neq 0$ for some $x$ | + | `is_der2_out1_zero_local(::typeof(f)) = false` | $\frac{\partial^2 f_1}{\partial x^2} \neq 0$ for some $x$ | + | `is_der1_out2_zero_local(::typeof(f)) = false` | $\frac{\partial f_2}{\partial x} \neq 0$ for some $x$ | + | `is_der2_out2_zero_local(::typeof(f)) = false` | $\frac{\partial^2 f_2}{\partial x^2} \neq 0$ for some $x$ | Optionally, to increase the sparsity of [`TracerLocalSparsityDetector`](@ref), you can additionally implement | Function | Meaning | |:--------------------------------------------------|:-----------------------------------------------------------| - | `is_der1_out1_zero_local(::typeof{f}, x) = false` | $\frac{\partial f_1}{\partial x} \neq 0$ for given $x$ | - | `is_der2_out1_zero_local(::typeof{f}, x) = false` | $\frac{\partial^2 f_1}{\partial x^2} \neq 0$ for given $x$ | - | `is_der1_out2_zero_local(::typeof{f}, x) = false` | $\frac{\partial f_2}{\partial x} \neq 0$ for given $x$ | - | `is_der2_out2_zero_local(::typeof{f}, x) = false` | $\frac{\partial^2 f_2}{\partial x^2} \neq 0$ for given $x$ | + | `is_der1_out1_zero_local(::typeof(f), x) = false` | $\frac{\partial f_1}{\partial x} \neq 0$ for given $x$ | + | `is_der2_out1_zero_local(::typeof(f), x) = false` | $\frac{\partial^2 f_1}{\partial x^2} \neq 0$ for given $x$ | + | `is_der1_out2_zero_local(::typeof(f), x) = false` | $\frac{\partial f_2}{\partial x} \neq 0$ for given $x$ | + | `is_der2_out2_zero_local(::typeof(f), x) = false` | $\frac{\partial^2 f_2}{\partial x^2} \neq 0$ for given $x$ | These fall back to diff --git a/docs/src/user/api.md b/docs/src/user/api.md index a9d84470..ac8e5d56 100644 --- a/docs/src/user/api.md +++ b/docs/src/user/api.md @@ -9,6 +9,11 @@ CollapsedDocStrings = true SparseConnectivityTracer uses [ADTypes.jl](https://github.com/SciML/ADTypes.jl)'s [interface for sparsity detection](https://sciml.github.io/ADTypes.jl/stable/#Sparsity-detector). In fact, the functions `jacobian_sparsity` and `hessian_sparsity` are re-exported from ADTypes. +```@docs +ADTypes.jacobian_sparsity +ADTypes.hessian_sparsity +``` + To compute **global** sparsity patterns of `f(x)` over the entire input domain `x`, use ```@docs TracerSparsityDetector @@ -18,3 +23,4 @@ To compute **local** sparsity patterns of `f(x)` at a specific input `x`, use ```@docs TracerLocalSparsityDetector ``` + diff --git a/docs/src/user/limitations.md b/docs/src/user/limitations.md index 0ce3662f..01b34177 100644 --- a/docs/src/user/limitations.md +++ b/docs/src/user/limitations.md @@ -58,7 +58,7 @@ it must be written generically enough to accept numbers of type `T<:Real` as (or Only [`TracerLocalSparsityDetector`](@ref) supports comparison operators (`<`, `==`, ...), indicator functions (`iszero`, `iseven`, ...) and control flow. -[`TracerSparsityDetector`](@ref) does not support any boolean functions and control flow (with the exception of `iselse`). +[`TracerSparsityDetector`](@ref) does not support any boolean functions and control flow (with the exception of `ifelse`). This might seem unintuitive but follows from our policy stated above: SCT guarantees conservative sparsity patterns. Using an approach based on operator-overloading, this means that global sparsity detection isn't allowed to hit any branching code. `ifelse` is the only exception, since it allows us to evaluate both branches.