Clarify that Stan uses non-standard/improved NUTS

[bbolker]

Summary:

While the documentation does explicitly say that Stan uses a non-standard/improved version of NUTS, this fact is easy to miss. It would be nice if it were more clearly stated.

Description

This section refers to Betancourt 2016b, and would indicate to a very careful reader that Stan is using a version of NUTS that has been adapted/improved from the original specification of Hoffman and Gelman (2014). However, this distinction is easy to miss. It would be nice if a phrase/sentence or two could be added in key places (e.g., both in this section and in the overall introduction to this section that clarified that a variant was being used. (See this tweet from 2016.

I can see here that exhaustive HMC and a multinomial variant of NUTS were added in release 2.10.0, but it's not clear to me which of these samplers is actually used ... ? (Bob Carpenter says in this thread that XHMC is not used, and Michael Betancourt cites Appendix A5 here to clarify that the multinomial variant is used:

In addition to the generalized No-U-Turn termination criterion, the Hamiltonian Monte Carlo implementation in Stan uses multinomial sampling from each trajectory instead of slice sampling, which provides a significant improvement in overall performance.

(This is also clear in hindsight from reading the docs - it's just not very clear if you don't know what you're reading!)

Additional Information:

I could submit a pull request if requested, but it would probably be better done by someone who has more detailed technical knowledge about the differences between vanilla-NUTS and improved-NUTS than I do.

Current Version:

v2.18.0

[bob-carpenter]

Thanks, @bbolker. You're right that this isn't clear in our doc. We need to do a better job at describing all of our algorithms. I have what I think is cleaner pseudocode for the NUTS algorithm from Hoffman and Gelman's paper, but it's still brutal and it doesn't incorporate the updates. And I have no way of really verifying that it's correct as written, so I'm reluctant to roll it out. The main blocker for this is that someone needs to read through the C++ code and match it with the doc description.