Design Doc: Derivatives of distributions

This document is meant to make sure we're in agreement about derivatives of functions that return -Inf.
To make this concrete, it will focus on taking derivatives of distribution functions when one or more arguments are outside the range of acceptable values. For example, consider the dgamma() function with arguments:

• x, must be >= 0
• shape, must be >= 0
• scale, must be > 0
• log, defaults to FALSE

Suppose that an x value is supplied that is negative (e.g. x = -1), and that log = FALSE. In this case, calling an uncompiled version of nimDerivs(dgamma(-1, shape, scale, log = FALSE)) (which takes the numeric derivative of R's native dgamma() function) will return the following nimbleList:

nimbleList object of type NIMBLE_ADCLASS
Field "value":
[1] 0
Field "gradient":
     [,1] [,2] [,3]
[1,]    0    0    0
Field "hessian":
, , 1

     [,1] [,2] [,3]
[1,]    0    0    0
[2,]    0    0    0
[3,]    0    0    0

These results seem reasonable. It is possible to have the derivative-enabled, compiled version of dgamma() produce these same results.

Now suppose that log = TRUE. In this case, calling an uncompiled version of nimDerivs(dgamma(-1, shape, scale, log = TRUE)) will return the following:

nimbleList object of type NIMBLE_ADCLASS
Field "value":
[1] -Inf
Field "gradient":
     [,1] [,2] [,3]
[1,]  NaN  NaN  NaN
Field "hessian":
, , 1

     [,1] [,2] [,3]
[1,]  NaN  NaN  NaN
[2,]  NaN  NaN  NaN
[3,]  NaN  NaN  NaN

Here, the NaN derivative values are likely the result of the numerical derivative procedure (which may come from taking a fraction like -Inf / -Inf).

Question: Is setting derivatives of functions that return -Inf to NaN the behavior that we'd like to mimic in the compiled version of nimDerivs? NaN seems like a reasonable choice, but they could also be set to e.g. 0.