scilab/modules/elementary_functions/help/en_US/ndgrid.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   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="ndgrid" xml:lang="en">\r
   3     <refnamediv>\r
   4         <refname>ndgrid</refname>\r
   5         <refpurpose>build matrices or N-D arrays by replicating some template vectors\r
   6         </refpurpose>\r
   7     </refnamediv>\r
   8     <refsynopsisdiv>\r
   9         <title>Calling Sequence</title>\r
  10         <synopsis>[X, Y] = ndgrid(x,y)\r
  11             [X, Y, Z] = ndgrid(x,y,z)\r
  12             [X, Y, Z, T] = ndgrid(x,y,z,t)\r
  13             [X1, X2, ..., Xm] = ndgrid(x1,x2,...,xm)\r
  14         </synopsis>\r
  15     </refsynopsisdiv>\r
  16     <refsection role="arguments">\r
  17         <title>Arguments</title>\r
  18         <variablelist>\r
  19             <varlistentry>\r
  20                 <term>x, y, z, ...</term>\r
  21                 <listitem>\r
  22                     <para>vectors of any data types. They may have distinct data types.</para>\r
  23                 </listitem>\r
  24             </varlistentry>\r
  25             <varlistentry>\r
  26                 <term>X, Y, Z, ...</term>\r
  27                 <listitem>\r
  28                     <para>matrices in case of 2 input arguments, or hypermatrices otherwise.\r
  29                     They all have the same sizes: size(X,"*") rows, size(Y,"*") columns, \r
  30                         size(Z,"*") layers, etc. \r
  31                         They have the datatypes of respective input vectors:\r
  32                         <literal>typeof(X)==typeof(x)</literal>, \r
  33                         <literal>typeof(Y)==typeof(y)</literal>, etc.\r
  34                     </para>\r
  35                 </listitem>\r
  36             </varlistentry>\r
  37         </variablelist>\r
  38     </refsection>\r
  39     <refsection role="description">\r
  40         <title>Description</title>\r
  41         <para>The first application of <function>ndgrid</function> is to build\r
  42             a grid of nodes meshing the 2D or 3D or N-D space according to 2, 3,\r
  43             or more sets\r
  44             <literal>x</literal>, <literal> y</literal>, etc.. of  \r
  45             "template" coordinates sampled along each direction/dimension of the\r
  46             space that you want to mesh.\r
  47         </para>\r
  48         <para>Hence, the matrix or hypermatrix <literal>X</literal> is made\r
  49             by replicating the vector <literal>x</literal> as all its columns ; \r
  50             the matrix or hypermatrix <literal>Y</literal> is made\r
  51             by replicating the vector <literal>y</literal> as all its rows ;\r
  52             <literal>Z</literal> is made of replicating the vector \r
  53             <literal>z</literal> along all its local thicknesses (3rd dimension); \r
  54             etc\r
  55         </para>\r
  56         <screen>\r
  57 <![CDATA[--> [X, Y] = ndgrid([1 3 4], [0 2 4 6])\r
  58  X  = \r
  59    1.   1.   1.   1.\r
  60    3.   3.   3.   3.\r
  61    4.   4.   4.   4.\r
  62 \r
  63    Y  = \r
  64    0.   2.   4.   6.\r
  65    0.   2.   4.   6.\r
  66    0.   2.   4.   6.\r
  67 ]]></screen>\r
  68         <para>  \r
  69             Then, the coordinates of the node(i,j) in the 2D space \r
  70             will be\r
  71             simply <literal>[x(i), y(j)]</literal> now given by\r
  72             <literal>[X(i,j), Y(i,j)]</literal>. As well, the coordinates of a\r
  73             <literal>node(i,j,k)</literal> of a 3D grid will be \r
  74             <literal>[x(i), y(j), z(k)]</literal> now given by \r
  75             <literal>[X(i,j,k), Y(i,j,k), Z(i,j,k)]</literal>.\r
  76         </para>\r
  77         <para>\r
  78             This replication scheme can be generalized to any number of dimensions,\r
  79             as well to any type of uniform data. Let's for instance consider 2\r
  80             attributes:\r
  81             <orderedlist>\r
  82                 <listitem>The first is a number, to be chosen from the vector say\r
  83                 <literal>n = [ 3 7 ]</literal>\r
  84                 </listitem>\r
  85                 <listitem>The second is a letter, to be chosen from the vector \r
  86                 say <literal>c = ["a" "e" "i" "o" "u" "y"]</literal>\r
  87                 </listitem>\r
  88             </orderedlist>\r
  89             Then we want to build the set of all {n,c} possible pairs. It will\r
  90             just be the 2D grid:\r
  91         </para>\r
  92         <screen>\r
  93 <![CDATA[--> [N, C] = ndgrid([3 7],["a" "e" "i" "o" "u" "y"])\r
  94  C  = \r
  95 !a  e  i  o  u  y  !\r
  96 !a  e  i  o  u  y  !\r
  97 \r
  98  N  = \r
  99    3.   3.   3.   3.   3.   3.\r
 100    7.   7.   7.   7.   7.   7.\r
 101 ]]></screen>\r
 102         <para>Then, the object(i,j) will have the properties \r
 103         <literal>{n(i) c(j)}</literal> that now can be addressed with\r
 104         <literal>{N(i,j) C(i,j)}</literal>.\r
 105         This kind of grid may be useful to initialize an array of structures.\r
 106         </para>\r
 107         <para>Following examples show how to use <varname>X, Y, Z</varname> in\r
 108         most frequent applications.\r
 109         </para> \r
 110     </refsection>\r
 111     <refsection role="examples">\r
 112         <title>Examples</title>\r
 113         <para><emphasis role="bold">Example #1:</emphasis> </para>\r
 114         <programlisting role="example"><![CDATA[  \r
 115 // Create a simple 2d grid\r
 116 x = linspace(-10,2,40);\r
 117 y = linspace(-5,5,40);\r
 118 [X,Y] = ndgrid(x,y);\r
 119 \r
 120 // Compute ordinates Z(X,Y) on the {X, Y} grid and plot Z(X,Y)\r
 121 Z = X - 3*X.*sin(X).*cos(Y-4) ;\r
 122 clf()\r
 123 plot3d(x,y,Z, flag=[color("green") 2 4], alpha=7, theta=60); show_window()\r
 124  ]]></programlisting>\r
 125         <scilab:image>\r
 126         x = linspace(-10,2,40);\r
 127         y = linspace(-5,5,40);\r
 128         [X,Y] = ndgrid(x,y);\r
 129         Z = X - 3*X.*sin(X).*cos(Y-4) ;\r
 130         clf()\r
 131         plot3d(x,y,Z, flag=[color("green") 2 4], alpha=7, theta=60); show_window()\r
 132         </scilab:image>\r
 133         <para><emphasis role="bold">Example #2:</emphasis> </para>\r
 134         <programlisting role="example"><![CDATA[  \r
 135 // Create a simple 3d grid\r
 136 nx = 10; ny = 6; nz = 4;\r
 137 x = linspace(0,2,nx);\r
 138 y = linspace(0,1,ny);\r
 139 z = linspace(0,0.5,nz);\r
 140 [X,Y,Z] = ndgrid(x,y,z);\r
 141 \r
 142 // Try to display this 3d grid ...\r
 143 XF=[]; YF=[]; ZF=[];\r
 144 \r
 145 for k=1:nz\r
 146    [xf,yf,zf] = nf3d(X(:,:,k),Y(:,:,k),Z(:,:,k));\r
 147    XF = [XF xf]; YF = [YF yf]; ZF = [ZF zf];\r
 148 end\r
 149 \r
 150 for j=1:ny\r
 151    [xf,yf,zf] = nf3d(matrix(X(:,j,:),[nx,nz]),...\r
 152                      matrix(Y(:,j,:),[nx,nz]),...\r
 153                      matrix(Z(:,j,:),[nx,nz]));\r
 154    XF = [XF xf]; YF = [YF yf]; ZF = [ZF zf];\r
 155 end\r
 156 \r
 157 clf()\r
 158 plot3d(XF,YF,ZF, flag=[0 6 3], 66, 61,leg="X@Y@Z")\r
 159 xtitle("A 3d grid !"); show_window()\r
 160  ]]></programlisting>\r
 161         <scilab:image>\r
 162             nx = 10; ny = 6; nz = 4;\r
 163             x = linspace(0,2,nx);\r
 164             y = linspace(0,1,ny);\r
 165             z = linspace(0,0.5,nz);\r
 166             [X,Y,Z] = ndgrid(x,y,z);\r
 167             \r
 168             XF=[]; YF=[]; ZF=[];\r
 169             \r
 170             for k=1:nz\r
 171             [xf,yf,zf] = nf3d(X(:,:,k),Y(:,:,k),Z(:,:,k));\r
 172             XF = [XF xf]; YF = [YF yf]; ZF = [ZF zf];\r
 173             end\r
 174             \r
 175             for j=1:ny\r
 176             [xf,yf,zf] = nf3d(matrix(X(:,j,:),[nx,nz]),...\r
 177             matrix(Y(:,j,:),[nx,nz]),...\r
 178             matrix(Z(:,j,:),[nx,nz]));\r
 179             XF = [XF xf]; YF = [YF yf]; ZF = [ZF zf];\r
 180             end\r
 181             plot3d(XF,YF,ZF, flag=[0 6 3], 66, 61, leg="X@Y@Z")\r
 182             xtitle("A 3d grid !"); \r
 183         </scilab:image>\r
 184 \r
 185         <para><emphasis role="bold">Example #3: Creates a table of digrams:</emphasis> </para>\r
 186         <programlisting role="example"><![CDATA[  \r
 187 [c1, c2] = ndgrid(["a" "b" "c"], ["a" "b" "c" "d" "e" "f" "g" "h"])\r
 188 c1+c2\r
 189  ]]></programlisting>\r
 190     <screen>\r
 191 <![CDATA[--> [c1, c2] = ndgrid(["a" "b" "c"], ["a" "b" "c" "d" "e" "f" "g" "h"])\r
 192  c2  = \r
 193 !a  b  c  d  e  f  g  h  !\r
 194 !a  b  c  d  e  f  g  h  !\r
 195 !a  b  c  d  e  f  g  h  !\r
 196 \r
 197  c1  = \r
 198 !a  a  a  a  a  a  a  a  !\r
 199 !b  b  b  b  b  b  b  b  !\r
 200 !c  c  c  c  c  c  c  c  !\r
 201 \r
 202 --> c1+c2\r
 203  ans  =\r
 204 !aa  ab  ac  ad  ae  af  ag  ah  !\r
 205 !ba  bb  bc  bd  be  bf  bg  bh  !\r
 206 !ca  cb  cc  cd  ce  cf  cg  ch  !\r
 207 ]]></screen>\r
 208     </refsection>\r
 209     <refsection role="see also">\r
 210         <title>See Also</title>\r
 211         <simplelist type="inline">\r
 212             <member>\r
 213                 <link linkend="meshgrid">meshgrid</link>\r
 214             </member>\r
 215             <member>\r
 216                 <link linkend="kron">kron</link>\r
 217             </member>\r
 218             <member>\r
 219                 <link linkend="feval">feval</link>\r
 220             </member>\r
 221             <member>\r
 222                 <link linkend="eval3d">eval3d</link>\r
 223             </member>\r
 224             <member>\r
 225                 <link linkend="nf3d">nf3d</link>\r
 226             </member>\r
 227         </simplelist>\r
 228     </refsection>\r
 229     <refsection role="history">\r
 230         <title>History</title>\r
 231         <revhistory>\r
 232             <revision>\r
 233                 <revnumber>6.0</revnumber>\r
 234                 <revdescription>Extension to all homogeneous datatypes ([], \r
 235                 booleans, encoded integers, polynomials, rationals, strings). \r
 236                 Revision of the help page.\r
 237                 </revdescription>\r
 238             </revision>\r
 239         </revhistory>\r
 240     </refsection>\r
 241 </refentry>\r