Stan Math Release notes draft

There was a debate on one of the closed Stan Math PRs regarding the release notes. I didnt feel like having another long winded discussion so I took 15 minutes and did a first draft.

Two questions:

  • Does anyone mind if we open a new wiki page where we keep an updated list of such one-liners? If you feel helping out this process just add a one-liner “Release notes” to each Math PR you open. If not, that is also fine with me, dont want to set new rules just for this. Its only 15 minutes/3 months :).
  • Any objections to the draft?

Stan-user facing changes:

  • added a new function to solve systems of nonlinear algebraic equations using Newton-Krylov methods.
  • re-implemented a reentrant safe and scalable version of lgamma
  • change the default boost_policy_t to avoid the double to long double propagation, this could affect the following functions: falling_factorial, rising_factorial, digamma and lgamma
  • implemented oridinal_logistic_glm_lpmf
  • fixed boundary conditions for log_sum_exp and log_diff_exp
  • GPU support for the following functions: gp_exp_quad_cov, mdivide_right_tri, multiply, mdivide_left_tri, normal_id_lgm, bernoulli_logit_glm_lpmf and poisson_log_glm_lpmf


  • added a new autodiff testing framework for simpler and more automated tests
  • added finite difference versions of gradient, Hessian, and gradient of Hessian functions that automatically scale step size based on input
  • cleaned up test behaviour when -NDEBUG is set
  • tests for bernoulli_logit, poisson_log and negbin_2_log GLMs are now tested with y as std::vector instead of Eigen::Matrix for better test coverage of the usual use case from Stan

Refactor/Code cleanup/Technical debt:

  • refactor of the type traits to use more C++14 features & SFINAE
  • cleaned up rev/mat/fun with the eigen plugin methods .val(), .adj() and .vi()
  • typename *_return type was changed to *_return_type_t
  • removed deprecated Eigen content from math headers
  • metaprograms cleanups: added various enable_if_*
  • added use of const ref and ref to replace copies with moves
  • added clang-tidy to the makefiles
  • cleaned up unnecesary Boost and Gtest compiler flags
  • beta binomials lpmf loop and conditionals cleanup
  • clang-tidy cleanup of the Stan Math codebase (adding braces, replace typedef with using and NULL with nullptr)
  • the make test-math-dependencies file was rewritten from make to Python


  • GPU support for prim/gp_exp_quad_cov, prim/mdivide_right_tri, prim/multiply, rev/multiply
  • fixed a bug with padding matrices
  • added the triangularity view to matrix_cl
  • the key for opencl kernel options is now a std::string not a const char *
  • added move constructors and assigments to avoid unnecesary copying
  • all references to “GPU” were changed to “CL”
  • changed the copy function to to_matrix_cl and from_matrix_cl
  • updated the OpenCL headers which also allowed for some OpenCL core code cleanup

Thank you Rok!! It would be nice to have the PR # and person who submitted so we can give contributors props. That’s a bit tedious, tmrw I’ll see if I can write a script that grabs info for all the PRs merged since the last release. @syclik do you have something like that already?

Do we have any speedup graphs for the OpenCL code? I can write up a draft tomorrow for the more narrative release notes (unless Dan or Bob wants to take the wheel on that of course)

1 Like

I can add PR numbers and names (github handles), thats probably a 5-10min job anyways. I will send you the slides with the speedups. Thanks!

1 Like

This is great!

I have no objections. I used to do it manually and it was more like 2 hours every release, but if you can do it faster, great!

Steve, nope. I did it manually using filters on the issues. Go for it!

Rok, you’re missing a couple user-facing things:

  • the lgamma PR changed the default compiler options; all interfaces should be updated.

  • numeric computations with the last version might have changed if it called boost; this was due to overriding the default boost policy with a custom one that’s changed this release. So this version may not replicate the last version.

Thanks, Rok.

We used to try to link the commits at one point and give props to bug reporters and anyone not on the stan-dev list.

Automating all this sounds great, but until then, great on Rok for doing it manually! I don’t think anyone will object.

It started with Daniel and I doing all the triage and writing all the release notes by scrolling through the commit messages, issues, and PRs. That was a terrible process and we missed a lot of stuff.

At the risk of starting a debate, I wouldn’t have even called that a debate! The only issue in that discussion that touched release notes was whether they could be automated by including a special field in PRs.

I still think it’s good to have the end Stan user in mind when creating, editing, working on, and releasing issues in the Math library. Adding a release notes block that is to be written from the Stan user’s perspective would suffice.

Do you mean “creating releases” instead of “releasing issues”?

I also think it’s good to think about and write for the Stan user, but it’s an awkward policy to force issues in Math to be written that way. If that’s what we all agree on, that’s fine, but think about how this would affect all the other parts of the Stan ecosystem. Do you think it’s going to be productive to write stanc3 issues so that it’s written for the Stan user?

I’m ok if we decide to adopt a general policy to state how an issue affects the Stan user (this may be left blank if it’s an internal change). One reason to not do this is because it adds yet another requirement on the person adding the issue / PR (wherever the policy is applied). There’s also an issue that the person writing the issue or code may not have the knowledge to write this down. In that case, what happens? Is the issue supposed to be rejected?

There were a bit over 50 PRs open since the last release, some of them were closed before merge. Most of the merged once I was either the author or the reviewer or they had a large enough effect on my work that I was aware of them. I only had to actually click on maybe 5 PRs. So I had it easy this time.

Thanks for those. Also added the Newton solver added yesterday. Will keep the top-level comment updated until the release.

That is fair. I just felt we circled around this in various places in the last few months.

Alrighty since we have the feature freeze I went through and wrote up an R script to grab all the merged PRs and wrote up a few release notes for this cycle. The gist below has both the R script to grab the PR info along with a little narrative for the changes this release.

I tried to tag all parties and mention their contributions. If anyone would like to change the wording lmk!


Steve this looks fantastic! I will do a more detailed look tomorrow, the text up top is light out.

1 Like