1math::interpolate(n)           Tcl Math Library           math::interpolate(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       math::interpolate - Interpolation routines
9

SYNOPSIS

11       package require Tcl  ?8.4?
12
13       package require struct
14
15       package require math::interpolate  ?1.1?
16
17       ::math::interpolate::defineTable name colnames values
18
19       ::math::interpolate::interp-1d-table name xval
20
21       ::math::interpolate::interp-table name xval yval
22
23       ::math::interpolate::interp-linear xyvalues xval
24
25       ::math::interpolate::interp-lagrange xyvalues xval
26
27       ::math::interpolate::prepare-cubic-splines xcoord ycoord
28
29       ::math::interpolate::interp-cubic-splines coeffs x
30
31       ::math::interpolate::interp-spatial xyvalues coord
32
33       ::math::interpolate::interp-spatial-params max_search power
34
35       ::math::interpolate::neville xlist ylist x
36
37______________________________________________________________________________
38

DESCRIPTION

40       This package implements several interpolation algorithms:
41
42       •      Interpolation  into  a table (one or two independent variables),
43              this is useful for example, if the data are  static,  like  with
44              tables of statistical functions.
45
46       •      Linear  interpolation  into  a  given  set of data (organised as
47              (x,y) pairs).
48
49       •      Lagrange interpolation. This is mainly of theoretical  interest,
50              because  there  is no guarantee about error bounds. One possible
51              use: if you need a line or a parabola through given  points  (it
52              will calculate the values, but not return the coefficients).
53
54              A  variation  is Neville's method which has better behaviour and
55              error bounds.
56
57       •      Spatial interpolation using  a  straightforward  distance-weight
58              method.  This  procedure allows any number of spatial dimensions
59              and any number of dependent variables.
60
61       •      Interpolation in one dimension using cubic splines.
62
63       This document describes the procedures and explains their usage.
64

INCOMPATIBILITY WITH VERSION 1.0.3

66       The interpretation of the tables in  the  ::math::interpolate::interpo‐
67       late-1d-table command has been changed to be compatible with the inter‐
68       pretation for 2D interpolation in the ::math::interpolate::interpolate-
69       table  command.  As a consequence this version is incompatible with the
70       previous versions of the command (1.0.x).
71

PROCEDURES

73       The interpolation package defines the following public procedures:
74
75       ::math::interpolate::defineTable name colnames values
76              Define a table with one or two independent variables  (the  dis‐
77              tinction  is  implicit  in  the data). The procedure returns the
78              name of the table - this name is used whenever you want  to  in‐
79              terpolate the values. Note: this procedure is a convenient wrap‐
80              per for the struct::matrix procedure. Therefore you  can  access
81              the data at any location in your program.
82
83              string name (in)
84                     Name of the table to be created
85
86              list colnames (in)
87                     List of column names
88
89              list values (in)
90                     List of values (the number of elements should be a multi‐
91                     ple of the number of columns. See EXAMPLES for  more  in‐
92                     formation on the interpretation of the data.
93
94                     The values must be sorted with respect to the independent
95                     variable(s).
96
97
98       ::math::interpolate::interp-1d-table name xval
99              Interpolate into the one-dimensional table "name" and  return  a
100              list of values, one for each dependent column.
101
102              string name (in)
103                     Name of an existing table
104
105              float xval (in)
106                     Value of the independent row variable
107
108
109       ::math::interpolate::interp-table name xval yval
110              Interpolate into the two-dimensional table "name" and return the
111              interpolated value.
112
113              string name (in)
114                     Name of an existing table
115
116              float xval (in)
117                     Value of the independent row variable
118
119              float yval (in)
120                     Value of the independent column variable
121
122
123       ::math::interpolate::interp-linear xyvalues xval
124              Interpolate linearly into the list of x,y pairs and  return  the
125              interpolated value.
126
127              list xyvalues (in)
128                     List  of  pairs  of (x,y) values, sorted to increasing x.
129                     They are used as the breakpoints of  a  piecewise  linear
130                     function.
131
132              float xval (in)
133                     Value  of the independent variable for which the value of
134                     y must be computed.
135
136
137       ::math::interpolate::interp-lagrange xyvalues xval
138              Use the list of x,y pairs to construct the unique polynomial  of
139              lowest  degree that passes through all points and return the in‐
140              terpolated value.
141
142              list xyvalues (in)
143                     List of pairs of (x,y) values
144
145              float xval (in)
146                     Value of the independent variable for which the value  of
147                     y must be computed.
148
149
150       ::math::interpolate::prepare-cubic-splines xcoord ycoord
151              Returns a list of coefficients for the second routine interp-cu‐
152              bic-splines to actually interpolate.
153
154              list xcoord
155                     List of x-coordinates for the value of the function to be
156                     interpolated  is  known. The coordinates must be strictly
157                     ascending. At least three points are required.
158
159              list ycoord
160                     List of y-coordinates (the values of the function at  the
161                     given x-coordinates).
162
163
164       ::math::interpolate::interp-cubic-splines coeffs x
165              Returns the interpolated value at coordinate x. The coefficients
166              are computed by the procedure prepare-cubic-splines.
167
168              list coeffs
169                     List of coefficients as returned by prepare-cubic-splines
170
171              float x
172                     x-coordinate at which to estimate the function.  Must  be
173                     between  the first and last x-coordinate for which values
174                     were given.
175
176
177       ::math::interpolate::interp-spatial xyvalues coord
178              Use a straightforward interpolation method with weights as func‐
179              tion  of  the inverse distance to interpolate in 2D and N-dimen‐
180              sional space
181
182              The list xyvalues is a list of lists:
183
184
185                  {   {x1 y1 z1 {v11 v12 v13 v14}}
186                {x2 y2 z2 {v21 v22 v23 v24}}
187                ...
188                  }
189
190
191              The last element of each inner list is either a single number or
192              a list in itself.  In the latter case the return value is a list
193              with the same number of elements.
194
195              The method is influenced by the search radius and the  power  of
196              the inverse distance
197
198              list xyvalues (in)
199                     List  of  lists, each sublist being a list of coordinates
200                     and of dependent values.
201
202              list coord (in)
203                     List of coordinates for which the values must  be  calcu‐
204                     lated
205
206
207       ::math::interpolate::interp-spatial-params max_search power
208              Set the parameters for spatial interpolation
209
210              float max_search (in)
211                     Search radius (data points further than this are ignored)
212
213              integer power (in)
214                     Power for the distance (either 1 or 2; defaults to 2)
215
216       ::math::interpolate::neville xlist ylist x
217              Interpolates  between  the  tabulated values of a function whose
218              abscissae are xlist and whose ordinates are ylist to produce  an
219              estimate  for  the  value of the function at x.  The result is a
220              two-element list; the first element is the function's  estimated
221              value,  and  the  second is an estimate of the absolute error of
222              the result.  Neville's algorithm for polynomial interpolation is
223              used.  Note that a large table of values will use an interpolat‐
224              ing polynomial of high degree, which is likely to result in  nu‐
225              merical  instabilities; one is better off using only a few tabu‐
226              lated values near the desired abscissa.
227

EXAMPLES

229       Example of using one-dimensional tables:
230
231       Suppose you have several tabulated functions of one variable:
232
233
234                  x     y1     y2
235                0.0    0.0    0.0
236                1.0    1.0    1.0
237                2.0    4.0    8.0
238                3.0    9.0   27.0
239                4.0   16.0   64.0
240
241       Then to estimate the values at 0.5, 1.5, 2.5 and 3.5, you can use:
242
243
244                 set table [::math::interpolate::defineTable table1  {x y1 y2} {   -      1      2
245                                 0.0    0.0    0.0
246                                 1.0    1.0    1.0
247                                 2.0    4.0    8.0
248                                 3.0    9.0   27.0
249                                 4.0   16.0   64.0}]
250                 foreach x {0.5 1.5 2.5 3.5} {
251                     puts "$x: [::math::interpolate::interp-1d-table $table $x]"
252                 }
253
254       For one-dimensional tables the first row is not  used.  For  two-dimen‐
255       sional tables, the first row represents the values for the second inde‐
256       pendent variable.
257
258       Example of using the cubic splines:
259
260       Suppose the following values are given:
261
262
263                  x       y
264                0.1     1.0
265                0.3     2.1
266                0.4     2.2
267                0.8     4.11
268                1.0     4.12
269
270       Then to estimate the values at 0.1, 0.2, 0.3, ... 1.0, you can use:
271
272
273                 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}]
274                 foreach x {0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0} {
275                    puts "$x: [::math::interpolate::interp-cubic-splines $coeffs $x]"
276                 }
277
278       to get the following output:
279
280
281              0.1: 1.0
282              0.2: 1.68044117647
283              0.3: 2.1
284              0.4: 2.2
285              0.5: 3.11221507353
286              0.6: 4.25242647059
287              0.7: 5.41804227941
288              0.8: 4.11
289              0.9: 3.95675857843
290              1.0: 4.12
291
292       As you can see, the values at the abscissae are reproduced perfectly.
293

BUGS, IDEAS, FEEDBACK

295       This document, and the package it describes, will  undoubtedly  contain
296       bugs  and  other  problems.  Please report such in the category math ::
297       interpolate  of  the  Tcllib  Trackers   [http://core.tcl.tk/tcllib/re
298       portlist].   Please also report any ideas for enhancements you may have
299       for either package and/or documentation.
300
301       When proposing code changes, please provide unified diffs, i.e the out‐
302       put of diff -u.
303
304       Note  further  that  attachments  are  strongly  preferred over inlined
305       patches. Attachments can be made by going  to  the  Edit  form  of  the
306       ticket  immediately  after  its  creation, and then using the left-most
307       button in the secondary navigation bar.
308

KEYWORDS

310       interpolation, math, spatial interpolation
311

CATEGORY

313       Mathematics
314
316       Copyright (c) 2004 Arjen Markus <arjenmarkus@users.sourceforge.net>
317       Copyright (c) 2004 Kevn B. Kenny <kennykb@users.sourceforge.net>
318
319
320
321
322tcllib                                1.1                 math::interpolate(n)
Impressum