Remove all the authors from the documentation. This has been done for the following...
[scilab.git] / scilab / modules / elementary_functions / help / en_US / elementarymatrices / ndgrid.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" version="5.0-subset Scilab" xml:id="ndgrid" xml:lang="en">
3   <info>
4     <pubdate>$LastChangedDate$</pubdate>
5   </info>
6   <refnamediv>
7     <refname>ndgrid</refname>
8     <refpurpose>arrays for multidimensional function evaluation on
9       grid
10     </refpurpose>
11   </refnamediv>
12   <refsynopsisdiv>
13     <title>Calling Sequence</title>
14     <synopsis>[X, Y] = ndgrid(x,y)
15       [X, Y, Z] = ndgrid(x,y,z)
16       [X, Y, Z, T] = ndgrid(x,y,z,t)
17       [X1, X2, ..., Xm] = ndgrid(x1,x2,...,xm)
18     </synopsis>
19   </refsynopsisdiv>
20   <refsection>
21     <title>Arguments</title>
22     <variablelist>
23       <varlistentry>
24         <term>x, y, z, ...</term>
25         <listitem>
26           <para>vectors</para>
27         </listitem>
28       </varlistentry>
29       <varlistentry>
30         <term>X, Y, Z, ...</term>
31         <listitem>
32           <para>matrices in case of 2 input arguments, or else
33             hypermatrices
34           </para>
35         </listitem>
36       </varlistentry>
37     </variablelist>
38   </refsection>
39   <refsection>
40     <title>Description</title>
41     <para>This is an utility routine useful to create arrays for function
42       evaluation on 2, 3, ..., n dimensional grids. For instance in 2d, a grid
43       is defined by two vectors, <literal>x</literal> and <literal> y</literal>
44       of length nx and ny, and you want to evaluate a function (says
45       <emphasis>f</emphasis>) on all the grid points, that is on all the points
46       of coordinates <emphasis>(x(i),y(j))</emphasis> with
47       <emphasis>i=1,..,nx</emphasis> and <emphasis>j=1,..,ny</emphasis>. In this
48       case, this function can compute the two matrices <literal>X,Y</literal> of
49       size <emphasis>nx x ny</emphasis> such that :
50     </para>
51     <programlisting><![CDATA[ 
52 X(i,j) = x(i)   for all i in [1,nx]
53 Y(i,j) = y(j)       and j in [1,ny]
54  ]]></programlisting>
55     <para>
56       and the evaluation may be done with <literal>Z=f(X,Y)</literal> (at
57       the condition that you have coded <literal>f</literal> for evaluation on
58       vector arguments, which is done (in general) by using the element-wise
59       operators <literal>.*</literal>, <literal>./</literal> and
60       <literal>.^</literal> in place of <literal>*</literal>,
61       <literal>/</literal> and <literal>^</literal>).
62     </para>
63     <para>
64       In the 3d case, considering 3 vectors <literal>x,y,z</literal> of
65       length nx, ny and nz, <literal>X,Y,Z</literal> are 3 hypermatrices of size
66       <emphasis>nx x ny x nz</emphasis> such that :
67     </para>
68     <programlisting><![CDATA[ 
69 X(i,j,k) = x(i)  
70 Y(i,j,k) = y(j)   for all (i,j,k) in [1,nx]x[1,ny]x[1,nz]
71 Z(i,j,k) = z(k)
72  ]]></programlisting>
73     <para>
74       In the general case of m input arguments <literal>x1, x2, ..,
75         xm
76       </literal>
77       ,then the m output arguments <literal>X1, X2, ..,
78         Xm
79       </literal>
80       are hypermatrices of size <emphasis>nx1 x nx2 x ... x
81         nxm
82       </emphasis>
83       and :
84     </para>
85     <programlisting><![CDATA[ 
86 Xj(i1,i2,...,ij,...,im) = xj(ij)   
87 for all (i1,i2,...,im) in [1,nx1]x[1,nx2]x...x[1,nxm]  
88  ]]></programlisting>
89   </refsection>
90   <refsection>
91     <title>Examples</title>
92     <programlisting role="example"><![CDATA[  
93 // create a simple 2d grid
94 nx = 40; ny = 40;
95 x = linspace(-1,1,nx);
96 y = linspace(-1,1,ny);
97 [X,Y] = ndgrid(x,y);
98
99 // compute a function on the grid and plot it
100 //deff("z=f(x,y)","z=128*x.^2 .*(1-x).^2 .*y.^2 .*(1-y).^2");
101 deff("z=f(x,y)","z=x.^2 + y.^3")
102 Z = f(X,Y);
103 clf()
104 plot3d(x,y,Z, flag=[2 6 4]); show_window()
105
106 // create a simple 3d grid
107 nx = 10; ny = 6; nz = 4;
108 x = linspace(0,2,nx);
109 y = linspace(0,1,ny);
110 z = linspace(0,0.5,nz);
111 [X,Y,Z] = ndgrid(x,y,z);
112
113 // try to display this 3d grid ...
114 XF=[]; YF=[]; ZF=[];
115
116 for k=1:nz
117    [xf,yf,zf] = nf3d(X(:,:,k),Y(:,:,k),Z(:,:,k));
118    XF = [XF xf]; YF = [YF yf]; ZF = [ZF zf];
119 end
120
121 for j=1:ny
122    [xf,yf,zf] = nf3d(matrix(X(:,j,:),[nx,nz]),...
123                      matrix(Y(:,j,:),[nx,nz]),...
124                      matrix(Z(:,j,:),[nx,nz]));
125    XF = [XF xf]; YF = [YF yf]; ZF = [ZF zf];
126 end
127
128 clf()
129 plot3d(XF,YF,ZF, flag=[0 6 3], leg="X@Y@Z")
130 xtitle("A 3d grid !"); show_window()
131  ]]></programlisting>
132   </refsection>
133   <refsection role="see also">
134     <title>See Also</title>
135     <simplelist type="inline">
136       <member>
137         <link linkend="kron">kron</link>
138       </member>
139     </simplelist>
140   </refsection>
141 </refentry>