libs/math/doc/interpolators/cardinal_quintic_b_spline.qbk

   1 [/
   2 Copyright (c) 2019 Nick Thompson
   3 Use, modification and distribution are subject to the
   4 Boost Software License, Version 1.0. (See accompanying file
   5 LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6 ]
   7
   8 [section:cardinal_quintic_b Cardinal Quintic B-spline interpolation]
   9
  10 [heading Synopsis]
  11 ``
  12   #include <boost/math/interpolators/cardinal_quintic_b_spline.hpp>
  13 ``
  14
  15     namespace boost{ namespace math{ namespace interpolators {
  16
  17     template <class Real>
  18     class cardinal_quintic_b_spline
  19     {
  20     public:
  21         // If you don't know the value of the derivative at the endpoints, leave them as NaNs and the routine will estimate them.
  22         // y[0] = y(a), y[n - 1] = y(b), step_size = (b - a)/(n -1).
  23         cardinal_quintic_b_spline(const Real* const y,
  24                                   size_t n,
  25                                   Real t0 /* initial time, left endpoint */,
  26                                   Real h  /*spacing, stepsize*/,
  27                                   std::pair<Real, Real> left_endpoint_derivatives = {std::numeric_limits<Real>::quiet_NaN(), std::numeric_limit<Real>::quiet_NaN()},
  28                                   std::pair<Real, Real> right_endpoint_derivatives = {std::numeric_limits<Real>::quiet_NaN(), std::numeric_limit<Real>::quiet_NaN()})
  29
  30         cardinal_quintic_b_spline(std::vector<Real> const & y,
  31                                   Real t0 /* initial time, left endpoint */,
  32                                   Real h  /*spacing, stepsize*/,
  33                                   std::pair<Real, Real> left_endpoint_derivatives = {std::numeric_limits<Real>::quiet_NaN(), std::numeric_limit<Real>::quiet_NaN()},
  34                                   std::pair<Real, Real> right_endpoint_derivatives = {std::numeric_limits<Real>::quiet_NaN(), std::numeric_limit<Real>::quiet_NaN()})
  35
  36         Real operator()(Real t) const;
  37
  38         Real prime(Real t) const;
  39
  40         Real double_prime(Real t) const;
  41
  42     };
  43     }}}
  44
  45 [heading Cardinal Quintic B-Spline Interpolation]
  46
  47 The cardinal quintic B-spline interpolator is very nearly the same as the cubic B-spline interpolator,
  48 with the modification that the basis functions are constructed by convolving a box function with itself five times,
  49 rather than three times as is done with the cubic B-spline.
  50
  51 The basis functions of the quintic B-spline interpolator are more smooth than the cubic /B/-spline interpolator, and hence this is very useful for computing second derivatives.
  52 For example, the second derivative of the cubic spline interpolator is a piecewise linear function, whereas the second derivative of the quintic /B/-spline is a cubic spline.
  53 The graph of the second derivative of the quintic /B/-spline is therefore more visually appealing, though whether it is in fact more accurate depends on the smoothness of your data.
  54
  55 And example usage is as follows:
  56
  57     #include <boost/math/interpolators/cardinal_quintic_b_spline.hpp>
  58     using boost::math::interpolators::cardinal_quintic_b_spline;
  59     std::vector<double> v(512);
  60     // fill v with data . . .
  61     double t0 = 0; // initial time
  62     double h = 0.125; // spacing
  63     std::pair<double, double> left_endpoint_derivatives{first_derivative_at_t0, second_derivative_at_t0};
  64     std::pair<double, double> right_endpoint_derivatives{first_derivative_at_tf, second_derivative_at_tf};
  65     auto qs = cardinal_quintic_b_spline<double>(v, t0, h, left_endpoint_derivatives, right_endpoint_derivatives);
  66
  67     // Evaluate the interpolant at a point:
  68     double y = qs(0.1);
  69     // Evaluate the derivative of the interpolant:
  70     double yp = qs.prime(0.1);
  71     // Evaluate the second derivative of the interpolant:
  72     double ypp = qs.double_prime(0.1);
  73
  74 This routine will estimate the endpoint derivatives if they are not provided.
  75 /Try to avoid this if possible./
  76 The endpoint derivatives must be evaluated by finite differences and this is not robust again perturbations in the data.
  77 So if you have some way of knowing the endpoint derivatives, make sure to provide them.
  78
  79 [heading References]
  80
  81 Cox, Maurice G. ['Numerical methods for the interpolation and approximation of data by spline functions.] Diss. City, University of London, 1975.
  82
  83 [endsect] [/section:cardinal_quintic_b]