Split the interp2d example instead of having one big image with subplots
[scilab.git] / scilab / modules / interpolation / help / en_US / interp2d.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <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="interp2d" xml:lang="en">
3     <refnamediv>
4         <refname>interp2d</refname>
5         <refpurpose>bicubic spline (2d) evaluation function</refpurpose>
6     </refnamediv>
7     <refsynopsisdiv>
8         <title>Calling Sequence</title>
9         <synopsis>[zp[, dzpdx, dzpdy[, d2zpdxx, d2zpdxy, d2zpdyy]]]=interp2d(xp, yp, x, y, C [,out_mode])</synopsis>
10     </refsynopsisdiv>
11     <refsection>
12         <title>Arguments</title>
13         <variablelist>
14             <varlistentry>
15                 <term>xp</term>
16                 <listitem>
17                     <para>
18                         a mx-by-my matrix of doubles, the <varname>x</varname> coordinates of the points where the spline is to be evaluated.
19                     </para>
20                 </listitem>
21             </varlistentry>
22             <varlistentry>
23                 <term>yp</term>
24                 <listitem>
25                     <para>
26                         a mx-by-my matrix of doubles, the <varname>y</varname> coordinates of the points where the spline is to be evaluated.
27                     </para>
28                 </listitem>
29             </varlistentry>
30             <varlistentry>
31                 <term>x</term>
32                 <listitem>
33                     <para>
34                         a 1-by-nx matrix of doubles, the <varname>x</varname> coordinate of the interpolation points.
35                         We must have x(i)&lt;x(i+1), for i=1,2,...,nx-1.
36                     </para>
37                 </listitem>
38             </varlistentry>
39             
40             <varlistentry>
41                 <term>y</term>
42                 <listitem>
43                     <para>
44                         a 1-by-ny matrix of doubles, the <varname>y</varname> coordinate of the interpolation points.
45                         We must have y(i)&lt;y(i+1), for i=1,2,...,ny-1.
46                     </para>
47                 </listitem>
48             </varlistentry>
49             
50             <varlistentry>
51                 <term>C</term>
52                 <listitem>
53                     <para>
54                         The coefficients of the bicubic spline. The input argument of the interp2d function is the output argument of the <link linkend="splin2d">splin2d</link> function.                    
55                     </para>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>out_mode</term>
60                 <listitem>
61                     <para>a 1-by-1 matrix of strings, the evaluation of s outside the range [x(1),x(nx)] by [y(1),y(ny)].
62                     </para>
63                 </listitem>
64             </varlistentry>
65             <varlistentry>
66                 <term>zp</term>
67                 <listitem>
68                     <para>
69                         a mx-by-my matrix of doubles, the evaluation of the <varname>z</varname> coordinate of the spline, i.e. zp(i,j)=s(xp(i,j),yp(i,j)), for i=1,2,...,mx and j = 1,2,...,my.
70                     </para>
71                 </listitem>
72             </varlistentry>
73             
74             <varlistentry>
75                 <term>dzpdx</term>
76                 <listitem>
77                     <para>a mx-by-my matrix of doubles, the first derivative of the spline with
78                         respect to <varname>x</varname>.
79                     </para>
80                 </listitem>
81             </varlistentry>
82             
83             <varlistentry>
84                 <term>dzpdy</term>
85                 <listitem>
86                     <para>a mx-by-my matrix of doubles, the first derivative of the spline with
87                         respect to <varname>y</varname>.
88                     </para>
89                 </listitem>
90             </varlistentry>
91             
92             <varlistentry>
93                 <term>d2zpdxx</term>
94                 <listitem>
95                     <para>a mx-by-my matrix of doubles, the second derivative of the spline with
96                         respect to <varname>x</varname>.
97                     </para>
98                 </listitem>
99             </varlistentry>
100             
101             <varlistentry>
102                 <term>d2zpdxy</term>
103                 <listitem>
104                     <para> a mx-by-my matrix of doubles, the second derivative of the spline with
105                         respect to <varname>x</varname> and <varname>y</varname>.
106                         
107                     </para>
108                 </listitem>
109             </varlistentry>
110             
111             <varlistentry>
112                 <term>d2zpdyy</term>
113                 <listitem>
114                     <para>a mx-by-my matrix of doubles, the second derivative of the spline with
115                         respect to <varname>y</varname>.
116                     </para>
117                 </listitem>
118             </varlistentry>
119         </variablelist>
120     </refsection>
121     <refsection>
122         <title>Description</title>
123         <para>
124             Given three vectors <literal>(x,y,C)</literal> defining a bicubic
125             spline or sub-spline function (see <link linkend="splin2d">splin2d</link>)
126             this function evaluates <emphasis>s</emphasis> (and <emphasis>ds/dx,
127                 ds/dy, d2s/dxx, d2s/dxy, d2s/dyy
128             </emphasis>
129             if needed) at
130             <emphasis>(xp(i),yp(i))</emphasis> :
131         </para>
132         <informalequation>
133             <mediaobject>
134                 <imageobject>
135                     <imagedata fileref="../mml/interp2_equation_1.mml"/>
136                 </imageobject>
137             </mediaobject>
138         </informalequation>
139         <para>
140             The <literal>out_mode</literal> parameter defines the evaluation
141             rule for extrapolation, i.e. for <emphasis>(xp(i),yp(i)) not in
142                 [x(1),x(nx)]x[y(1),y(ny)]
143             </emphasis>
144             :
145         </para>
146         <variablelist>
147             <varlistentry>
148                 <term>"by_zero"</term>
149                 <listitem>
150                     <para>an extrapolation by zero is done</para>
151                 </listitem>
152             </varlistentry>
153             <varlistentry>
154                 <term>"by_nan"</term>
155                 <listitem>
156                     <para>extrapolation by Nan</para>
157                 </listitem>
158             </varlistentry>
159             <varlistentry>
160                 <term>"C0"</term>
161                 <listitem>
162                     <para>the extrapolation is defined as follows :</para>
163                     <programlisting role=""><![CDATA[ 
164 s(x,y) = s(proj(x,y)) where proj(x,y) is nearest point 
165                       of [x(1),x(nx)]x[y(1),y(ny)] from (x,y)
166  ]]></programlisting>
167                 </listitem>
168             </varlistentry>
169             <varlistentry>
170                 <term>"natural"</term>
171                 <listitem>
172                     <para>the extrapolation is done by using the nearest bicubic-patch
173                         from (x,y).
174                     </para>
175                 </listitem>
176             </varlistentry>
177             <varlistentry>
178                 <term>"periodic"</term>
179                 <listitem>
180                     <para>
181                         <literal>s</literal> is extended by periodicity.
182                     </para>
183                 </listitem>
184             </varlistentry>
185         </variablelist>
186     </refsection>
187     <refsection>
188         <title>Examples</title>
189         
190         <programlisting role="example"><![CDATA[
191 n = 7;  // a n x n interpolation grid
192 x = linspace(0,2*%pi,n); y = x;
193 z = cos(x')*cos(y);
194 C = splin2d(x, y, z, "periodic");
195
196 // now evaluate on a bigger domain than [0,2pi]x [0,2pi]
197 m = 80; // discretisation parameter of the evaluation grid
198 xx = linspace(-0.5*%pi,2.5*%pi,m); yy = xx;
199 [XX,YY] = ndgrid(xx,yy);
200 zz1 = interp2d(XX,YY, x, y, C, "C0");
201 plot3d(xx, yy, zz1, flag=[2 6 4])
202 xtitle("extrapolation with the C0 outmode")
203  ]]></programlisting>
204         <scilab:image>
205             n = 7;  // a n x n interpolation grid
206             x = linspace(0,2*%pi,n); y = x;
207             z = cos(x')*cos(y);
208             C = splin2d(x, y, z, "periodic");
209             
210             // now evaluate on a bigger domain than [0,2pi]x [0,2pi]
211             m = 80; // discretisation parameter of the evaluation grid
212             xx = linspace(-0.5*%pi,2.5*%pi,m); yy = xx;
213             [XX,YY] = ndgrid(xx,yy);
214             zz1 = interp2d(XX,YY, x, y, C, "C0");
215             plot3d(xx, yy, zz1, flag=[2 6 4])
216             xtitle("extrapolation with the C0 outmode")
217         </scilab:image>
218         
219         <programlisting role="example"><![CDATA[
220 n = 7;  // a n x n interpolation grid
221 x = linspace(0,2*%pi,n); y = x;
222 z = cos(x')*cos(y);
223 C = splin2d(x, y, z, "periodic");
224
225 // now evaluate on a bigger domain than [0,2pi]x [0,2pi]
226 m = 80; // discretisation parameter of the evaluation grid
227 xx = linspace(-0.5*%pi,2.5*%pi,m); yy = xx;
228 [XX,YY] = ndgrid(xx,yy);
229 zz2 = interp2d(XX,YY, x, y, C, "by_zero");
230 plot3d(xx, yy, zz2, flag=[2 6 4])
231 xtitle("extrapolation with the by_zero outmode")
232  ]]></programlisting>
233         <scilab:image>
234             n = 7;  // a n x n interpolation grid
235             x = linspace(0,2*%pi,n); y = x;
236             z = cos(x')*cos(y);
237             C = splin2d(x, y, z, "periodic");
238             
239             // now evaluate on a bigger domain than [0,2pi]x [0,2pi]
240             m = 80; // discretisation parameter of the evaluation grid
241             xx = linspace(-0.5*%pi,2.5*%pi,m); yy = xx;
242             [XX,YY] = ndgrid(xx,yy);
243             zz2 = interp2d(XX,YY, x, y, C, "by_zero");
244             plot3d(xx, yy, zz2, flag=[2 6 4])
245             xtitle("extrapolation with the by_zero outmode")
246         </scilab:image>
247         <programlisting role="example"><![CDATA[
248 n = 7;  // a n x n interpolation grid
249 x = linspace(0,2*%pi,n); y = x;
250 z = cos(x')*cos(y);
251 C = splin2d(x, y, z, "periodic");
252
253 // now evaluate on a bigger domain than [0,2pi]x [0,2pi]
254 m = 80; // discretisation parameter of the evaluation grid
255 xx = linspace(-0.5*%pi,2.5*%pi,m); yy = xx;
256 [XX,YY] = ndgrid(xx,yy);
257 zz3 = interp2d(XX,YY, x, y, C, "periodic");
258 plot3d(xx, yy, zz3, flag=[2 6 4])
259 xtitle("extrapolation with the periodic outmode")
260  ]]></programlisting>
261         <scilab:image>
262             n = 7;  // a n x n interpolation grid
263             x = linspace(0,2*%pi,n); y = x;
264             z = cos(x')*cos(y);
265             C = splin2d(x, y, z, "periodic");
266             
267             // now evaluate on a bigger domain than [0,2pi]x [0,2pi]
268             m = 80; // discretisation parameter of the evaluation grid
269             xx = linspace(-0.5*%pi,2.5*%pi,m); yy = xx;
270             [XX,YY] = ndgrid(xx,yy);
271             zz3 = interp2d(XX,YY, x, y, C, "periodic");
272             plot3d(xx, yy, zz3, flag=[2 6 4])
273             xtitle("extrapolation with the periodic outmode")
274         </scilab:image>
275         
276         <programlisting role="example"><![CDATA[
277 n = 7;  // a n x n interpolation grid
278 x = linspace(0,2*%pi,n); y = x;
279 z = cos(x')*cos(y);
280 C = splin2d(x, y, z, "periodic");
281
282 // now evaluate on a bigger domain than [0,2pi]x [0,2pi]
283 m = 80; // discretisation parameter of the evaluation grid
284 xx = linspace(-0.5*%pi,2.5*%pi,m); yy = xx;
285 [XX,YY] = ndgrid(xx,yy);
286 zz4 = interp2d(XX,YY, x, y, C, "natural");
287 plot3d(xx, yy, zz4, flag=[2 6 4])
288 xtitle("extrapolation with the natural outmode")
289  ]]></programlisting>
290         <scilab:image>
291             
292             n = 7;  // a n x n interpolation grid
293             x = linspace(0,2*%pi,n); y = x;
294             z = cos(x')*cos(y);
295             C = splin2d(x, y, z, "periodic");
296             
297             // now evaluate on a bigger domain than [0,2pi]x [0,2pi]
298             m = 80; // discretisation parameter of the evaluation grid
299             xx = linspace(-0.5*%pi,2.5*%pi,m); yy = xx;
300             [XX,YY] = ndgrid(xx,yy);
301             zz4 = interp2d(XX,YY, x, y, C, "natural");
302             plot3d(xx, yy, zz4, flag=[2 6 4])
303             xtitle("extrapolation with the natural outmode")
304         </scilab:image>
305     </refsection>
306     <refsection role="see also">
307         <title>See Also</title>
308         <simplelist type="inline">
309             <member>
310                 <link linkend="splin2d">splin2d</link>
311             </member>
312         </simplelist>
313     </refsection>
314     <refsection>
315         <title>History</title>
316         <revhistory>
317             <revision>
318                 <revnumber>5.4.0</revnumber>
319                 <revremark>Previously, imaginary part of input arguments were implicitly ignored.</revremark>
320             </revision>
321         </revhistory>
322     </refsection>
323 </refentry>