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.
makeModelDerivsInfo(model, wrtNodes, calcNodes, dataAsConstantNodes = TRUE)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.
a nimble model object, such as returned from nimbleModel.
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).
a character vector of node names in the model that will be
used in model$calculate(calcNodes) while derivatives are being
recorded.
logical indicating whether data nodes in the model should automatically be treated as "constant" entries (TRUE) or "update" entries (FALSE). Defaults to TRUE.
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.