What doc would help developers of the Math library?


Over the next few months, I want to focus on making it easier to develop in the Math library. I had dinner with @breckbaldwin last week and it was clear that this is something we’re lacking.

I’ll just dedicate a few hours a week doing this.

Anyone have ideas on what resources would help? I’d love to hear ideas from anyone:

  • existing devs
  • newer devs
  • people that would consider developing, but are having difficulties

Thanks, all.

  1. Intro to C++ concepts needed to develop for Stan. I’ve written C and limited amounts of C++, however much of the Stan code is a mystery to me. I’d like to be able to understand enough of the templated code to read the code and contribute new functions.

  2. Description of directory structure of the Stan source. I’m sure it’s quite simple once you get the hang of it, but I find myself grepping through it all to find the code I need.

  3. Guidelines for what should be in the Stan code and what should be in user specific functions. If I am implementing, say a general inverse Gaussian distribution, should this be included in Stan math? What about more obscure and domain specific models?

  4. Walkthrough of how how to implement, something, required documentation, pull request process etc.

  1. I’ve read some of the documents on templating, and added to the Stan docs, but they are trivial. Some examples with references to Stan code would be great. May be something ‘typical’ of Stan, including both templates and enable_if programming, or some more complex non-trivial features.

  2. A description of the map from Stan datatypes to C++ datatypes. (i.e. [stan -> c++] -> [vector[n] y -> Eigen::Matrix<double, Eigen::Dynamic, 1>)

  3. There is a way to visualize the objects put on the stack (stan::math::print_stack().) A description of this feature of Stan development would be cool, we obviously want the library as efficient as possible. If there’s any other features like this we haven’t seen yet, please let us know!

  4. More in depth description of all of the memory management features unique to the stan library (i.e. stan::math::recover_memory()).

  5. Description of how to use/print the gradient functions in Stan, and any other diagnostic tools for making sure our code/math is accurate ( some_var_.grad(vars, grad)) and then (for (auto g : grad) { std::cout << g << std::endl;}

  6. How does the architecture from rev-> prim work? I threw some print statements in gp_exp_quad_cov formerly (cov_exp_quad) to see how it works. rev fuctions are precompiled, and then call some of the prim functions on runtime? How does this work exactly? What kind of templating it happening to make sure rev is going to which prim? Can we have a quick visualization on a simple stan program to know what’s happening?

  7. I haven’t done this stuff yet, but I’d like to be able to run a specific branch on my fork to test some stuff out (i.e. compare a simple generative model to GPstuff, etc). May be a description about this could be useful for beginning developers. I’ve done some derivations of the gradients as in the Autodiff paper and for some functions in the math library, but I don’t trust my math until I do some comparisons!

If there are other memory or gradient tools that we can use, please give us a description! Or, just point me to the docs!


About two weeks ago I fixed up jenkins so the doxygen site for stan math is available. May be a useful place to put some of the guidelines and concepts mentioned above


It would be nice to flesh it out more so that it looks something like Eigen or ViennaCL’s docs



That would be a yearlong course in C++ and numerical analysis! We just don’t have time for that. We’re going to just have to assume people know C++11 well and provide examples of how Stan fits into that.

I highly recommend Vandevoorde and Josuttis for template metaprogramming (all the expression templates, type lists, and traits we use, as well as recursive template metaprogramming, lazy function evaluation, etc. are all covered).

This is going to change a bit, but it’s at the front of our doc, including the legal dependencies. We could use some examples. The short answer is:

{prim, rev, fwd, mix} / {scal, arr, mat, meta, err }

We don’t have any other than what we think might be useful.

I think a case study on this would be great.

The top-level overview of all that’s in our reverse-mode autodiff paper on arXiv.

That would be good for a case study, but it’s literally just a loop like you laid out. We’re recommending people use our functionals for most purposes now that you have closures and binding.

I’m afraid that depends on the function.

Sean’s working on that.

Lots of stuff out there, but nothing Stan-specific.


Doc for the intended usage of metaprograms would be nice


Sure - it just wasn’t something I found in the docs. @syclik showed me this. When I’m comfortable with the library I can write a case study on this topic.

drezap: I can do this, with my first commit as an example. Is a latex document fine? Where should I send it when complete? This http://mc-stan.org/users/documentation/case-studies send me back to this forum.

Quick question:

So I believe for rev we need implement different functions for different inputs/stan datatypes, can I just add support for a certain datatypes, with prim as the “catch all”, and come back to it when my template metaprogramming improves or I come up with a solution? I have something that’s works and I can commit, but I’m stuck at some flow control/template problem. So the autodiff will not be enabled with certain datatypes, but it’s still “functional”/“works”.

Not sure where to post this question. I just want to merge something and come back to it later.


I think you could bring a lot of people on board who could meaningfully contribute new functions to Stan math without fully understanding the details of how Stan works.

Maybe this would be enough:


Not about doc, but I feel it may help by categorizing unit tests into groups, for example by compile+run time. Before a developer sends to Jenkins, he should pass all the short tests, which takes a reasonable wall time. Current wiki requirement for finishing all the tests takes too long to be effective in practice.


Thanks for the responses. I think it’s clear that we need to separate out the docs a bit for the math library. We need a user-facing doc and dev-facing doc. Over the next couple weeks, I’ll try to come up with some organization that helps.

Yup. Heard. It’s a chicken and egg problem. We don’t strictly need all that testing if there are enough unit tests in place. The problem is explaining the combinatorics of templated programming and what that truly means for a developer to test in order to verify the code is correct. I’m going to try to write all that down too.