Class BSpline

All Implemented Interfaces:
DoubleUnaryOperator, RealValuedDomainOps, RealValuedFunctOps, RealValuedFunctVAOps, VADomainOps

public class BSpline extends RealValuedFunction
Class implementing B-splines.

This class supports both periodic and non-periodic B-splines. Periodic B-splines can be used to approximate period functions. Additional control points and knots are added for periodic B-splines. (see below).

A B-spline consists of

  • an increasing finite sequence of real numbers called "knots": u0 ≤ u1 ≤ ... ≤ um
  • a set of basis functions.
  • a set of control points (just numbers for this class) denoted as P0, P1, … Pn.
  • a degree—normally denoted as p. The degree of a B-spline must satisfy p = m - n - 1.

The basis functions are defined as follows: $$\begin{eqnarray} N_{i,0}(u) & = & \left\{\begin{array}{ll} 1 & \mbox {if $u_i \le u < u_{i+1}$} \\ 0 & \mbox{if $u < u_i$ or $u_{i+1} \le u$} \end{array}\right . \\ N_{i,p}(u) & = & \mbox{$N_{i,p-1}(u)\frac{u-u_i}{u_{i+p}-u_i} + N_{i+1,p-1}(u)\frac{u_{i+p+1}-u}{u_{i+p+1}-u_{i+1}}$ for $p > 0$} \end{eqnarray}$$

  • Ni,0(u) = 1 if ui ≤ u < ui+1.
  • Ni,0(u) = 0 if u < ui or ui+1 ≤ u.
  • Ni,p(u) = Ni,p-1(u) (u-ui) ⁄ (ui+p-ui) + Ni+1,p-1(u) (ui+p+1-u) ⁄ (ui+p+1-ui+1) for p > 0.
The value of the function $f$ defined by this spline at a point u is defined by $$f(u) = \sum^n_{i=0} P_iN_{i,p}$$ with a domain [up, um-p] for non-periodic splines and (-∞, ∞) for periodic splines (for a periodic spline, the value of u will be shifted by an appropriate multiple of the period so as to be in the interval [up, um-p], at at the end points of this interval, the values will match, as will their derivatives.

The documentation for the constructor BSpline(int,double[],double[],boolean) describes how periodic and non-periodic B-splines are created. A couple of constructors use a simplified set of arguments. These use a BSpline.Mode argument to specify a menu of options for setting up the knots array and for determining if the spline is periodic.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    Modes for creating a B-spline from a set of data points.

    Nested classes/interfaces inherited from class org.bzdev.math.RealValuedFunctionVA

    RealValuedFunctionVA.Linear
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    Default cutoff for using a straightforward recursive implementation of the method M.

    Fields inherited from class org.bzdev.math.RealValuedFunction

    xFunction
  • Constructor Summary

    Constructors
    Constructor
    Description
    BSpline(double[] knots, double[] cpoints)
    Constructor for open B-splines.
    BSpline(int degree, double[] knots, boolean periodic, double[] x, double[] y)
    Constructor specifying a B-spline's degree, knots, and fitting the spline to a set of data points.
    BSpline(int degree, double[] knots, boolean periodic, double[] x, double[] y, double sigma)
    Constructor specifying a B-spline's degree, knots, and fitting the spline to a set of data points, all with the same error.
    BSpline(int degree, double[] knots, boolean periodic, double[] x, double[] y, double[] sigma)
    Constructor specifying a B-spline's degree, knots, and fitting the spline to a set of data points with errors.
    BSpline(int degree, double[] knots, double[] cpoints, boolean periodic)
    Constructor.
    BSpline(int degree, int n, BSpline.Mode mode, double[] x, double[] y)
    Constructor specifying a B-spline's degree, number of control points, mode, and a set of Y values for given X values.
    BSpline(int degree, int n, BSpline.Mode mode, double[] x, double[] y, double sigma)
    Constructor specifying a B-spline's degree, number of control points, mode, and a set of Y values for given X values, with a specified error for the Y values.
    BSpline(int degree, int n, BSpline.Mode mode, double[] x, double[] y, double[] sigma)
    Constructor specifying a B-spline's degree, number of control points, mode, and a set of Y values and their standard deviations for given X values.
  • Method Summary

    Modifier and Type
    Method
    Description
    static double[]
    createKnots(int degree, int n, BSpline.Mode mode, double[] x)
    Create a knot array for a B-Spline.
    double
    derivAt(double u)
    Evaluate the function's first derivative.
    double[]
    Get the control points.
    double[]
    getControlPoints(double[] array)
    Get the control points, storing them in a pre-allocated array.
    int
    Get the degree if this B-spline.
    double
    Get the maximum value in the domain of the function.
    double
    Get the minimum value in the domain of the function.
    Get the least squares fit, if any, used to initialize this BSpline.
    int
    Get the number of control points.
    double
    Get the period.
    double
    Get the ending value for a period.
    double
    Get the starting value for a period.
    boolean
    Determine if the spline is a periodic spline.
    final double
    N(int i, int p, double u)
    Compute the value of a B-Spline's basis function.
    double
    secondDerivAt(double u)
    Evaluate the function's second derivative.
    protected void
    setControlPoints(double[] cpoints)
    Set the control points for this BSpline.
    static void
    setCutoff(int value)
    Set the cutoff for the use of the naive basis-function computation.
    double
    valueAt(double u)
    Call the function.

    Methods inherited from class org.bzdev.math.RealValuedFunctionVA

    jacobian, jacobian, maxArgLength, minArgLength

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface org.bzdev.math.RealValuedFunctOps

    andThen, andThen, applyAsDouble, compose, compose, maxArgLength, minArgLength
  • Field Details

    • CUTOFF

      public static final int CUTOFF
      Default cutoff for using a straightforward recursive implementation of the method M. When the argument to N providing the degree of a basis function is below this value, the straightforward implementation is used. Otherwise intermediate results are cached and reused.
      See Also:
  • Constructor Details

    • BSpline

      public BSpline(double[] knots, double[] cpoints) throws IllegalArgumentException
      Constructor for open B-splines. A full description is provided by the constructor BSpline(int,double[],double[],boolean). The degree of the B-spline is equal to knots.length - cpoints.length - 1.
      Parameters:
      knots - the knots for the B-spline to be constructed
      cpoints - the control points for the B-spline to be constructed
      Throws:
      IllegalArgumentException
      See Also:
    • BSpline

      public BSpline(int degree, double[] knots, double[] cpoints, boolean periodic) throws IllegalArgumentException
      Constructor. There are two cases depending on whether the B-spline will be periodic or non-periodic. For the non-periodic case, if m is the length of the knots array, n is the number of control points, and p is the degree if the B-spline, then the following constraint must be satisfied:
           n + p + 1 = m
      or
           m - n - 1 = p.
      or
           m - p - 1 = n.
      The degree matches the highest possible degree of the polynomial representation of the basis functions (some authors start the sequence at 1 instead of 0, in which case the degree the smallest integer larger than the degree of the polynomials). The domain of the spline is [us, ue]. where us=knots[degree] and ue=knots[knots.length-p-1].

      For the periodic case, the values of the spline over a range [us,ue] repeat indefinitely in either direction, and the knots array's initial and ending components will be us and ue respectively. As a result, the period is ue-us. For a periodic spline whose degree is p, the length of the control-points array will either be one less than the length of the knots array, or (p-1) less than the length of the knots array. The constructor will augment these arrays as follows:

      • p components will be inserted before the initial component of the knots array, and p components will be inserted after the last component of the knots array. The p components before the last original entry will be copied to the start of the array in the same order as in the original array, with values decreased by the period. The first p components past the initial component of the original array array will be copied to the end of the array, with values increased by the period.
      • When the control-points array's length is one less than the length of the knots array, p components will be inserted before the initial component of the control-points array. The last p components of the original array will be copied to the start of the augmented array in the same order as in the original array.
      Note: Copying of control points must be considered when fitting a periodic spline to a function or a set of data points.
      Parameters:
      degree - a non-negative integer giving the degree of the B-spline to be constructed
      knots - the knots for the B-spline to be constructed
      cpoints - the control points for the B-spline to be constructed
      periodic - true if the spline is periodic; false if it is open.
      Throws:
      IllegalArgumentException
    • BSpline

      public BSpline(int degree, double[] knots, boolean periodic, double[] x, double[] y)
      Constructor specifying a B-spline's degree, knots, and fitting the spline to a set of data points. The use of knots is the same as that for the constructor BSpline(int,double[],double[],boolean).
      Parameters:
      degree - the degree of the B-spline that will be created
      knots - the knots the B-spline uses
      periodic - true if the B-spline is periodic, false otherwise
      x - values in the domain of the spline
      y - values in the range of the spline
    • BSpline

      public BSpline(int degree, double[] knots, boolean periodic, double[] x, double[] y, double sigma)
      Constructor specifying a B-spline's degree, knots, and fitting the spline to a set of data points, all with the same error. The use of knots is the same as that for the constructor BSpline(int,double[],double[],boolean).
      Parameters:
      degree - the degree of the B-spline that will be created
      knots - the knots the B-spline uses
      periodic - true if the B-spline is periodic, false otherwise
      x - values in the domain of the spline
      y - values in the range of the spline
      sigma - the standard deviation of the 'y' values for the least-squares fit.
    • BSpline

      public BSpline(int degree, double[] knots, boolean periodic, double[] x, double[] y, double[] sigma)
      Constructor specifying a B-spline's degree, knots, and fitting the spline to a set of data points with errors. The use of knots is the same as that for the constructor BSpline(int,double[],double[],boolean).
      Parameters:
      degree - the degree of the B-spline that will be created
      knots - the knots the B-spline uses
      periodic - true if the B-spline is periodic, false otherwise
      x - values in the domain of the spline
      y - values in the range of the spline
      sigma - the standard deviations for the values provided by the argument y
    • BSpline

      public BSpline(int degree, int n, BSpline.Mode mode, double[] x, double[] y)
      Constructor specifying a B-spline's degree, number of control points, mode, and a set of Y values for given X values. The number of X,Y data points must be larger than the number of control points.
      Parameters:
      degree - the degree of the B-spline that will be created
      n - the number of control points
      mode - the mode for the B-spline (either BSpline.Mode.UNCLAMPED, BSpline.Mode.CLAMPED, BSpline.Mode.CLAMPED_LEFT, BSpline.Mode.CLAMPED_RIGHT, or BSpline.Mode.PERIODIC); null for the default (BSplineMode.UNCLAMPED).
      x - values in the domain of the spline
      y - values in the range of the spline
    • BSpline

      public BSpline(int degree, int n, BSpline.Mode mode, double[] x, double[] y, double sigma)
      Constructor specifying a B-spline's degree, number of control points, mode, and a set of Y values for given X values, with a specified error for the Y values. The number of X,Y data points must be larger than the number of control points.
      Parameters:
      degree - the degree of the B-spline that will be created
      n - the number of control points
      mode - the mode for the B-spline (either BSpline.Mode.UNCLAMPED, BSpline.Mode.CLAMPED, BSpline.Mode.CLAMPED_LEFT, BSpline.Mode.CLAMPED_RIGHT, or BSpline.Mode.PERIODIC); null for the default (BSplineMode.UNCLAMPED).
      x - values in the domain of the spline
      y - values in the range of the spline
      sigma - the standard deviation for the Y values
    • BSpline

      public BSpline(int degree, int n, BSpline.Mode mode, double[] x, double[] y, double[] sigma)
      Constructor specifying a B-spline's degree, number of control points, mode, and a set of Y values and their standard deviations for given X values. The number of X,Y data points must be larger than the number of control points.
      Parameters:
      degree - the degree of the B-spline that will be created
      n - the number of control points
      mode - the mode for the B-spline (either BSpline.Mode.UNCLAMPED, BSpline.Mode.CLAMPED, BSpline.Mode.CLAMPED_LEFT, BSpline.Mode.CLAMPED_RIGHT, or BSpline.Mode.PERIODIC); null for the default (BSplineMode.UNCLAMPED)
      x - values in the domain of the spline
      y - values in the range of the spline
      sigma - the standard deviations for the values provided by the argument y
  • Method Details

    • setControlPoints

      protected void setControlPoints(double[] cpoints) throws IllegalArgumentException
      Set the control points for this BSpline.
      Parameters:
      cpoints - an array containing the control points,
      Throws:
      IllegalArgumentException
    • getControlPoints

      public double[] getControlPoints()
      Get the control points.
      Returns:
      the control-point array
    • getControlPoints

      public double[] getControlPoints(double[] array)
      Get the control points, storing them in a pre-allocated array.
      Parameters:
      array - the array that will contain the control poions.
      Returns:
      the control-point array (the first argument)
    • getNumberOfControlPoints

      public int getNumberOfControlPoints()
      Get the number of control points.
      Returns:
      the number of control points
    • isPeriodic

      public boolean isPeriodic()
      Determine if the spline is a periodic spline.
      Returns:
      true if the spline is periodic; false otherwise.
    • getPeriodStart

      public double getPeriodStart()
      Get the starting value for a period. A periodic B-spline explicitly handles a range of values of the parameters. For other values of the parameter, the parameter is shifted by the period until it falls within this range. For a non-periodic B-spline, the domain minimum is returned.
      Returns:
      the starting value for a period if the spline is periodic; otherwise the domain minimum
    • getPeriodEnd

      public double getPeriodEnd()
      Get the ending value for a period. A periodic B-spline explicitly handles a range of values of the parameters. For other values of the parameter, the parameter is shifted by the period until it falls within this range. For a non-periodic B-spline, the domain maximum is returned.
      Returns:
      the ending value for a period if the spline is periodic; otherwise the domain maximum
    • getPeriod

      public double getPeriod()
      Get the period. A periodic B-spline explicitly handles a range of values of the parameters. For other values of the parameter, the parameter is shifted by the period until it falls within this range. For a periodic B-spline, the period is numerically equal to getPeriodEnd()-getPeriodStart().
      Returns:
      the period for a periodic spline; 0.0 if the spline is not periodic
    • getDegree

      public int getDegree()
      Get the degree if this B-spline. The smallest degree is zero (some authors use 1, in which case the degree will be larger by 1 than the value returned by this method).
      Returns:
      this B-spline's degree.
    • getLSF

      public LeastSquaresFit getLSF()
      Get the least squares fit, if any, used to initialize this BSpline. This method will always return null if it is called two or more times. It is intended for use by subclasses of LeastSquaresFit or other classes that need information about a least squares fit when the fit is created.
      Returns:
      the least squares fit; null if there is none.
    • createKnots

      public static double[] createKnots(int degree, int n, BSpline.Mode mode, double[] x)
      Create a knot array for a B-Spline.
      Parameters:
      degree - the degree of the B-Spline
      n - the number of control points for the B-Spline
      mode - the mode for the B-spline (either BSpline.Mode.UNCLAMPED, BSpline.Mode.CLAMPED, BSpline.Mode.CLAMPED_LEFT, BSpline.Mode.CLAMPED_RIGHT, or BSpline.Mode.PERIODIC); null for the default (BSpline.Mode.UNCLAMPED)
      x - the x values used to create the B-Spline
      Returns:
      the knot array
    • setCutoff

      public static void setCutoff(int value)
      Set the cutoff for the use of the naive basis-function computation. When the argument to N providing the degree of a basis function is below this value, the straightforward implementation is used. Otherwise intermediate results are cached and reused.
      Parameters:
      value - the cutoff, which must not be negative
    • N

      public final double N(int i, int p, double u)
      Compute the value of a B-Spline's basis function.
      Parameters:
      i - a integer representing a knot span with a value equal to the index of the knot at the start of a span
      p - the degree of the basis function
      u - the value of the B-spline's parameter
      Returns:
      the value of the basis function at point u
    • getDomainMin

      public double getDomainMin()
      Description copied from class: RealValuedFunction
      Get the minimum value in the domain of the function.
      Specified by:
      getDomainMin in interface RealValuedDomainOps
      Overrides:
      getDomainMin in class RealValuedFunction
      Returns:
      the minimum value
    • getDomainMax

      public double getDomainMax()
      Description copied from interface: RealValuedDomainOps
      Get the maximum value in the domain of the function.
      Specified by:
      getDomainMax in interface RealValuedDomainOps
      Overrides:
      getDomainMax in class RealValuedFunction
      Returns:
      the maximum value
    • valueAt

      public double valueAt(double u) throws IllegalArgumentException
      Description copied from class: RealValuedFunction
      Call the function.
      Specified by:
      valueAt in interface RealValuedFunctOps
      Overrides:
      valueAt in class RealValuedFunction
      Parameters:
      u - the function's argument
      Returns:
      the value of the function for the given argument
      Throws:
      IllegalArgumentException - the function's argument was out of range
    • derivAt

      public double derivAt(double u) throws IllegalArgumentException
      Description copied from class: RealValuedFunction
      Evaluate the function's first derivative.
      Overrides:
      derivAt in class RealValuedFunction
      Parameters:
      u - the function's argument
      Returns:
      the value of the function for the given argument
      Throws:
      IllegalArgumentException - the function's argument was out of range
    • secondDerivAt

      public double secondDerivAt(double u)
      Description copied from class: RealValuedFunction
      Evaluate the function's second derivative.
      Overrides:
      secondDerivAt in class RealValuedFunction
      Parameters:
      u - the function's argument
      Returns:
      the value of the function for the given argument