Update docs for Tapir (#125)

Author: gdalle

Project.toml

@@ -84,9 +84,10 @@ ReverseDiff = "37e2e3b7-166d-5795-8a7a-e32c996b4267"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 SparseDiffTools = "47a9eef4-7e08-11e9-0b38-333d64bd3804"
 Symbolics = "0c5d862f-8b57-4792-8d23-62f2024744c7"
+Tapir = "07d77754-e150-4737-8c94-cd238a1fb45b"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 Tracker = "9f7883ad-71c0-57eb-9f7f-b5c9e6d3789c"
 Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
 
 [targets]
-test = ["ADTypes", "Aqua", "Chairmarks", "DataFrames", "Diffractor", "Documenter", "Enzyme", "FastDifferentiation", "FiniteDiff", "FiniteDifferences", "ForwardDiff", "JET", "JuliaFormatter", "Pkg", "PolyesterForwardDiff", "ReverseDiff", "SparseArrays", "SparseDiffTools", "Symbolics", "Test", "Tracker", "Zygote"]
+test = ["ADTypes", "Aqua", "Chairmarks", "DataFrames", "Diffractor", "Documenter", "Enzyme", "FastDifferentiation", "FiniteDiff", "FiniteDifferences", "ForwardDiff", "JET", "JuliaFormatter", "Pkg", "PolyesterForwardDiff", "ReverseDiff", "SparseArrays", "SparseDiffTools", "Symbolics", "Tapir", "Test", "Tracker", "Zygote"]

README.md

@@ -5,7 +5,7 @@
 [![Coverage](https://codecov.io/gh/gdalle/DifferentiationInterface.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/gdalle/DifferentiationInterface.jl)
 [![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle)
 
-An interface to various automatic differentiation backends in Julia.
+An interface to various automatic differentiation (AD) backends in Julia.
 
 ## Goal
 
@@ -39,20 +39,21 @@ We support most of the backends defined by [ADTypes.jl](https://github.com/SciML
 | [Tracker.jl](https://github.com/FluxML/Tracker.jl)                              | `AutoTracker()`                                              |
 | [Zygote.jl](https://github.com/FluxML/Zygote.jl)                                | `AutoZygote()`                                               |
 
-We also provide one additional backend:
+We also support additional (experimental) backends:
 
 | backend                                                                          | object                      |
 | :------------------------------------------------------------------------------- | :-------------------------- |
 | [FastDifferentiation.jl](https://github.com/brianguenter/FastDifferentiation.jl) | `AutoFastDifferentiation()` |
+| [Tapir.jl](https://github.com/withbayes/Tapir.jl)                                | `AutoTapir()`               |
 
 ## Example
 
 ```jldoctest readme
-julia> import ADTypes, ForwardDiff
+julia> import ForwardDiff
 
 julia> using DifferentiationInterface
 
-julia> backend = ADTypes.AutoForwardDiff();
+julia> backend = AutoForwardDiff();
 
 julia> f(x) = sum(abs2, x);
 

docs/Project.toml

@@ -19,6 +19,9 @@ PolyesterForwardDiff = "98d1487c-24ca-40b6-b7ab-df2af84e126b"
 PrettyTables = "08abe8d2-0d0c-5749-adfa-8a2ac140af0d"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 ReverseDiff = "37e2e3b7-166d-5795-8a7a-e32c996b4267"
+SparseDiffTools = "47a9eef4-7e08-11e9-0b38-333d64bd3804"
+Symbolics = "0c5d862f-8b57-4792-8d23-62f2024744c7"
+Tapir = "07d77754-e150-4737-8c94-cd238a1fb45b"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 Tracker = "9f7883ad-71c0-57eb-9f7f-b5c9e6d3789c"
 Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"

docs/make.jl

@@ -18,6 +18,9 @@ using FiniteDifferences: FiniteDifferences
 using ForwardDiff: ForwardDiff
 using PolyesterForwardDiff: PolyesterForwardDiff
 using ReverseDiff: ReverseDiff
+using Symbolics: Symbolics
+using SparseDiffTools: SparseDiffTools
+using Tapir: Tapir
 using Tracker: Tracker
 using Zygote: Zygote
 
@@ -49,6 +52,8 @@ makedocs(;
         get_extension(DI, :DifferentiationInterfaceForwardDiffExt),
         get_extension(DI, :DifferentiationInterfacePolyesterForwardDiffExt),
         get_extension(DI, :DifferentiationInterfaceReverseDiffExt),
+        get_extension(DI, :DifferentiationInterfaceSparseDiffToolsExt),
+        get_extension(DI, :DifferentiationInterfaceTapirExt),
         get_extension(DI, :DifferentiationInterfaceTrackerExt),
         get_extension(DI, :DifferentiationInterfaceZygoteExt),
     ],

docs/src/backends.md

@@ -20,6 +20,7 @@ function all_backends()
         AutoForwardDiff(),
         AutoPolyesterForwardDiff(; chunksize=2),
         AutoReverseDiff(),
+        AutoTapir(),
         AutoTracker(),
         AutoZygote(),
     ]
@@ -36,32 +37,43 @@ end
 
 ## Types
 
-Most backend choices are defined by [ADTypes.jl](https://github.com/SciML/ADTypes.jl).
+We support (and re-export) most backend choices from [ADTypes.jl](https://github.com/SciML/ADTypes.jl), and we provide a few more of our own.
 
 !!! warning
-    Only the backends listed here are supported by DifferentiationInterface.jl, even though ADTypes.jl defines more.
+    Only the backends listed below are supported by DifferentiationInterface.jl, even though ADTypes.jl defines more.
+
+### Dense
 
 ```@docs
 AutoChainRules
 AutoDiffractor
 AutoEnzyme
+AutoFastDifferentiation
 AutoForwardDiff
 AutoForwardDiff()
 AutoFiniteDiff
 AutoFiniteDifferences
 AutoPolyesterForwardDiff
 AutoPolyesterForwardDiff()
 AutoReverseDiff
+AutoTapir
 AutoTracker
 AutoZygote
 ```
 
-We also provide a few of our own:
+### Sparse
+
+!!! danger
+    Sparsity support is still experimental, use at your own risk.
 
 ```@docs
-AutoFastDifferentiation
 AutoSparseFastDifferentiation
-AutoTapir
+AutoSparseFiniteDiff
+AutoSparseForwardDiff
+AutoSparseForwardDiff()
+AutoSparsePolyesterForwardDiff
+AutoSparseReverseDiff
+AutoSparseZygote
 ```
 
 ## Availability
@@ -111,6 +123,8 @@ Modules = [
     Base.get_extension(DifferentiationInterface, :DifferentiationInterfaceForwardDiffExt),
     Base.get_extension(DifferentiationInterface, :DifferentiationInterfacePolyesterForwardDiffExt),
     Base.get_extension(DifferentiationInterface, :DifferentiationInterfaceReverseDiffExt),
+    Base.get_extension(DifferentiationInterface, :DifferentiationInterfaceSparseDiffToolsExt),
+    Base.get_extension(DifferentiationInterface, :DifferentiationInterfaceTapirExt),
     Base.get_extension(DifferentiationInterface, :DifferentiationInterfaceTrackerExt),
     Base.get_extension(DifferentiationInterface, :DifferentiationInterfaceZygoteExt)
 ]

docs/src/developer.md

@@ -22,30 +22,31 @@ For simplicity, we remove `value_` in the operator names below.
 !!! note "Edge labels"
 
     Full edges in the following graphs require a single call to the destination.
-    Dotted edges require multiple calls to the destination, the number is indicated above.
+    Dotted edges require multiple calls to the destination, the number is indicated on the edge.
 
-### Forward mode, allocating functions
+### First order
 
 ```mermaid
 flowchart LR
-    pushforward!! --> pushforward
-    derivative --> pushforward
-    derivative!! --> pushforward!!
-    gradient .-> |n|pushforward
-    gradient!! .-> |n|pushforward!!
-    jacobian .-> |n|pushforward
-    jacobian!! .-> |n|pushforward!!
-```
-
-### Reverse mode, allocating functions
-
-```mermaid
-flowchart LR
-    pullback!! --> pullback
-    derivative .-> |m|pullback
-    derivative!! .-> |m|pullback!!
-    gradient --> pullback
-    gradient!! --> pullback!!
-    jacobian .-> |m|pullback
-    jacobian!! .-> |m|pullback!!
+    direction LR
+    subgraph Out-of-place
+        pushforward
+        pullback
+        derivative --> pushforward
+        gradient --> pullback
+        jacobian .-> |n|pushforward
+        jacobian .-> |m|pullback
+    end
+
+    subgraph In-place
+        pushforward!! --> pushforward
+        pullback!! --> pullback
+        derivative!! --> pushforward!!
+        gradient!! --> pullback!!
+        jacobian!! .-> |n|pushforward!!
+        jacobian!! .-> |m|pullback!!
+    end
+
+    pushforward .-> |m|pullback
+    pullback .-> |n|pushforward
 ```

docs/src/overview.md

@@ -69,11 +69,11 @@ We only define two variants for now:
 | [`hessian`](@ref)           | [`hessian!!`](@ref)           |
 
 !!! danger
-    This is an experimental functionality, use at your own risk.
+    Second-order differentiation is still experimental, use at your own risk.
 
 ## Preparation
 
-In many cases, automatic differentiation can be accelerated if the function has been run at least once (e.g. to record a tape) and if some cache objects are provided.
+In many cases, AD can be accelerated if the function has been run at least once (e.g. to record a tape) and if some cache objects are provided.
 This is a backend-specific procedure, but we expose a common syntax to achieve it.
 
 | operator            | preparation function                |

docs/src/tutorial.md

@@ -7,13 +7,14 @@ CurrentModule = Main
 We present a typical workflow with DifferentiationInterface.jl and showcase its potential performance benefits.
 
 ```@repl tuto
-using ADTypes, BenchmarkTools, DifferentiationInterface
+using DifferentiationInterface
+using BenchmarkTools
 import ForwardDiff, Enzyme, DataFrames
 ```
 
 ## Computing a gradient
 
-A common use case of Automatic Differentiation (AD) is optimizing real-valued functions with first- or second-order methods.
+A common use case of AD is optimizing real-valued functions with first- or second-order methods.
 Let's define a simple objective
 
 ```@repl tuto
@@ -28,7 +29,7 @@ x = [1.0, 2.0, 3.0]
 
 To compute its gradient, we need to choose a "backend", i.e. an AD package that DifferentiationInterface.jl will call under the hood.
 [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl) is very efficient for low-dimensional inputs, so we'll go with that one.
-Backend types are defined and exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl):
+Most backend types are defined by [ADTypes.jl](https://github.com/SciML/ADTypes.jl) and re-exported by DifferentiationInterface.jl:
 
 ```@repl tuto
 backend = AutoForwardDiff()

src/DifferentiationInterface.jl

@@ -16,6 +16,22 @@ using ADTypes:
     AbstractFiniteDifferencesMode,
     AbstractReverseMode,
     AbstractSymbolicDifferentiationMode
+using ADTypes:
+    AutoChainRules,
+    AutoDiffractor,
+    AutoEnzyme,
+    AutoFiniteDiff,
+    AutoFiniteDifferences,
+    AutoForwardDiff,
+    AutoPolyesterForwardDiff,
+    AutoReverseDiff,
+    AutoSparseFiniteDiff,
+    AutoSparseForwardDiff,
+    AutoSparsePolyesterForwardDiff,
+    AutoSparseReverseDiff,
+    AutoSparseZygote,
+    AutoTracker,
+    AutoZygote
 using DocStringExtensions
 using FillArrays: OneElement
 using LinearAlgebra: Symmetric, dot
@@ -67,6 +83,22 @@ include("hessian.jl")
 
 include("backends.jl")
 
+export AutoChainRules,
+    AutoDiffractor,
+    AutoEnzyme,
+    AutoFiniteDiff,
+    AutoFiniteDifferences,
+    AutoForwardDiff,
+    AutoPolyesterForwardDiff,
+    AutoReverseDiff,
+    AutoSparseFiniteDiff,
+    AutoSparseForwardDiff,
+    AutoSparsePolyesterForwardDiff,
+    AutoSparseReverseDiff,
+    AutoSparseZygote,
+    AutoTracker,
+    AutoZygote
+
 export AutoFastDifferentiation, AutoSparseFastDifferentiation, AutoTapir
 export SecondOrder
 

src/second_order.jl

@@ -3,6 +3,10 @@
 
 Combination of two backends for second-order differentiation.
 
+# Constructor
+
+    SecondOrder(outer, inner)
+
 # Fields
 
 $(TYPEDFIELDS)