Michael Thomas Flanagan's Java Scientific Library

CubicSpline Class:     Cubic Spline Interpolation

      

Last update: 11 September 2012                                                                                                                              Main Page of Michael Thomas Flanagan's Java Scientific Library

This class contains the constructor and methods for performing an interpolation within a one dimensional array of data points, y = f(x), using a cubic spline. The default option is a natural spline but the user may override this by entering the limiting first derivatives.
It also contains a method for returning the interpolated first derivative, dy/dx.
This class also contains the array and new instance creation methods required by the related class, BiCubicSpline.

See CubicSplineFast for a version with all the data checking statements and methods removed allowing faster execution times.
See CubicInterpolation for a general cubic interpolation.
See also Gradient for the calculation of the cubic spline interpolated first derivatives for each element of a 1D array.

import directive: import flanagan.interpolation.CubicSpline;

SUMMARY OF CONSTRUCTOR AND METHODS
Constructors public CubicSpline(double[] x, double[] y)
public CubicSpline(int n)
Interpolate public double interpolate(double xx1)
public double[] interpolate_for_y_and_dydx(double xx1)
public static double interpolate(double xx1, double[] x, double[] y, double[] deriv)
Override natural spline public void setDerivLimits(double ydd0, double yddn)
Reset natural spline public void setDerivLimits()
Calculate second derivatives public void calcDeriv()
Set second derivatives public void setDeriv(public double[] deriv)
Get second derivatives public double[] getDeriv()
Set Data public void resetData(double[] x, double[] y)
Array public static CubicSpline[] oneDarray(int n, int m)
New CubicSpline public static CubicSpline zero(int n)
Rounding Error Options public static void noRoundingErrorCheck()
public static void potentialRoundingError(double potentialRoundingError)


CONSTRUCTORS

 STANDARD CONSTRUCTOR
public CubicSpline(double[] x, double[] y)
Usage:                      CubicSpline aa = new CubicSpline(x, y);
Creates an instance of the CubicSpline object with its internal data arrays initialised to copies of the values in the x and y arrays where y is the tabulated function, y = f(x). The variables x and y are one dimensional arrays of type double. This is the standard constructor.

CONSTRUCTOR WITH ZERO VALUE DATA ARRAYS
public CubicSpline(int n)
Usage:                      CubicSpline aa = new CubicSpline(n);
Creates an instance of the CubicSpline object that will hold an array of data points of length n and with all data arrays initialised to zero. This constructor is required by the related class BiCubicSpline.


METHODS

INTERPOLATION
Instant Methods
Interpolate for the y value only
public double interpolate(double xx1)
Usage:                      y1 = aa.interpolate(xx1);
Returns the interpolated value of y, y1, for a given value of xx1, using the y = f(x) data stored in aa by the constructor. This method may be called as often as required. The second derivatives needed for the interpolation are calculated and stored on instantiation so that they need not be recalculated on each call to this method. This method throws an IllegalArgumentException if xx1 is outside the range of the values of x[] supplied to the constructor or if two x values within the y = f(x) data set are identical.

Interpolate for the y value and for the first derivative, dy/dx
public double[] interpolate_for_y_and_dydx(double xx1)
Usage:                      yy = aa.interpolate_for_y_and_dydx(xx1);
Returns the interpolated value of y in the first element of the double array, yy, i.e. in yy[0], and of the first derivative, dy/dx, in the second element of the double array, yy, i.e. in yy[1], for a given value of xx1, using the y = f(x) data stored in aa by the constructor. This method may be called as often as required. The second derivatives needed for the interpolation are calculated and stored on instantiation so that they need not be recalculated on each call to this method. This method throws an IllegalArgumentException if xx1 is outside the range of the values of x[] supplied to the constructor or if two x values within the y = f(x) data set are identical.

Static Method
Interpolate for the y value only
public static double interpolate(double xx1, double[] x, double[] y, double[] deriv)
Usage:                      y1 = CubicSpline.interpolate(xx1, x, y, deriv);
Returns the interpolated value of y, y1, for a given value of xx1, using the y = f(x) data and its second derivatives (deriv). This static version of interpolate does not use the internal arrays stored in an instance of CubicSpline. The second derivatives have to be calculated and supplied by the user. This method throws an IllegalArgumentException if xx1 is outside the range of the values of x[] data supplied, if arrrays x, y and array are of different lengths or if two x values within the y = f(x) data set are identical.


OVERRIDING THE NATURAL SPLINE OPTION
public setDerivLimits(double ydd0, double yddn)
Usage:                      aa.setDerivLimits(ydd0, yddn);
The default option in this class is to perfom a natural spline interpolation, i.e. set the second derivatives of y with respect to x at the first and last data points to zero. This method allows the user to override the natural spline option by setting the limiting first derivatives to the user supplied first derivatives ydd0 and yddn respectively.


RESETTING THE NATURAL SPLINE OPTION
public setDerivLimits()
Usage:                      aa.setDerivLimits();
The default option in this class is to perfom a natural spline interpolation, i.e. set the second derivatives of y with respect to x at the first and last data points to zero. This method allows users to reset the natural spline option if they have previously overridden it and now wish to reurn to it.


CREATE AN INTERNAL ARRAY OF SECOND DERIVATIVES
public void calcDeriv()
Usage:                      aa.calcDeriv();
Calculates the array of second derivatives for the data set, y = f(x). This method is NOT needed. It is retained for backward compatibility purposes. Old users who did need it may delete calls to this method. The Constructor now automatically calls calcDeriv() and stores the second derivatives needed by the interpolation methods.


SET THE INTERNAL ARRAY OF SECOND DERIVATIVES
public void setDeriv(public double[] deriv)
Usage:                      aa.setDeriv(deriv);
Sets the array of second derivatives for the data set, y = f(x) to the argument, deriv. It overides the internal calculation of the second derivatives. This method is used by the related class BiCubicSpline.


GET THE INTERNAL ARRAY OF SECOND DERIVATIVES
public double[] getDeriv()
Usage:                      yd = aa.getDeriv();
Returns the internal array of second derivatives.


RESET THE DATA ARRAYS
public void resetData(double[] x, double[] y)
Usage:                      aa.resetData(xx, yy);
Resets the internal data arrays to copies of the values in the xx and yy arrays. This method is required by the related class, BiCubicSpline.


ONE DIMESIONAL ARRAY OF CUBIC SPLINE INSTANCES
public static CubicSpline[] oneDarray(int n)
Usage:                      CubicSpline[] cc = CubicSpline.oneDarray(n);
Creates an array, of length n, of CubicSpline instances with all data array values set at zero. This method is used by the related class BiCubicSpline.


CREATE A NEW INSTANCE OF CUBIC SPLINE
public static CubicSpline zero()
Usage:                      CubicSpline cc = CubicSpline.zero();
Creates and returns a new instance of a cubic spline object with all data array values set at zero. This method is used by the related class BiCubicSpline.


ROUNDING ERROR OPTIONS
public static void noRoundingErrorCheck()
Usage:                      CubicSpline.noRoundingErrorCheck();
Seveveral applications that call CubicSpline, e.g. plotting programs, may calculate an array of points to be fed to an instance of cubic spline that should lie between the limits initially supplied to the instance but which, due to rounding errors in the calculation of the array, may have extreme values that lie outside the limits by the an amount equal to the rounding error, e.g. an array that should lie between limits of 0 and 4 may run from 0 to 4.0000000000000003. The default option of the CubicSpline class is to check for such violations of the order of a rounding error and round the extreme value to the limit thus preventing an out of range exception being thrown. This method allows this default option to be ignored so that an out of range exception is thrown if any value lies outside he range of the limis no matter how small the violation is.

public static void potentialRoundingError(double potentialRoundingError)
Usage:                      CubicSpline.potentialRoundingError(potentialRoundingError);
Seveveral applications that call CubicSpline, e.g. plotting programs, may calculate an array of points to be fed to an instance of cubic spline that should lie between the limits initially supplied to the instance but which, due to rounding errors in the calculation of the array, may have extreme values that lie outside the limits by the an amount equal to the rounding error, e.g. an array that should lie between limits of 0 and 4 may run from 0 to 4.0000000000000003. The default option of the CubicSpline class is to check for such violations of the order of a rounding error and round the extreme value to the limit thus preventing an out of range exception being thrown. The default calculculation of the potential rounding error is the multiplication of 5x10-15 by 10 raised to the exponent of the value lying outside the limits. This method allows the value of 5x10-15 to be reset to the user's choice, potentialRoundingError.


EXAMPLE PROGAM

 An example program may be found on CubicSplineExample.java


OTHER CLASSES USED BY THIS CLASS

 This class uses the following classes in this library:

This page was prepared by Dr Michael Thomas Flanagan