[ Tcllib Table Of Contents  Tcllib Index ]
math::interpolate(n) 1.1 "Tcl Math Library"
Name
math::interpolate  Interpolation routines
Synopsis
 package require Tcl ?8.4?
 package require struct
 package require math::interpolate ?1.1?
 ::math::interpolate::defineTable name colnames values
 ::math::interpolate::interp1dtable name xval
 ::math::interpolate::interptable name xval yval
 ::math::interpolate::interplinear xyvalues xval
 ::math::interpolate::interplagrange xyvalues xval
 ::math::interpolate::preparecubicsplines xcoord ycoord
 ::math::interpolate::interpcubicsplines coeffs x
 ::math::interpolate::interpspatial xyvalues coord
 ::math::interpolate::interpspatialparams max_search power
 ::math::interpolate::neville xlist ylist x
Description
This package implements several interpolation algorithms:

Interpolation into a table (one or two independent variables), this is useful for example, if the data are static, like with tables of statistical functions.

Linear interpolation into a given set of data (organised as (x,y) pairs).

Lagrange interpolation. This is mainly of theoretical interest, because there is no guarantee about error bounds. One possible use: if you need a line or a parabola through given points (it will calculate the values, but not return the coefficients).
A variation is Neville's method which has better behaviour and error bounds.

Spatial interpolation using a straightforward distanceweight method. This procedure allows any number of spatial dimensions and any number of dependent variables.

Interpolation in one dimension using cubic splines.
This document describes the procedures and explains their usage.
INCOMPATIBILITY WITH VERSION 1.0.3
The interpretation of the tables in the ::math::interpolate::interpolate1dtable command has been changed to be compatible with the interpretation for 2D interpolation in the ::math::interpolate::interpolatetable command. As a consequence this version is incompatible with the previous versions of the command (1.0.x).
PROCEDURES
The interpolation package defines the following public procedures:
 ::math::interpolate::defineTable name colnames values

Define a table with one or two independent variables (the distinction is implicit in the data). The procedure returns the name of the table  this name is used whenever you want to interpolate the values. Note: this procedure is a convenient wrapper for the struct::matrix procedure. Therefore you can access the data at any location in your program.
 string name (in)

Name of the table to be created
 list colnames (in)

List of column names
 list values (in)

List of values (the number of elements should be a multiple of the number of columns. See EXAMPLES for more information on the interpretation of the data.
The values must be sorted with respect to the independent variable(s).
 ::math::interpolate::interp1dtable name xval

Interpolate into the onedimensional table "name" and return a list of values, one for each dependent column.
 string name (in)

Name of an existing table
 float xval (in)

Value of the independent row variable
 ::math::interpolate::interptable name xval yval

Interpolate into the twodimensional table "name" and return the interpolated value.
 string name (in)

Name of an existing table
 float xval (in)

Value of the independent row variable
 float yval (in)

Value of the independent column variable
 ::math::interpolate::interplinear xyvalues xval

Interpolate linearly into the list of x,y pairs and return the interpolated value.
 list xyvalues (in)

List of pairs of (x,y) values, sorted to increasing x. They are used as the breakpoints of a piecewise linear function.
 float xval (in)

Value of the independent variable for which the value of y must be computed.
 ::math::interpolate::interplagrange xyvalues xval

Use the list of x,y pairs to construct the unique polynomial of lowest degree that passes through all points and return the interpolated value.
 list xyvalues (in)

List of pairs of (x,y) values
 float xval (in)

Value of the independent variable for which the value of y must be computed.
 ::math::interpolate::preparecubicsplines xcoord ycoord

Returns a list of coefficients for the second routine interpcubicsplines to actually interpolate.
 list xcoord

List of xcoordinates for the value of the function to be interpolated is known. The coordinates must be strictly ascending. At least three points are required.
 list ycoord

List of ycoordinates (the values of the function at the given xcoordinates).
 ::math::interpolate::interpcubicsplines coeffs x

Returns the interpolated value at coordinate x. The coefficients are computed by the procedure preparecubicsplines.
 list coeffs

List of coefficients as returned by preparecubicsplines
 float x

xcoordinate at which to estimate the function. Must be between the first and last xcoordinate for which values were given.
 ::math::interpolate::interpspatial xyvalues coord

Use a straightforward interpolation method with weights as function of the inverse distance to interpolate in 2D and Ndimensional space
The list xyvalues is a list of lists:
{ {x1 y1 z1 {v11 v12 v13 v14}} {x2 y2 z2 {v21 v22 v23 v24}} ... }
The last element of each inner list is either a single number or a list in itself. In the latter case the return value is a list with the same number of elements.
The method is influenced by the search radius and the power of the inverse distance
 list xyvalues (in)

List of lists, each sublist being a list of coordinates and of dependent values.
 list coord (in)

List of coordinates for which the values must be calculated
 ::math::interpolate::interpspatialparams max_search power

Set the parameters for spatial interpolation
 float max_search (in)

Search radius (data points further than this are ignored)
 integer power (in)

Power for the distance (either 1 or 2; defaults to 2)
 ::math::interpolate::neville xlist ylist x

Interpolates between the tabulated values of a function whose abscissae are xlist and whose ordinates are ylist to produce an estimate for the value of the function at x. The result is a twoelement list; the first element is the function's estimated value, and the second is an estimate of the absolute error of the result. Neville's algorithm for polynomial interpolation is used. Note that a large table of values will use an interpolating polynomial of high degree, which is likely to result in numerical instabilities; one is better off using only a few tabulated values near the desired abscissa.
EXAMPLES
Example of using onedimensional tables:
Suppose you have several tabulated functions of one variable:
x y1 y2 0.0 0.0 0.0 1.0 1.0 1.0 2.0 4.0 8.0 3.0 9.0 27.0 4.0 16.0 64.0
Then to estimate the values at 0.5, 1.5, 2.5 and 3.5, you can use:
set table [::math::interpolate::defineTable table1 {x y1 y2} {  1 2 0.0 0.0 0.0 1.0 1.0 1.0 2.0 4.0 8.0 3.0 9.0 27.0 4.0 16.0 64.0}] foreach x {0.5 1.5 2.5 3.5} { puts "$x: [::math::interpolate::interp1dtable $table $x]" }
For onedimensional tables the first row is not used. For twodimensional tables, the first row represents the values for the second independent variable.
Example of using the cubic splines:
Suppose the following values are given:
x y 0.1 1.0 0.3 2.1 0.4 2.2 0.8 4.11 1.0 4.12
Then to estimate the values at 0.1, 0.2, 0.3, ... 1.0, you can use:
set coeffs [::math::interpolate::preparecubicsplines {0.1 0.3 0.4 0.8 1.0} {1.0 2.1 2.2 4.11 4.12}] foreach x {0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0} { puts "$x: [::math::interpolate::interpcubicsplines $coeffs $x]" }
to get the following output:
0.1: 1.0 0.2: 1.68044117647 0.3: 2.1 0.4: 2.2 0.5: 3.11221507353 0.6: 4.25242647059 0.7: 5.41804227941 0.8: 4.11 0.9: 3.95675857843 1.0: 4.12
As you can see, the values at the abscissae are reproduced perfectly.
Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category math :: interpolate of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.
Category
Mathematics
Copyright
Copyright © 2004 Arjen Markus
<arjenmarkus@users.sourceforge.net>
Copyright © 2004 Kevn B. Kenny
<kennykb@users.sourceforge.net>