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