interpolate(3)



math::interpolate(3tcl)        Tcl Math Library        math::interpolate(3tcl)

______________________________________________________________________________

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:

       o      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.

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

       o      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.

       o      Spatial interpolation using  a  straightforward  distance-weight
              method.  This  procedure allows any number of spatial dimensions
              and any number of dependent variables.

       o      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::interpo-
       late-1d-table command has been changed to be compatible with the inter-
       pretation 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  dis-
              tinction  is  implicit  in  the data). The procedure returns the
              name of the table - this name is used whenever you want  to  in-
              terpolate the values. Note: this procedure is a convenient wrap-
              per 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 multi-
                     ple of the number of columns. See EXAMPLES for  more  in-
                     formation 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 in-
              terpolated 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-cu-
              bic-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 func-
              tion  of  the inverse distance to interpolate in 2D and N-dimen-
              sional 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  calcu-
                     lated

       ::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 interpolat-
              ing polynomial of high degree, which is likely to result in  nu-
              merical  instabilities; one is better off using only a few tabu-
              lated 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-dimen-
       sional tables, the first row represents the values for the second inde-
       pendent 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/re-
       portlist].   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 out-
       put 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>

tcllib                                1.1              math::interpolate(3tcl)

Man(1) output converted with man2html
list of all man pages