FUNCTION interp_coeffs_1d, vdata, poles, tol, DanIDL_C_code
; Description: This function calculates the vector of interpolation coefficients for an input vector
; of data "vdata" and a given interpolation scheme with filter poles "poles". The
; calculation of the initial value of the causal coefficient can be speeded up by setting
; the value of "tol" to a positive value greater than "0.0" but less than "1.0", which
; represents the maximum acceptable relative error during the filtering process.
; This function will use C++ code if possible to achieve a much faster execution than
; the default IDL code. The C++ code is an astounding factor of ~62 times faster than the
; IDL code in this case.
;
; Input Parameters:
;
; vdata - FLOAT/DOUBLE VECTOR - A one-dimensional data vector for which the interpolation coefficients
; are to be calculated. Note that this data vector should not contain
; bad data values, so such values should have been previously
; interpolated over in "vdata".
; poles - FLOAT/DOUBLE VECTOR - A one-dimensional vector of values for the poles required for the recursive
; filter. A list of the pole values required for each interpolation scheme
; are reported here for convenience:
;
; Interpolation Scheme: No. Poles: First Pole: Second Pole:
;
; Quadratic B-splines 1 sqrt(8)-3
; Cubic B-Splines 1 sqrt(3)-2
; Quartic B-Splines 2 sqrt(664-sqrt(438976))+sqrt(304)-19 sqrt(664+sqrt(438976))-sqrt(304)-19
; Quintic B-Splines 2 (sqrt(270-sqrt(70980))+sqrt(105)-13)/2 (sqrt(270+sqrt(70980))-sqrt(105)-13)/2
; Cubic O-MOMS 1 (sqrt(105)-13)/8
;
; tol - FLOAT/DOUBLE - The maximum acceptable relative error during the filtering process. By setting
; this parameter to a positive value greater than "0.0" but less than "1.0", the
; initial value of the causal coefficient is calculated from a subset of data
; values, while achieving the acceptable relative error "tol". By setting this
; parameter to any other value, the initial value of the causal coefficient is
; calculated exactly from all data values in the vector.
; DanIDL_C_code - STRING - The full directory path indicating where the DanIDL C++ code is installed.
; The shared library of DanIDL C++ routines should exist as
; "/dist/libDanIDL.so" within the installation.
;
; Return Value:
;
; The return value is a one-dimensional vector of DOUBLES of the same length as "vdata" that
; represents the interpolation coefficients for the given interpolation scheme with filter poles
; "poles". If this module fails for any reason, then the return value is 0.0D.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 15/08/2008 - Module created (dmb)
;Check that "vdata" is a one-dimensional vector of the correct number type, and if there is only one
;input data point, then return the input data point
;Check that "poles" is a one-dimensional vector of the correct number type
;Check that "tol" is a number of the correct type
;Determine if the shared library of DanIDL C++ routines is installed
;Set up the output vector of interpolation coefficients
;If the shared library of DanIDL C++ routines is installed, then use the C++ code to speed up
;the calculation of the interpolation coefficients
;Calculate the interpolation coefficients
;If the shared library of DanIDL C++ routines is not installed, then use the default IDL code
;Compute the overall gain, and apply this gain to the interpolation coefficients
;If "tol" is greater than "0.0" but less than "1.0", then calculate the lengths of the
;required truncated sums
;For each pole
;If the length of the truncated sum is less than the length of "vdata", then calculate
;the initial value of the causal coefficient with a truncated sum
;If the length of the truncated sum is the same as or greater than the length of "vdata",
;then calculate the initial value of the causal coefficient with a full sum
;Execute the causal recursion on the interpolation coefficients
;Calculate the initial value of the anti-causal coefficient
;Execute the anti-causal recursion on the interpolation coefficients
;Return the output vector of interpolation coefficients