RTMB (version 1.8)

Tape: The AD tape

Description

The AD tape as an R function

Usage

MakeTape(f, x)
# S3 method for Tape
$(x, name)
# S3 method for Tape
print(x, ...)
TapeConfig(
  ...,
  comparison = c("NA", "forbid", "tape", "allow"),
  atomic = c("NA", "enable", "disable"),
  vectorize = c("NA", "disable", "enable")
)
DataEval(f, x)
GetTape(obj, name = c("ADFun", "ADGrad", "ADHess"), warn = TRUE)

Value

Object of class "Tape".

Arguments

f

R function

x

numeric vector

name

Name of a tape method

...

Ignored

comparison

Set behaviour of AD comparison (">","==", etc).

atomic

Set behaviour of AD BLAS operations (notably matrix multiply).

vectorize

Enable/disable AD vectorized 'Ops' and 'Math'.

obj

Output from MakeADFun

warn

Give warning if obj was created using another DLL?

Methods (by generic)

• $: Get a tape method.

• print(Tape): Print method

Functions

• MakeTape(): Generate a 'Tape' of an R function.

• TapeConfig(): Global configuration parameters of the tape (experts only!) comparison By default, AD comparison gives an error (comparison="forbid"). This is the safe and recommended behaviour, because comparison is a non-differentiable operation. If you are building a tape that requires indicator functions e.g. f(x)*(x<0)+g(x)*(x>=0) then use comparison="tape" to add the indicators to the tape. A final option comparison="allow" exists for testing/illustration purposes. Do not use.

• DataEval(): Move a chunk of data from R to the tape by evaluating a normal R function (replaces TMB functionality 'DATA_UPDATE').

• GetTape(): Extract tapes from a model object created by MakeADFun.

Details

A 'Tape' is a representation of a function that accepts fixed size numeric input and returns fixed size numeric output. The tape can be constructed using F <- MakeTape(f, x) where f is a standard differentiable R function (or more precisely: One using only functions that are documented to work for AD types). Having constructed a tape F, a number of methods are available:

Evaluation:

• Normal function evaluation 'F(x)' for numeric input.

• AD evaluation 'F(x)' as part of other tapes.

• Jacobian calculations using 'F$jacobian(x)'.

• Signal that the next forward pass should drop lazy evaluation and update the entire tape F$force.update().

Transformation:

• Get new tape representing the Jacobian using F$jacfun().

• Get new tape representing the sparse Jacobian using F$jacfun(sparse=TRUE).

• Get new tape representing the Laplace approximation using F$laplace(indices).

• Get new tape representing the Saddle Point approximation using F$laplace(indices,SPA=TRUE).

• Get new tape representing the optimum (minimum) wrt indices by F$newton(indices).

• Get a 'shared pointer' representation of a tape using F$atomic().

• Get tape of a single node by F$node(index) (mainly useful for derivative debugging).

• Reorder tape so selected inputs (indices) and its forward dependencies come as late as possible by F$reorder(indices).

Modification:

• Simplify internal representation of a tape using F$simplify().

Extract tape information:

• Get internal parameter vector by F$par().

• Get computational graph by F$graph().

• Print the tape by F$print().

• Get internal arrays as a data.frame by F$data.frame().

• Find out where the tape spends its time by F$timer().

Examples

F <- MakeTape(prod, numeric(3))
show(F)
F$print()
H <- F$jacfun()$jacfun() ## Hessian tape
show(H)
#### Handy way to plot the graph of F
if (requireNamespace("igraph")) {
   G <- igraph::graph_from_adjacency_matrix(F$graph())
   plot(G, vertex.size=17, layout=igraph::layout_as_tree)
}
## Taped access of an element of 'rivers' dataset
F <- MakeTape(function(i) DataEval( function(i) rivers[i] , i), 1 )
F(1)
F(2)
## DATA_UPDATE example
## - Pay attention to lazy evaluation!
## - Use 'force.update()'
mydat <- 1:4
fetch <- function() { print("Getting 'mydat'"); .GlobalEnv$mydat }
F <- MakeTape( function(x) x * sum(DataEval(fetch)), 1 )
F$reorder() ## Re-order tape for faster execution
F(1) ## No data update
F(2) ## No data update
mydat <- 5:8
F(1) ## Still no data update !
F$force.update() ## Signal that data has changed
F(1) ## data update
F(2) ## No data update