Package edu.cnu.mdi.splot.fit

Class CubicSpline

java.lang.Object
edu.cnu.mdi.splot.fit.CubicSpline
All Implemented Interfaces:
Evaluator
public class CubicSpline extends Object implements Evaluator
Natural cubic spline interpolator over tabulated data (x[i], y[i]).

This class precomputes the natural cubic spline second derivatives and can:

Spline details

The spline is "natural": the second derivative is forced to be zero at the endpoints. Between consecutive knots x[i] <= x <= x[i+1], the interpolant is a cubic polynomial chosen so that y, y' and y'' are continuous across knots.

Requirements

  • x[] and y[] must be non-null, same length, and length >= 2.
  • x[] must be strictly increasing (no duplicates).

Out-of-range evaluation

If x is outside [x[0], x[n-1]], this implementation clamps to the nearest endpoint (returns y[0] or y[n-1]).

  • Constructor Summary

    Constructors
    Constructor
    Description
    CubicSpline(double[] x, double[] y)
    Create a natural cubic spline through the provided tabulated data.

  • Method Summary

    Modifier and Type
    Method
    Description
    CubicSpline
    derivative()
    Obtain a cubic spline that approximates the derivative of this spline by numeric differentiation at the knots, then spline-interpolating those derivative samples.
    double[]
    findRoots(double xmin, double xmax)
    Find roots of the spline in a given range.
    Point2D.Double[]
    findXValsOfMaxima(double xmin, double xmax)
    Find the (x, y) values of the maxima of the interpolated function in a given range.
    boolean
    isValid()
    Whether the spline is properly initialized.
    int
    size()
    Number of spline knots.
    double
    value(double x)
    Evaluate the natural cubic spline interpolant.
    double
    xmax()
    Maximum x value of the spline domain.
    double
    xmin()
    Minimum x value of the spline domain.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • CubicSpline

      public CubicSpline(double[] x, double[] y)
      Create a natural cubic spline through the provided tabulated data.
      Parameters:
      x - strictly increasing x-values (knots)
      y - y-values at the knots
      Throws:
      IllegalArgumentException - if inputs are invalid (null, length mismatch, length < 2, non-increasing x)

  • Method Details

    • size

      public int size()
      Number of spline knots.
      Returns:
      number of x points defining the spline

    • xmin

      public double xmin()
      Minimum x value of the spline domain.
      Returns:
      minimum x, or NaN if undefined

    • xmax

      public double xmax()
      Maximum x value of the spline domain.
      Returns:
      maximum x, or NaN if undefined

    • isValid

      public boolean isValid()
      Whether the spline is properly initialized.
      Returns:
      true if x/y arrays are non-null and have length ≥ 2

    • value

      public double value(double x)
      Evaluate the natural cubic spline interpolant.

      The interval containing x is found with a binary search, then the standard cubic-spline interpolation formula is used.

      Specified by:
      value in interface Evaluator
      Parameters:
      x - query x-value
      Returns:
      interpolated y-value; clamped to endpoints if x is outside the knot range

    • derivative

      public CubicSpline derivative()
      Obtain a cubic spline that approximates the derivative of this spline by numeric differentiation at the knots, then spline-interpolating those derivative samples.

      The derivatives are estimated using:

      • Centered differences for interior points
      • One-sided differences for the endpoints
      This is robust and simple. If you need an analytic derivative of the spline itself, you could compute it directly from the spline coefficients; this method instead builds a new spline based on sampled slopes at knots.
      Returns:
      a new CubicSpline approximating dy/dx

    • findRoots

      public double[] findRoots(double xmin, double xmax)
      Find roots of the spline in a given range.

      The method scans the range with a fixed number of samples to find sign changes, then applies Brent's method to refine each root. The results are deduplicated and returned sorted.

      Parameters:
      xmin - minimum x value of the search range
      xmax - maximum x value of the search range
      Returns:
      array of roots in the range, or null if none found
      Throws:
      IllegalArgumentException - if xmax <= xmin

    • findXValsOfMaxima

      public Point2D.Double[] findXValsOfMaxima(double xmin, double xmax)
      Find the (x, y) values of the maxima of the interpolated function in a given range.

      Implementation strategy:

      1. Compute a spline approximation to the first derivative.
      2. Find its roots (critical points) in [xmin, xmax].
      3. Compute a spline approximation to the second derivative.
      4. Keep only critical points where the second derivative is negative (local maxima).
      5. Return the corresponding (x, f(x)) pairs, sorted by descending y if there is more than one.
      Parameters:
      xmin - the min value of the range
      xmax - the max value of the range
      Returns:
      an array of maxima points, or null if none are found