maspack.interpolation

Class CubicHermiteSpline1d

java.lang.Object

maspack.function.Diff1Function1x1Base

maspack.interpolation.CubicHermiteSpline1d

All Implemented Interfaces:

java.lang.Cloneable, java.lang.Iterable<CubicHermiteSpline1d.Knot>, Diff1Function1x1, Diff1FunctionNx1, Function1x1, FunctionNx1, Clonable, Scannable

public class CubicHermiteSpline1d
extends Diff1Function1x1Base
implements java.lang.Iterable<CubicHermiteSpline1d.Knot>

Implements one dimensional cubic Hermite spline interpolation in the x/y plane. The spline is described by a series of segments, each specifying an interval of x within which y is interpolated cubicly. The spline is defined by a sequence of knots delimiting the boundaries of these segments, with each knot specifying y and its derivative for a given value of x.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CubicHermiteSpline1d.Knot Describes a single knot for a specific value of x.

Constructor Summary

Constructors

Constructor and Description
CubicHermiteSpline1d() Creates a empty spline
CubicHermiteSpline1d(CubicHermiteSpline1d spline) Creates a spline from a copy of an existing one.
CubicHermiteSpline1d(double[] values) Creates a spline from data containing the x, y and y derivative values for each knot point.
CubicHermiteSpline1d(double[] x, double[] y, double[] dy) Creates a spline from data containing the x, y and y derivative values for each knot point.

Method Summary

Modifier and Type	Method and Description
CubicHermiteSpline1d.Knot	addKnot(double x, double y, double dy) Adds another knot point to this cubic hermite spline, consisting of an x coordinate, along with y and y derivative values.
void	addKnot(int idx, CubicHermiteSpline1d.Knot knot)
void	clearKnots()
CubicHermiteSpline1d	clone()
CubicHermiteSpline1d	copy() Creates a copy of this spline.
boolean	equals(CubicHermiteSpline1d curve)
double	eval(double x) Evaluates the function at a prescribed input value.
double	eval(DoubleHolder deriv, double x) Evaluates both the value and first derivative of this function at a specified input value.
double	evalDeriv(double x) Evaluates first derivative of this function at a specified input value.
double	evalDy(double x) Evaluates the y derivative value at a specific x value.
double	evalDy(double x, double alpha) Evaluates the y derivative of the function composed of this spline plus a linear term alpha x at a specific x value.
double	evalDy2(double x) Evaluates the second y derivative value at a specific x value.
double	evalDy3(double x) Evaluates the third y derivative value spline at a specific x value.
double	evalY(double x) Evaluates the y value for this spline at a specific x value.
double	evalY(double x, double alpha) Evaluates the y value of the function composed of this spline plus a linear term alpha x at a specific x value.
CubicHermiteSpline1d.Knot	getFirstKnot()
CubicHermiteSpline1d.Knot	getKnot(int idx)
CubicHermiteSpline1d.Knot	getLastKnot()
CubicHermiteSpline1d.Knot	getNextKnot(double x) Find the knot immediately following x.
CubicHermiteSpline1d.Knot	getPreviousKnot(double x) Find the knot immediately preceeding x.
boolean	isInvertible() Queries whether this spline is invertible.
boolean	isWritable() Returns true if this component should in fact be written to secondary storage.
java.util.Iterator<CubicHermiteSpline1d.Knot>	iterator()
int	numKnots()
boolean	removeKnot(CubicHermiteSpline1d.Knot knot)
void	scaleX(double s) Scales the x values of this spline.
void	scaleY(double s) Scales the y values of this spline.
void	scan(ReaderTokenizer rtok, java.lang.Object ref) Scans this spline from a ReaderTokenizer.
void	set(CubicHermiteSpline1d spline) Sets this spline to be a copy of another spline.
void	setNatural(double[] x, double[] y) Sets this spline to a natural cubic spline for a set of knot points whose x and y positions are given.
void	setNatural(double[] x, double[] y, double ddy0, double ddyL) Sets this spline to a natural cubic spline for a set of knot points whose x and y positions are given.
double	solveX(double y) Solves for the x value given a specific y value.
double	solveX(double y, double alpha) Solves for the x value given a specific y value of the function defined by this spline plus a linear term alpha x.
void	updateCoefficients()
void	updateCoefficients(CubicHermiteSpline1d.Knot knot)
void	write(java.io.PrintWriter pw, NumberFormat fmt, java.lang.Object ref) Writes a text description of this spline to a PrintWriter.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Methods inherited from interface maspack.function.Diff1Function1x1

eval, evalDeriv

Methods inherited from interface maspack.function.Function1x1

eval, inputSize

Constructor Detail

CubicHermiteSpline1d

public CubicHermiteSpline1d()

Creates a empty spline

CubicHermiteSpline1d

public CubicHermiteSpline1d(double[] x,
                            double[] y,
                            double[] dy)

Creates a spline from data containing the x, y and y derivative values for each knot point.

Parameters:

x - x values. These should be in ascending order. If they are not, they will be sorted into ascending order (internally) with the y and derivative values reordered appropriately. All x values should also be unique.

y - y values

dy - y derivative values

CubicHermiteSpline1d

public CubicHermiteSpline1d(double[] values)

Creates a spline from data containing the x, y and y derivative values for each knot point. This is specified using a single array with 3 n entries, where n is the number of knots. The entries should gave the form

  x0 y0 dy0 x1 y1 dy1 x2 y2 dy2 ...
 

where xi, yi, and dyi are the x, y and derivative values for the i-th knot.

The x values should be in ascending order. If they are not, they will be sorted into ascending order (internally) with the y and derivative values reordered appropriately. All x values should also be unique.

Parameters:

values - x, y, and derivative values for the knots.

CubicHermiteSpline1d

public CubicHermiteSpline1d(CubicHermiteSpline1d spline)

Creates a spline from a copy of an existing one.

Parameters:

spline - spline to copy

Method Detail

setNatural

public void setNatural(double[] x,
                       double[] y)

Sets this spline to a natural cubic spline for a set of knot points whose x and y positions are given. This is a wrapper for setNatural(double[],double[],double,double) with ddy0 and ddyL both set to 0.

Parameters:

x - knot point x values

y - knot point y values

setNatural

public void setNatural(double[] x,
                       double[] y,
                       double ddy0,
                       double ddyL)

Sets this spline to a natural cubic spline for a set of knot points whose x and y positions are given. The implementation is based on a some notes published by James Keesling, in people.clas.ufl.edu/kees/files/CubicSplines.pdf

Parameters:

x - knot point x values

y - knot point y values

ddy0 - desired second derivative at the first knot

ddyL - desired second derivative at the last knot

addKnot

public CubicHermiteSpline1d.Knot addKnot(double x,
                                         double y,
                                         double dy)

Adds another knot point to this cubic hermite spline, consisting of an x coordinate, along with y and y derivative values. The value of x must be greater than the x value of any previous knot point.

addKnot

public void addKnot(int idx,
                    CubicHermiteSpline1d.Knot knot)

removeKnot

public boolean removeKnot(CubicHermiteSpline1d.Knot knot)

clearKnots

public void clearKnots()

getPreviousKnot

public CubicHermiteSpline1d.Knot getPreviousKnot(double x)

Find the knot immediately preceeding x. Specifically, find the nearest knot for which knot.x0 <= x. If no such knot exists, null is returned.

Parameters:

x - value for which previous knot is sought

getNextKnot

public CubicHermiteSpline1d.Knot getNextKnot(double x)

Find the knot immediately following x. Specifically, find the nearest knot for which knot.x0 > x. If no such knot exists, null is returned.

Parameters:

x - value for which next knot is sought

evalY

public double evalY(double x)

Evaluates the y value for this spline at a specific x value. Values which are outside the specified knot range are extrapolated based on y and dy values at the end point knots. An empty spline evaluates to 0.

Parameters:

x - value at which y should be evaluated

evalY

public double evalY(double x,
                    double alpha)

Evaluates the y value of the function composed of this spline plus a linear term alpha x at a specific x value. Values which are outside the specified knot range are extrapolated based on y and dy values at the end point knots. An empty spline evaluates to 0.

Parameters:

x - value at which y should be evaluated

alpha - slope of the additional linear term

evalDy

public double evalDy(double x)

Evaluates the y derivative value at a specific x value. Values which are outside the specified knot range are extrapolated based on y and dy values at the end point knots. An empty spline evaluates to 0.

Parameters:

x - value at which the y derivative should be evaluated

evalDy

public double evalDy(double x,
                     double alpha)

Evaluates the y derivative of the function composed of this spline plus a linear term alpha x at a specific x value. Values which are outside the specified knot range are extrapolated based on y and dy values at the end point knots. An empty spline evaluates to 0.

Parameters:

x - value at which the y derivative should be evaluated

alpha - slope of the additional linear term

evalDy2

public double evalDy2(double x)

Evaluates the second y derivative value at a specific x value. Values which are outside the specified knot range are extrapolated as 0.

Parameters:

x - value at which the second y derivative should be evaluated

evalDy3

public double evalDy3(double x)

Evaluates the third y derivative value spline at a specific x value. Values which are outside the specified knot range are extrapolated as 0.

Parameters:

x - value at which the second y derivative should be evaluated

eval

public double eval(double x)

Description copied from class: Diff1Function1x1Base

Evaluates the function at a prescribed input value.

Specified by:

eval in interface Function1x1

Specified by:

eval in class Diff1Function1x1Base

Parameters:

x - input value

Returns:

function output value

eval

public double eval(DoubleHolder deriv,
                   double x)

Description copied from class: Diff1Function1x1Base

Evaluates both the value and first derivative of this function at a specified input value.

Specified by:

eval in interface Diff1Function1x1

Specified by:

eval in class Diff1Function1x1Base

Parameters:

deriv - if non-null, returns the derivative value

x - input value

Returns:

function value

evalDeriv

public double evalDeriv(double x)

Description copied from interface: Diff1Function1x1

Evaluates first derivative of this function at a specified input value.

Specified by:

evalDeriv in interface Diff1Function1x1

Parameters:

x - input value

Returns:

derivative value

scan

public void scan(ReaderTokenizer rtok,
                 java.lang.Object ref)
          throws java.io.IOException

Scans this spline from a ReaderTokenizer. The expected format consists of an openning square bracket, followed by 3 n numeric values giving the x, y amd y derivative values for each of the n knots, and terminated with a closing square bracket. Whitespace characters are ignored. For example,

  [  0.0 4.0 1.0  2.0 5.0 -1.0 ]
 

describes a spline with two knots, with the first at x = 0.0 and having y and y derivative values of 4.0 and 1.0, and the second at x = 2.0 with y and y derivative values of 5.0 and -1.0.

Specified by:

scan in interface Scannable

Overrides:

scan in class Diff1Function1x1Base

Parameters:

rtok - Tokenizer from which to scan the spline

ref - optional reference object (not used)

Throws:

java.io.IOException - if an I/O or formatting error occured

write

public void write(java.io.PrintWriter pw,
                  NumberFormat fmt,
                  java.lang.Object ref)
           throws java.io.IOException

Writes a text description of this spline to a PrintWriter. The format is the same as that described for scan.

Specified by:

write in interface Scannable

Overrides:

write in class Diff1Function1x1Base

Parameters:

pw - writer to which the spline should be written

fmt - describes how the numbers should be formatted

ref - optional reference object (not used)

Throws:

java.io.IOException - if an I/O error occured

isWritable

public boolean isWritable()

Returns true if this component should in fact be written to secondary storage. This gives subclasses control over whether or not they are actually written out.

Specified by:

isWritable in interface Scannable

Overrides:

isWritable in class Diff1Function1x1Base

Returns:

true if this component should be written to secondary storage.

numKnots

public int numKnots()

getKnot

public CubicHermiteSpline1d.Knot getKnot(int idx)

getFirstKnot

public CubicHermiteSpline1d.Knot getFirstKnot()

getLastKnot

public CubicHermiteSpline1d.Knot getLastKnot()

updateCoefficients

public void updateCoefficients(CubicHermiteSpline1d.Knot knot)

updateCoefficients

public void updateCoefficients()

iterator

public java.util.Iterator<CubicHermiteSpline1d.Knot> iterator()

Specified by:

iterator in interface java.lang.Iterable<CubicHermiteSpline1d.Knot>

set

public void set(CubicHermiteSpline1d spline)

Sets this spline to be a copy of another spline.

Parameters:

spline - spline to copy

scaleX

public void scaleX(double s)

Scales the x values of this spline.

Parameters:

s - scale factor

scaleY

public void scaleY(double s)

Scales the y values of this spline.

Parameters:

s - scale factor

isInvertible

public boolean isInvertible()

Queries whether this spline is invertible. We use a strict definition: the knot y values must be stictly monotonic, and y'(s) must not be zero anywhere. The spline must also have at least one knots.

Returns:

true if this spline is invertible

solveX

public double solveX(double y)

Solves for the x value given a specific y value. In order to do this, the spline must be invertible. Y values outside the nominal range are extrapolated based on the x and 1/dy values at the end knots.

Parameters:

y - value for which x should be solved

Throws:

ImproperStateException - if the spline is not invertible

java.lang.IllegalArgumentException - if the spline is invertible but y is out of range

solveX

public double solveX(double y,
                     double alpha)

Solves for the x value given a specific y value of the function defined by this spline plus a linear term alpha x. In order to do this, the spline must be invertible, and the sign of alpha must be consistent with its monotonicity. Y values outside the nominal range are extrapolated based on the x and 1/dy values at the end knots.

Parameters:

y - value for which x should be solvde

alpha - slope of the additional linear term

Throws:

ImproperStateException - if the spline is not invertible

java.lang.IllegalArgumentException - if the sign of alpha is inconsistent with the spline's monotonicity

copy

public CubicHermiteSpline1d copy()

Creates a copy of this spline.

equals

public boolean equals(CubicHermiteSpline1d curve)

clone

public CubicHermiteSpline1d clone()

Specified by:

clone in interface Clonable

Overrides:

clone in class Diff1Function1x1Base