From bb200a628fd3dcfdcf9e512f49f0966b3ddb8936 Mon Sep 17 00:00:00 2001 From: Guillaume Dalle <22795598+gdalle@users.noreply.github.com> Date: Wed, 6 Nov 2024 14:48:42 +0100 Subject: [PATCH] docs: clarify tape recording in ReverseDiff docstring --- Project.toml | 2 +- src/dense.jl | 19 ++++++++++++++++++- 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/Project.toml b/Project.toml index 21726ae..ce144ee 100644 --- a/Project.toml +++ b/Project.toml @@ -1,7 +1,7 @@ name = "ADTypes" uuid = "47edcb42-4c32-4615-8424-f2b9edc5f35b" authors = ["Vaibhav Dixit , Guillaume Dalle and contributors"] -version = "1.9.0" +version = "1.9.1" [deps] ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4" diff --git a/src/dense.jl b/src/dense.jl index aa028bc..58a4846 100644 --- a/src/dense.jl +++ b/src/dense.jl @@ -298,7 +298,24 @@ Defined by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). # Fields - - `compile::Union{Val, Bool}`: whether to [compile the tape](https://juliadiff.org/ReverseDiff.jl/api/#ReverseDiff.compile) prior to differentiation (the boolean version is also the type parameter) + - `compile::Union{Val, Bool}`: whether to allow pre-recording and reusing a tape (which speeds up the differentiation process). + + + If `compile=false` or `compile=Val(false)`, a new tape must be recorded at every call to the differentiation operator. + + If `compile=true` or `compile=Val(true)`, a tape can be pre-recorded on an example input and then reused at every differentiation call. + + The boolean version of this keyword argument is taken as the type parameter. + +!!! warning + + Pre-recording a tape only captures the path taken by the differentiated function _when executed on the example input_. + If said function has value-dependent branching behavior, reusing pre-recorded tapes can lead to incorrect results. + In such situations, you should keep the default setting `compile=Val(false)`. + For more details, please refer to ReverseDiff's [`AbstractTape` API documentation](https://juliadiff.org/ReverseDiff.jl/dev/api/#The-AbstractTape-API). + +!!! info + + Despite what its name may suggest, the `compile` setting does not prescribe whether or not the tape is compiled with [`ReverseDiff.compile`](https://juliadiff.org/ReverseDiff.jl/dev/api/#ReverseDiff.compile) after being recorded. + This is left as a private implementation detail. """ struct AutoReverseDiff{C} <: AbstractADType compile::Bool # this field is left for legacy reasons