makeModelDerivsInfo: Information on model structure used for derivatives

In nimble: MCMC, Particle Filtering, and Programmable Hierarchical Modeling

Information on model structure used for derivatives

Description

Inspect structure of a nimble model to determine nodes needed as "update" and/or "constant" entries in usage of nimDerivs. This will typically be used in the setup code of a nimbleFunction.

Usage

makeModelDerivsInfo(model, wrtNodes, calcNodes, dataAsConstantNodes = TRUE)

Arguments

model	a nimble model object, such as returned from nimbleModel.
wrtNodes	a character vector of node names in the model with respect to which derivatives will be taken through a call to nimDerivs (same as derivs).
calcNodes	a character vector of node names in the model that will be used in model$calculate(calcNodes) while derivatives are being recorded.
dataAsConstantNodes	logical indicating whether data nodes in the model should automatically be treated as "constant" entries (TRUE) or "update" entries (FALSE). Defaults to TRUE.

Details

In the compilable parts of a nimbleFunction (i.e. run or other method code, not setup code), a call like nimDerivs(foo(x), ...) records derivatives of foo(x). If foo contains any calls to model$calculate(calcNodes), it may be necessary to provide auxiliary information about the model in further arguments to nimDerivs, specifically the model, updateNodes and constantNodes arguments. 'makeModelDerivsInfo' is a utility to set up that information for typical use cases. It returns a list with elements updateNodes and constantNodes to be passed as arguments of the same name to nimDerivs (along with passing the model as the model argument).

The reason auxiliary information is needed is that recording of derivatives uses a different model than for regular calculations. Together, updateNodes and constantNodes should contain all nodes whose values are needed for the model calculations being recorded and that are not part of wrtNodes. These may include parents of nodes that are in calcNodes but are not themselves in calcNodes, as well as the values of stochastic nodes in calcNodes, which are needed to calculate the corresponding log probabilities. updateNodes will have their values updated from the regular model every time that recorded derivative calculations are used. constantNodes will not be updated every time, which means their values will be permanently fixed either the first time the call to 'nimDerivs' is invoked or on any subsequent call that has reset=TRUE. Use of constantNodes can be slightly more efficient, but one must be careful to be aware that values will not be updated unless reset=TRUE. See the automatic differentiation section of the User Manual for more information.

In the above explanation, care must be taken to understand what should be included in wrtNodes. In a typical use case, some arguments to foo are put into the model using values(model, nodes) <- some_foo_arguments. Next there is typically a call to model$calculate(calcNodes). Here the nodes are considered "with-respect-to" nodes because derivative tracking will follow the arguments of foo, including when they are put into a model and hence used in model$calculate. Therefore these nodes should be the wrtNodes for makeModelDerivsInfo.

Value

A list with elements updateNodes and constantNodes. These shouls be provided as the same-named arguments to nimDerivs (same as derivs).

When using double-taping of derivatives (i.e. foo contains another call to nimDerivs), both calls to nimDerivs should include the model, updateNodes, and constantNodes arguments.

nimble documentation built on July 9, 2023, 5:24 p.m.