[bmelinden]

Summary

This PR adds the possibility to set up look-up tables using cubic splines as part of a stan model (#3365). The functionality mirrors that of Boost interpolators (https://www.boost.org/doc/libs/latest/libs/math/doc/html/interpolation.html), and includes cubic Hermite interpolation, PCHIP and Modified Akima splines. The constructs support non-equidistant nodes at the price of O(log(n)) evaluation complexity. Splines with equidistant nodes that evaluates in constant time may be included in a future update.

The primary use case of this pull request is to make it easy include experimental data or pre-calculated functions into model definitions, not to model smooth curves (Stan already supports smoothing splines). If attempting the latter though, note that PCHIP and MAKIMA interpolation has kinks in derivatives wrt to input values yk, and thus if yk is used as parameters, the log density is not differentiable everywhere. Cubic hermite interpolation with parametrised derivaties does not suffer from this problem.

The new functionality is implemented in
stan/math/prim/fun/interpolate_1d_cubic_spline.hpp

Usage is divided into two steps. 1) define the loop-up table using e.g.,
interpolate_1d_name_of_method_setup(x,y,dydx) with which returns a tuble W with knots x, values y, and derivatives dydx. For hermite interpolation, the derivatives are given as input to the setup function. For PCHIP and MAKIMA, only x,y are given, and Boost is used to calculate the derivatives 2) compute an interpolated value for the value x by calling the corresponding eval function interpolate_1d_cubic_spline(x,W), same for all cubic spline interpolation methods.

Tests

Test are included in
test/unit/math/prim/fun/interpolate_1d_cubic_spline_test.cpp

Side Effects

No known side effects.

Release notes

Add functionality to setup up and use look-up tables based on cubic splines, using functions
W=interpolate_1d_..._setup() and y=interpolate_1d_cubic_spline(x,W).

Checklist

• Copyright holder: Martin Lindén

  The copyright holder is typically you or your assignee, such as a university or company. By submitting this pull request, the copyright holder is agreeing to the license the submitted work under the following licenses:
  - Code: BSD 3-clause (https://opensource.org/licenses/BSD-3-Clause)
  - Documentation: CC-BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

• the basic tests are passing

  • unit tests pass (to run, use: ./runTests.py test/unit) : check
  • header checks pass, (make test-headers) : check
  • dependencies checks pass, (make test-math-dependencies) : check
  • docs build, (make doxygen)
  • code passes the built in C++ standards checks (make cpplint)

• the code is written in idiomatic C++ and changes are documented in the doxygen : I think so, but I relied heavily on AI for both functional code and tests.

• the new changes are tested : only on the C++ code level, I have not ran stan code with the latest version