summaryrefslogtreecommitdiff
path: root/modules/interpolation/help/en_US/splin2d.xml
blob: 01f80ca5807a531d06791d64614428d1e39e83e1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
<?xml version="1.0" encoding="UTF-8"?>
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="splin2d" xml:lang="en">
    <refnamediv>
        <refname>splin2d</refname>
        <refpurpose>bicubic spline gridded 2d interpolation</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Calling Sequence</title>
        <synopsis>C = splin2d(x, y, z, [,spline_type])</synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>x</term>
                <listitem>
                    <para> a 1-by-nx matrix of doubles, the x coordinate of the interpolation points. We must have x(i)&lt;x(i+1), for i=1,2,...,nx-1.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y</term>
                <listitem>
                    <para>a 1-by-ny matrix of doubles, the y coordinate of the interpolation points.
                        We must have y(i)&lt;y(i+1), for i=1,2,...,ny-1.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>z</term>
                <listitem>
                    <para>a nx-by-ny matrix of doubles, the function values.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>spline_type</term>
                <listitem>
                    <para>a 1-by-1 matrix of strings, the typof of spline to compute.
                        Available values are spline_type="not_a_knot" and spline_type="periodic".
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>C</term>
                <listitem>
                    <para>the coefficients of the bicubic patches. This output argument of splin2d is the input argument of the interp2d function.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>This function computes a bicubic spline or sub-spline
            <emphasis>s</emphasis> which interpolates the
            <emphasis>(xi,yj,zij)</emphasis> points, ie, we have
            <emphasis>s(xi,yj)=zij</emphasis> for all <emphasis>i=1,..,nx</emphasis>
            and <emphasis>j=1,..,ny</emphasis>. The resulting spline
            <emphasis>s</emphasis> is defined by the triplet
            <literal>(x,y,C)</literal> where <literal>C</literal> is the vector (of
            length 16(nx-1)(ny-1)) with the coefficients of each of the (nx-1)(ny-1)
            bicubic patches : on <emphasis>[x(i) x(i+1)]x[y(j) y(j+1)]</emphasis>,
            <emphasis>s</emphasis> is defined by :
        </para>
        <informalequation>
            <mediaobject>
                <imageobject>
                    <imagedata align="center" fileref="../mml/splin2d_equation_1.mml"/>
                </imageobject>
            </mediaobject>
        </informalequation>
        <para>
            The evaluation of <emphasis>s</emphasis> at some points must be done
            by the <link linkend="interp2d">interp2d</link> function. Several kind of
            splines may be computed by selecting the appropriate
            <literal>spline_type</literal> parameter. The method used to compute the
            bicubic spline (or sub-spline) is the old fashionned one 's, i.e. to
            compute on each grid point <emphasis>(xi,yj)</emphasis> an approximation
            of the first derivatives <emphasis>ds/dx(xi,yj)</emphasis> and
            <emphasis>ds/dy(xi,yj)</emphasis> and of the cross derivative
            <emphasis>d2s/dxdy(xi,yj)</emphasis>. Those derivatives are computed by
            the mean of 1d spline schemes leading to a C2 function
            (<emphasis>s</emphasis> is twice continuously differentiable) or by the
            mean of a local approximation scheme leading to a C1 function only. This
            scheme is selected with the <literal>spline_type</literal> parameter (see
            <link linkend="splin">splin</link> for details) :
        </para>
        <variablelist>
            <varlistentry>
                <term>"not_a_knot"</term>
                <listitem>
                    <para>this is the default case.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>"periodic"</term>
                <listitem>
                    <para>to use if the underlying function is periodic : you must have
                        <emphasis>z(1,j) = z(nx,j) for all j in [1,ny] and z(i,1) = z(i,ny)
                            for i in [1,nx]
                        </emphasis>
                        but this is not verified by the
                        interface.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Remarks</title>
        <para>
            From an accuracy point of view use essentially the <emphasis role="bold">not_a_knot</emphasis> type or <emphasis role="bold">periodic</emphasis> type if the underlying interpolated
            function is periodic.
        </para>
        <para>
            The <emphasis role="bold">natural</emphasis>, <emphasis role="bold">monotone</emphasis>, <emphasis role="bold">fast</emphasis> (or
            <emphasis role="bold">fast_periodic</emphasis>) type may be useful in some
            cases, for instance to limit oscillations (<emphasis role="bold">monotone</emphasis> being the most powerful for that).
        </para>
        <para>To get the coefficients of the bi-cubic patches in a more friendly
            way you can use <literal>c = hypermat([4,4,nx-1,ny-1],C)</literal> then
            the coefficient <emphasis>(k,l)</emphasis> of the patch
            <emphasis>(i,j)</emphasis> (see equation here before) is stored at
            <literal>c(k,l,i,j)</literal>. Nevertheless the <link linkend="interp2d">interp2d</link> function wait for the big vector
            <literal>C</literal> and not for the hypermatrix <literal>c</literal>
            (note that one can easily retrieve <literal>C</literal> from
            <literal>c</literal> with <literal>C=c(:)</literal>).
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[ 
// example 1 : interpolation of cos(x)cos(y)
n = 7;  // a regular grid with n x n interpolation points
        // will be used
x = linspace(0,2*%pi,n); y = x;
z = cos(x')*cos(y);
C = splin2d(x, y, z, "periodic");
m = 50; // discretization parameter of the evaluation grid
xx = linspace(0,2*%pi,m); yy = xx;
[XX,YY] = ndgrid(xx,yy);
zz = interp2d(XX,YY, x, y, C);
emax = max(abs(zz - cos(xx')*cos(yy)));
clf()
plot3d(xx, yy, zz, flag=[2 4 4])
[X,Y] = ndgrid(x,y);
param3d1(X,Y,list(z,-9*ones(1,n)), flag=[0 0])
str = msprintf(" with %d x %d interpolation points. ermax = %g",n,n,emax) 
xtitle("spline interpolation of cos(x)cos(y)"+str)
 ]]></programlisting>
        <scilab:image>
            n = 7;  // a regular grid with n x n interpolation points
            // will be used
            x = linspace(0,2*%pi,n); y = x;
            z = cos(x')*cos(y);
            C = splin2d(x, y, z, "periodic");
            m = 50; // discretization parameter of the evaluation grid
            xx = linspace(0,2*%pi,m); yy = xx;
            [XX,YY] = ndgrid(xx,yy);
            zz = interp2d(XX,YY, x, y, C);
            emax = max(abs(zz - cos(xx')*cos(yy)));
            clf()
            plot3d(xx, yy, zz, flag=[2 4 4])
            [X,Y] = ndgrid(x,y);
            param3d1(X,Y,list(z,-9*ones(1,n)), flag=[0 0])
            str = msprintf(" with %d x %d interpolation points. ermax = %g",n,n,emax) 
            xtitle("spline interpolation of cos(x)cos(y)"+str)
        </scilab:image>
        
        <programlisting role="example"><![CDATA[ 
// example 2 : different interpolation functions on random data
n = 6;
x = linspace(0,1,n); y = x;
z = rand(n,n);
np = 50;
xp = linspace(0,1,np); yp = xp;
[XP, YP] = ndgrid(xp,yp);
ZP1 = interp2d(XP, YP, x, y, splin2d(x, y, z, "not_a_knot"));
ZP2 = linear_interpn(XP, YP, x, y, z);
ZP3 = interp2d(XP, YP, x, y, splin2d(x, y, z, "natural"));
ZP4 = interp2d(XP, YP, x, y, splin2d(x, y, z, "monotone"));
xset("colormap", jetcolormap(64))
clf()
subplot(2,2,1)
plot3d1(xp, yp, ZP1, flag=[2 2 4])
xtitle("not_a_knot")
subplot(2,2,2)
plot3d1(xp, yp, ZP2, flag=[2 2 4])
xtitle("bilinear interpolation")
subplot(2,2,3)
plot3d1(xp, yp, ZP3, flag=[2 2 4])
xtitle("natural")
subplot(2,2,4)
plot3d1(xp, yp, ZP4, flag=[2 2 4])
xtitle("monotone")
show_window()
 ]]></programlisting>
        <scilab:image>
            // example 2 : different interpolation functions on random data
            n = 6;
            x = linspace(0,1,n); y = x;
            z = rand(n,n);
            np = 50;
            xp = linspace(0,1,np); yp = xp;
            [XP, YP] = ndgrid(xp,yp);
            ZP1 = interp2d(XP, YP, x, y, splin2d(x, y, z, "not_a_knot"));
            ZP2 = linear_interpn(XP, YP, x, y, z);
            ZP3 = interp2d(XP, YP, x, y, splin2d(x, y, z, "natural"));
            ZP4 = interp2d(XP, YP, x, y, splin2d(x, y, z, "monotone"));
            xset("colormap", jetcolormap(64))
            clf()
            subplot(2,2,1)
            plot3d1(xp, yp, ZP1, flag=[2 2 4])
            xtitle("not_a_knot")
            subplot(2,2,2)
            plot3d1(xp, yp, ZP2, flag=[2 2 4])
            xtitle("bilinear interpolation")
            subplot(2,2,3)
            plot3d1(xp, yp, ZP3, flag=[2 2 4])
            xtitle("natural")
            subplot(2,2,4)
            plot3d1(xp, yp, ZP4, flag=[2 2 4])
            xtitle("monotone")
            show_window()
        </scilab:image>
        <programlisting role="example"><![CDATA[ 
// example 3 : not_a_knot spline and monotone sub-spline
//             on a step function
a = 0; b = 1; c = 0.25; d = 0.75;
// create interpolation grid
n = 11;
x = linspace(a,b,n);
ind = find(c <= x & x <= d); 
z = zeros(n,n); z(ind,ind) = 1;  // a step inside a square
// create evaluation grid
np = 220;
xp = linspace(a,b, np);
[XP, YP] = ndgrid(xp, xp);
zp1 = interp2d(XP, YP, x, x, splin2d(x,x,z));
zp2 = interp2d(XP, YP, x, x, splin2d(x,x,z,"monotone"));
// plot
clf()
xset("colormap",jetcolormap(128))
subplot(1,2,1)
plot3d1(xp, xp, zp1, flag=[-2 6 4])
xtitle("spline (not_a_knot)")
subplot(1,2,2)
plot3d1(xp, xp, zp2, flag=[-2 6 4])
xtitle("subspline (monotone)")
 ]]></programlisting>
        
    </refsection>
    <refsection role="see also">
        <title>See Also</title>
        <simplelist type="inline">
            <member>
                <link linkend="cshep2d">cshep2d</link>
            </member>
            <member>
                <link linkend="linear_interpn">linear_interpn</link>
            </member>
            <member>
                <link linkend="interp2d">interp2d</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.4.0</revnumber>
                <revremark>previously, imaginary part of input arguments were implicitly ignored.</revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>