Provided by: tcllib_1.19-dfsg-2_all bug

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::interp-1d-table name xval

       ::math::interpolate::interp-table name xval yval

       ::math::interpolate::interp-linear xyvalues xval

       ::math::interpolate::interp-lagrange xyvalues xval

       ::math::interpolate::prepare-cubic-splines xcoord ycoord

       ::math::interpolate::interp-cubic-splines coeffs x

       ::math::interpolate::interp-spatial xyvalues coord

       ::math::interpolate::interp-spatial-params 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  distance-weight  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::interpolate-1d-table command
       has been changed to be compatible with the interpretation  for  2D  interpolation  in  the
       ::math::interpolate::interpolate-table   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::interp-1d-table name xval
              Interpolate into the one-dimensional 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::interp-table name xval yval
              Interpolate  into  the  two-dimensional  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::interp-linear 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::interp-lagrange 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::prepare-cubic-splines xcoord ycoord
              Returns a list of coefficients  for  the  second  routine  interp-cubic-splines  to
              actually interpolate.

              list xcoord
                     List  of  x-coordinates  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  y-coordinates  (the  values  of  the  function  at  the  given  x-
                     coordinates).

       ::math::interpolate::interp-cubic-splines coeffs x
              Returns the interpolated value at coordinate x. The coefficients  are  computed  by
              the procedure prepare-cubic-splines.

              list coeffs
                     List of coefficients as returned by prepare-cubic-splines

              float x
                     x-coordinate  at  which  to estimate the function. Must be between the first
                     and last x-coordinate for which values were given.

       ::math::interpolate::interp-spatial xyvalues coord
              Use a straightforward interpolation method with weights as function of the  inverse
              distance to interpolate in 2D and N-dimensional 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::interp-spatial-params 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  two-element  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 one-dimensional 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::interp-1d-table $table $x]"
                 }

       For one-dimensional tables the first row is not  used.  For  two-dimensional  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::prepare-cubic-splines  {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::interp-cubic-splines $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
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be  made  by going to the Edit form of the ticket immediately after its creation, and then
       using the left-most button in the secondary navigation bar.

KEYWORDS

       interpolation, math, spatial interpolation

CATEGORY

       Mathematics

COPYRIGHT

       Copyright (c) 2004 Arjen Markus <arjenmarkus@users.sourceforge.net>
       Copyright (c) 2004 Kevn B. Kenny <kennykb@users.sourceforge.net>