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