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>