What is the supported external API of the Math Library?

Developers
18

I wrote this, but I’ll get into a little more detail:

Different Math devs have written different versions over the years (I’m listing what I can find quickly down below), but what I consider to be the current API is written here: Quick Start · stan-dev/math Wiki · GitHub.

To break it down a bit:

  • 13 header includes. C++ clients can expect these to exist.
    • stan/math.hpp
    • these 12 header files: stan/math/{prim, rev, fwd, mix}/{scal, arr, mat}.hpp (but we’re trying to knock that down to 4 with the “flattening” refactor)
  • Math functions (almost everything in the stan::math namespace):
    • every function in err, fun, functor, prob, and vectorize folders, e.g. stan/math/prim/scal/fun/*.hpp.
    • a lot of the meta folder, but not all; some of this is considered “internal,” but clients should have access to templated functions like value_of(...) or is_var

That covers almost everything in the Math library. I can’t think of a single function signature I’d be willing to change at will, but I’m sure there are a handful of functions that we could. In practice, we’ve acted as though this is our API because we’ve deprecated functions like normal_log() when we could easily have removed it and had Stan’s generator handle the name change.

So, that’s what I consider to be the C++ API. I know there are users (that have posted on Discourse) that have stated they use the Math library for higher order autodiff without the Stan language. I don’t know if the number of clients that use it for that purpose are in the single digits or if it’s much higher.

Different places where Math devs and users have discussed it:

1 Like