Elementary function: move ndgrid to the right place after 6ad9efdc
[scilab.git] / scilab / modules / elementary_functions / help / en_US / elementarymatrices / ndgrid.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2
3 <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">
4     
5     <refnamediv>
6         
7         <refname>ndgrid</refname>
8         
9         <refpurpose>build matrices or N-D arrays by replicating some template vectors
10             
11         </refpurpose>
12         
13     </refnamediv>
14     
15     <refsynopsisdiv>
16         
17         <title>Calling Sequence</title>
18         
19         <synopsis>[X, Y] = ndgrid(x,y)
20             
21             [X, Y, Z] = ndgrid(x,y,z)
22             
23             [X, Y, Z, T] = ndgrid(x,y,z,t)
24             
25             [X1, X2, ..., Xm] = ndgrid(x1,x2,...,xm)
26             
27         </synopsis>
28         
29     </refsynopsisdiv>
30     
31     <refsection role="arguments">
32         
33         <title>Arguments</title>
34         
35         <variablelist>
36             
37             <varlistentry>
38                 
39                 <term>x, y, z, ...</term>
40                 
41                 <listitem>
42                     
43                     <para>vectors of any data types. They may have distinct data types.</para>
44                     
45                 </listitem>
46                 
47             </varlistentry>
48             
49             <varlistentry>
50                 
51                 <term>X, Y, Z, ...</term>
52                 
53                 <listitem>
54                     
55                     <para>matrices in case of 2 input arguments, or hypermatrices otherwise.
56                         
57                         They all have the same sizes: size(X,"*") rows, size(Y,"*") columns, 
58                         
59                         size(Z,"*") layers, etc. 
60                         
61                         They have the datatypes of respective input vectors:
62                         
63                         <literal>typeof(X)==typeof(x)</literal>, 
64                         
65                         <literal>typeof(Y)==typeof(y)</literal>, etc.
66                         
67                     </para>
68                     
69                 </listitem>
70                 
71             </varlistentry>
72             
73         </variablelist>
74         
75     </refsection>
76     
77     <refsection role="description">
78         
79         <title>Description</title>
80         
81         <para>
82             The first application of <function>ndgrid</function> is to build
83             
84             a grid of nodes meshing the 2D or 3D or N-D space according to 2, 3,
85             
86             or more sets
87             
88             <literal>x</literal>, <literal> y</literal>, etc.. of  
89             
90             "template" coordinates sampled along each direction/dimension of the
91             
92             space that you want to mesh.
93             
94         </para>
95         
96         <para>
97             Hence, the matrix or hypermatrix <literal>X</literal> is made
98             
99             by replicating the vector <literal>x</literal> as all its columns ; 
100             
101             the matrix or hypermatrix <literal>Y</literal> is made
102             
103             by replicating the vector <literal>y</literal> as all its rows ;
104             
105             <literal>Z</literal> is made of replicating the vector 
106             
107             <literal>z</literal> along all its local thicknesses (3rd dimension); 
108             
109             etc
110             
111         </para>
112         
113         <screen>
114             
115             <![CDATA[--> [X, Y] = ndgrid([1 3 4], [0 2 4 6])\r
116  X  = \r
117    1.   1.   1.   1.\r
118    3.   3.   3.   3.\r
119    4.   4.   4.   4.\r
120 \r
121    Y  = \r
122    0.   2.   4.   6.\r
123    0.   2.   4.   6.\r
124    0.   2.   4.   6.\r
125 ]]>
126         </screen>
127         
128         <para>  
129             
130             Then, the coordinates of the node(i,j) in the 2D space 
131             
132             will be
133             
134             simply <literal>[x(i), y(j)]</literal> now given by
135             
136             <literal>[X(i,j), Y(i,j)]</literal>. As well, the coordinates of a
137             
138             <literal>node(i,j,k)</literal> of a 3D grid will be 
139             
140             <literal>[x(i), y(j), z(k)]</literal> now given by 
141             
142             <literal>[X(i,j,k), Y(i,j,k), Z(i,j,k)]</literal>.
143             
144         </para>
145         
146         <para>
147             
148             This replication scheme can be generalized to any number of dimensions,
149             
150             as well to any type of uniform data. Let's for instance consider 2
151             
152             attributes:
153             
154             <orderedlist>
155                 
156                 <listitem>The first is a number, to be chosen from the vector say
157                     
158                     <literal>n = [ 3 7 ]</literal>
159                     
160                 </listitem>
161                 
162                 <listitem>The second is a letter, to be chosen from the vector 
163                     
164                     say <literal>c = ["a" "e" "i" "o" "u" "y"]</literal>
165                     
166                 </listitem>
167                 
168             </orderedlist>
169             
170             Then we want to build the set of all {n,c} possible pairs. It will
171             
172             just be the 2D grid:
173             
174         </para>
175         
176         <screen>
177             
178             <![CDATA[--> [N, C] = ndgrid([3 7],["a" "e" "i" "o" "u" "y"])\r
179  C  = \r
180 !a  e  i  o  u  y  !\r
181 !a  e  i  o  u  y  !\r
182 \r
183  N  = \r
184    3.   3.   3.   3.   3.   3.\r
185    7.   7.   7.   7.   7.   7.\r
186 ]]>
187         </screen>
188         
189         <para>Then, the object(i,j) will have the properties 
190             
191             <literal>{n(i) c(j)}</literal> that now can be addressed with
192             
193             <literal>{N(i,j) C(i,j)}</literal>.
194             
195             This kind of grid may be useful to initialize an array of structures.
196             
197         </para>
198         
199         <para>
200             Following examples show how to use <varname>X, Y, Z</varname> in
201             
202             most frequent applications.
203             
204         </para>
205          
206         
207     </refsection>
208     
209     <refsection role="examples">
210         
211         <title>Examples</title>
212         
213         <para>
214             <emphasis role="bold">Example #1:</emphasis> 
215         </para>
216         
217         <programlisting role="example"><![CDATA[  \r
218 // Create a simple 2d grid\r
219 x = linspace(-10,2,40);\r
220 y = linspace(-5,5,40);\r
221 [X,Y] = ndgrid(x,y);\r
222 \r
223 // Compute ordinates Z(X,Y) on the {X, Y} grid and plot Z(X,Y)\r
224 Z = X - 3*X.*sin(X).*cos(Y-4) ;\r
225 clf()\r
226 plot3d(x,y,Z, flag=[color("green") 2 4], alpha=7, theta=60); show_window()\r
227  ]]></programlisting>
228         
229         <scilab:image>
230             
231             x = linspace(-10,2,40);
232             
233             y = linspace(-5,5,40);
234             
235             [X,Y] = ndgrid(x,y);
236             
237             Z = X - 3*X.*sin(X).*cos(Y-4) ;
238             
239             clf()
240             
241             plot3d(x,y,Z, flag=[color("green") 2 4], alpha=7, theta=60); show_window()
242             
243         </scilab:image>
244         
245         <para>
246             <emphasis role="bold">Example #2:</emphasis> 
247         </para>
248         
249         <programlisting role="example"><![CDATA[  \r
250 // Create a simple 3d grid\r
251 nx = 10; ny = 6; nz = 4;\r
252 x = linspace(0,2,nx);\r
253 y = linspace(0,1,ny);\r
254 z = linspace(0,0.5,nz);\r
255 [X,Y,Z] = ndgrid(x,y,z);\r
256 \r
257 // Try to display this 3d grid ...\r
258 XF=[]; YF=[]; ZF=[];\r
259 \r
260 for k=1:nz\r
261    [xf,yf,zf] = nf3d(X(:,:,k),Y(:,:,k),Z(:,:,k));\r
262    XF = [XF xf]; YF = [YF yf]; ZF = [ZF zf];\r
263 end\r
264 \r
265 for j=1:ny\r
266    [xf,yf,zf] = nf3d(matrix(X(:,j,:),[nx,nz]),...\r
267                      matrix(Y(:,j,:),[nx,nz]),...\r
268                      matrix(Z(:,j,:),[nx,nz]));\r
269    XF = [XF xf]; YF = [YF yf]; ZF = [ZF zf];\r
270 end\r
271 \r
272 clf()\r
273 plot3d(XF,YF,ZF, flag=[0 6 3], 66, 61,leg="X@Y@Z")\r
274 xtitle("A 3d grid !"); show_window()\r
275  ]]></programlisting>
276         
277         <scilab:image>
278             
279             nx = 10; ny = 6; nz = 4;
280             
281             x = linspace(0,2,nx);
282             
283             y = linspace(0,1,ny);
284             
285             z = linspace(0,0.5,nz);
286             
287             [X,Y,Z] = ndgrid(x,y,z);
288             
289             
290             
291             XF=[]; YF=[]; ZF=[];
292             
293             
294             
295             for k=1:nz
296             
297             [xf,yf,zf] = nf3d(X(:,:,k),Y(:,:,k),Z(:,:,k));
298             
299             XF = [XF xf]; YF = [YF yf]; ZF = [ZF zf];
300             
301             end
302             
303             
304             
305             for j=1:ny
306             
307             [xf,yf,zf] = nf3d(matrix(X(:,j,:),[nx,nz]),...
308             
309             matrix(Y(:,j,:),[nx,nz]),...
310             
311             matrix(Z(:,j,:),[nx,nz]));
312             
313             XF = [XF xf]; YF = [YF yf]; ZF = [ZF zf];
314             
315             end
316             
317             plot3d(XF,YF,ZF, flag=[0 6 3], 66, 61, leg="X@Y@Z")
318             
319             xtitle("A 3d grid !"); 
320             
321         </scilab:image>
322         
323         
324         
325         <para>
326             <emphasis role="bold">Example #3: Creates a table of digrams:</emphasis> 
327         </para>
328         
329         <programlisting role="example"><![CDATA[  \r
330 [c1, c2] = ndgrid(["a" "b" "c"], ["a" "b" "c" "d" "e" "f" "g" "h"])\r
331 c1+c2\r
332  ]]></programlisting>
333         
334         <screen>
335             
336             <![CDATA[--> [c1, c2] = ndgrid(["a" "b" "c"], ["a" "b" "c" "d" "e" "f" "g" "h"])\r
337  c2  = \r
338 !a  b  c  d  e  f  g  h  !\r
339 !a  b  c  d  e  f  g  h  !\r
340 !a  b  c  d  e  f  g  h  !\r
341 \r
342  c1  = \r
343 !a  a  a  a  a  a  a  a  !\r
344 !b  b  b  b  b  b  b  b  !\r
345 !c  c  c  c  c  c  c  c  !\r
346 \r
347 --> c1+c2\r
348  ans  =\r
349 !aa  ab  ac  ad  ae  af  ag  ah  !\r
350 !ba  bb  bc  bd  be  bf  bg  bh  !\r
351 !ca  cb  cc  cd  ce  cf  cg  ch  !\r
352 ]]>
353         </screen>
354         
355     </refsection>
356     
357     <refsection role="see also">
358         
359         <title>See Also</title>
360         
361         <simplelist type="inline">
362             
363             <member>
364                 
365                 <link linkend="meshgrid">meshgrid</link>
366                 
367             </member>
368             
369             <member>
370                 
371                 <link linkend="kron">kron</link>
372                 
373             </member>
374             
375             <member>
376                 
377                 <link linkend="feval">feval</link>
378                 
379             </member>
380             
381             <member>
382                 
383                 <link linkend="eval3d">eval3d</link>
384                 
385             </member>
386             
387             <member>
388                 
389                 <link linkend="nf3d">nf3d</link>
390                 
391             </member>
392             
393         </simplelist>
394         
395     </refsection>
396     
397     <refsection role="history">
398         
399         <title>History</title>
400         
401         <revhistory>
402             
403             <revision>
404                 
405                 <revnumber>6.0</revnumber>
406                 
407                 <revdescription>Extension to all homogeneous datatypes ([], 
408                     
409                     booleans, encoded integers, polynomials, rationals, strings). 
410                     
411                     Revision of the help page.
412                     
413                 </revdescription>
414                 
415             </revision>
416             
417         </revhistory>
418         
419     </refsection>
420     
421 </refentry>
422