<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> 
<!DOCTYPE MAN SYSTEM "../../manrev.dtd">
<MAN>
  <LANGUAGE>eng</LANGUAGE>
  <TITLE>ndgrid</TITLE>
  <TYPE>Scilab Function</TYPE>
  <DATE>February 2004</DATE>
  <SHORT_DESCRIPTION name="ndgrid">arrays for multidimensional function evaluation on grid</SHORT_DESCRIPTION>

  <CALLING_SEQUENCE>
  <CALLING_SEQUENCE_ITEM>[X, Y] = ndgrid(x,y)</CALLING_SEQUENCE_ITEM>
  <CALLING_SEQUENCE_ITEM>[X, Y, Z] = ndgrid(x,y,z)</CALLING_SEQUENCE_ITEM>
  <CALLING_SEQUENCE_ITEM>[X, Y, Z, T] = ndgrid(x,y,z,t)</CALLING_SEQUENCE_ITEM>
  <CALLING_SEQUENCE_ITEM>[X1, X2, ..., Xm] = ndgrid(x1,x2,...,xm)</CALLING_SEQUENCE_ITEM>
  </CALLING_SEQUENCE>

  <PARAM>
    <PARAM_INDENT>
     <PARAM_ITEM>
        <PARAM_NAME>x, y, z, ...</PARAM_NAME>
        <PARAM_DESCRIPTION>
	 <SP>: vectors</SP>
	</PARAM_DESCRIPTION> 
     </PARAM_ITEM>
     <PARAM_ITEM>
        <PARAM_NAME>X, Y, Z, ...</PARAM_NAME>
        <PARAM_DESCRIPTION>
	 <SP>: matrices in case of 2 input arguments, or else hypermatrices</SP>
	</PARAM_DESCRIPTION> 
     </PARAM_ITEM>
   </PARAM_INDENT>
  </PARAM>
  
  <DESCRIPTION>
    <P>
    This is an utility routine useful to create arrays for function evaluation on 2, 3, ..., n 
    dimensional grids. For instance in 2d, a grid is defined by two vectors, <VERB>x</VERB> and
    <VERB> y</VERB> of length nx and ny, and you want to evaluate a function (says <EM>f</EM>) 
    on all the grid points, that is on all the points of coordinates  <EM>(x(i),y(j))</EM> 
    with  <EM>i=1,..,nx</EM> and <EM>j=1,..,ny</EM>. In this case, this function can
    compute the two matrices <VERB>X,Y</VERB> of size <EM>nx x ny</EM> such that :
    </P>
    <VERBATIM><![CDATA[
      X(i,j) = x(i)   for all i in [1,nx]
      Y(i,j) = y(j)       and j in [1,ny]
     ]]></VERBATIM>
    <P>
    and the evaluation may be done with <VERB>Z=f(X,Y)</VERB> (at the condition that you have 
    coded <VERB>f</VERB> for evaluation on vector arguments, which is done (in general) by 
    using the element-wise operators <VERB>.*</VERB>, <VERB>./</VERB> and <VERB>.^</VERB>
    in place of <VERB>*</VERB>, <VERB>/</VERB> and <VERB>^</VERB>).
    </P>
    <P>
    In the 3d case, considering 3 vectors <VERB>x,y,z</VERB> of length nx, ny and nz,  <VERB>X,Y,Z</VERB>
    are 3 hypermatrices  of size <EM>nx x ny x nz</EM> such that :
    </P>
    <VERBATIM><![CDATA[
      X(i,j,k) = x(i)  
      Y(i,j,k) = y(j)   for all (i,j,k) in [1,nx]x[1,ny]x[1,nz]
      Z(i,j,k) = z(k)
     ]]></VERBATIM>
    <P>
    In the general case of m input arguments <VERB>x1, x2, .., xm</VERB>, then
    the m output arguments <VERB>X1, X2, .., Xm</VERB> are hypermatrices  of size 
    <EM>nx1 x nx2 x ... x nxm</EM> and :
    </P>
    <VERBATIM><![CDATA[
    Xj(i1,i2,...,ij,...,im) = xj(ij)   
    for all (i1,i2,...,im) in [1,nx1]x[1,nx2]x...x[1,nxm]  
     ]]></VERBATIM>
    </DESCRIPTION>

  <EXAMPLE><![CDATA[
// create a simple 2d grid
nx = 40; ny = 40;
x = linspace(-1,1,nx);
y = linspace(-1,1,ny);
[X,Y] = ndgrid(x,y);
// compute a function on the grid and plot it
//deff("z=f(x,y)","z=128*x.^2 .*(1-x).^2 .*y.^2 .*(1-y).^2");
deff("z=f(x,y)","z=x.^2 + y.^3")
Z = f(X,Y);
xbasc()
plot3d(x,y,Z, flag=[2 6 4]); xselect()

// create a simple 3d grid
nx = 10; ny = 6; nz = 4;
x = linspace(0,2,nx);
y = linspace(0,1,ny);
z = linspace(0,0.5,nz);
[X,Y,Z] = ndgrid(x,y,z);
// try to display this 3d grid ...
XF=[]; YF=[]; ZF=[];
for k=1:nz
   [xf,yf,zf] = nf3d(X(:,:,k),Y(:,:,k),Z(:,:,k));
   XF = [XF xf]; YF = [YF yf]; ZF = [ZF zf];
end
for j=1:ny
   [xf,yf,zf] = nf3d(matrix(X(:,j,:),[nx,nz]),...
                     matrix(Y(:,j,:),[nx,nz]),...
                     matrix(Z(:,j,:),[nx,nz]));
   XF = [XF xf]; YF = [YF yf]; ZF = [ZF zf];
end
xbasc()
plot3d(XF,YF,ZF, flag=[0 6 3], leg="X@Y@Z")
xtitle("A 3d grid !"); xselect()
 ]]></EXAMPLE>

  <SEE_ALSO>
    <SEE_ALSO_ITEM>
      <LINK>kron</LINK>
    </SEE_ALSO_ITEM>
  </SEE_ALSO>

  <AUTHOR>
     B. Pincon
  </AUTHOR>

</MAN>
