c2cd6bf19159e5d8c2f105235df91f5bbe4e0473
[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         <programlisting role="example"><![CDATA[ 
190 // see the examples of splin2d
191
192 // this example shows some different extrapolation features
193 // interpolation of cos(x)cos(y)
194 n = 7;  // a n x n interpolation grid
195 x = linspace(0,2*%pi,n); y = x;
196 z = cos(x')*cos(y);
197 C = splin2d(x, y, z, "periodic");
198
199 // now evaluate on a bigger domain than [0,2pi]x [0,2pi]
200 m = 80; // discretisation parameter of the evaluation grid
201 xx = linspace(-0.5*%pi,2.5*%pi,m); yy = xx;
202 [XX,YY] = ndgrid(xx,yy);
203 zz1 = interp2d(XX,YY, x, y, C, "C0");
204 zz2 = interp2d(XX,YY, x, y, C, "by_zero");
205 zz3 = interp2d(XX,YY, x, y, C, "periodic");
206 zz4 = interp2d(XX,YY, x, y, C, "natural");
207 clf()
208 subplot(2,2,1)
209 plot3d(xx, yy, zz1, flag=[2 6 4])
210 xtitle("extrapolation with the C0 outmode")
211 subplot(2,2,2)
212 plot3d(xx, yy, zz2, flag=[2 6 4])
213 xtitle("extrapolation with the by_zero outmode")
214 subplot(2,2,3)
215 plot3d(xx, yy, zz3, flag=[2 6 4])
216 xtitle("extrapolation with the periodic outmode")
217 subplot(2,2,4)
218 plot3d(xx, yy, zz4, flag=[2 6 4])
219 xtitle("extrapolation with the natural outmode")
220 show_window()
221  ]]></programlisting>
222         <scilab:image>
223             n = 7;  // a n x n interpolation grid
224             x = linspace(0,2*%pi,n); y = x;
225             z = cos(x')*cos(y);
226             C = splin2d(x, y, z, "periodic");
227             
228             // now evaluate on a bigger domain than [0,2pi]x [0,2pi]
229             m = 80; // discretisation parameter of the evaluation grid
230             xx = linspace(-0.5*%pi,2.5*%pi,m); yy = xx;
231             [XX,YY] = ndgrid(xx,yy);
232             zz1 = interp2d(XX,YY, x, y, C, "C0");
233             zz2 = interp2d(XX,YY, x, y, C, "by_zero");
234             zz3 = interp2d(XX,YY, x, y, C, "periodic");
235             zz4 = interp2d(XX,YY, x, y, C, "natural");
236             clf()
237             subplot(2,2,1)
238             plot3d(xx, yy, zz1, flag=[2 6 4])
239             xtitle("extrapolation with the C0 outmode")
240             subplot(2,2,2)
241             plot3d(xx, yy, zz2, flag=[2 6 4])
242             xtitle("extrapolation with the by_zero outmode")
243             subplot(2,2,3)
244             plot3d(xx, yy, zz3, flag=[2 6 4])
245             xtitle("extrapolation with the periodic outmode")
246             subplot(2,2,4)
247             plot3d(xx, yy, zz4, flag=[2 6 4])
248             xtitle("extrapolation with the natural outmode")
249             show_window()
250         </scilab:image>
251     </refsection>
252     <refsection role="see also">
253         <title>See Also</title>
254         <simplelist type="inline">
255             <member>
256                 <link linkend="splin2d">splin2d</link>
257             </member>
258         </simplelist>
259     </refsection>
260     <refsection>
261         <title>History</title>
262         <revhistory>
263             <revision>
264                 <revnumber>5.4.0</revnumber>
265                 <revremark>previously, imaginary part of input arguments were implicitly ignored.</revremark>
266             </revision>
267         </revhistory>
268     </refsection>
269 </refentry>