% $Id: tutTemplateStart.tex 1510 2007-08-17 09:26:16Z paultcochrane $

% Copyright (C) 2000-2007
%
% Code contributed by Greg Collecutt, Joseph Hope and the xmds-devel team
%
% This file is part of xmds.
%
% This program is free software; you can redistribute it and/or
% modify it under the terms of the GNU General Public License
% as published by the Free Software Foundation; either version 2
% of the License, or (at your option) any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program; if not, write to the Free Software 
% Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.

\chapter{Using a template}
\label{chap:usingATemplate}

In this tutorial, we're going to hack an \xmds template to pieces to
write a simulation script.  This is possibly one of the easiest ways
to make an \xmds simulation script; almost everything has been done
for you, and all that is left for you to do is to translate the
equations into something a C/C++ compiler could understand.  This
tutorial builds upon the skills learnt in \Chap{chap:tutFromScratch}
and from the knowledge (of the existence of, at least) of the extra tags
discussed in \Chap{chap:extraAndAdvancedFeatures}.

\section{The advection equation}
\label{sec:theAdvectionEquation}

But first, the problem.  Here we'll solve the one dimensional
advection equation
\begin{equation}
\frac{\del}{\del t} A(x,t) = -v \frac{\del}{\del x} A(x,t),
\label{eq:advectionEquation}
\end{equation}
where $A(x,t)$ is the field to evolve according to the differential
equation, $x$ is the spatial dimension, $t$ is time, and $v$ is the
velocity of the wave.  As with the two examples discussed in
\Chap{chap:tutFromScratch}, this example is adapted from that in
Garcia~\cite{Garcia:1994:1}.  

We shall use in this example an initial pulse which is a
cosine-modulated Gaussian:
\begin{equation}
A(x,t=0) = \cos[k(x-x_0)] \exp\left[-\frac{(x-x_0)^2}{2\sigma^2}\right],
\label{eq:cosineModulatedGaussian}
\end{equation}
where $k = 2\pi/\lambda$ is the wave number of the pulse, which has a
wavelength $\lambda$, $x_0$ is the initial peak position of the pulse,
and $\sigma$ is the initial pulse width (standard deviation).  This
initial condition has an analytical solution (which we give here
merely for interest value)
\begin{align}
  A(x,t) &= \cos\{k[(x - vt) - x_0]\} 
    \exp\left\{-\frac{[(x - vt) - x_0]^2}{2\sigma^2}\right\}\\
  &= \cos\{k[x - (x_0 + vt)]\} 
    \exp\left\{-\frac{[x - (x_0 + vt)]^2}{2\sigma^2}\right\},
\label{eq:cosineModulatedGaussianSolution}
\end{align}
which is still a cosine-modulated Gaussian, just displaced by an
amount $vt$.

The boundary conditions we shall use are periodic, and since we get
this for free when using \xmds, there isn't anything special we need
to do here, other than to keep in mind that the boundary conditions
are periodic.  As with the diffusion equation example, we'll make the
$x$ domain go from -0.5 to 0.5, we'll set the value of $\sigma$ to 0.1,
and $x_0$ to 0.  The wave speed we'll set to 1.  Any other parameters
will be mentioned as we go through and hack with the code.

\section{The template code}

Here is the code that we're going to hack with.  This is just an
outline of many of the tags that we can use to perform a simulation
using \xmds.  Most of them you should know by now, but one or two you
may be unfamiliar with, this is ok, as we don't need them for what we
want to do.  Comments have been put all through the document to give a
better idea of what the tags do and what their default value is (if any).

\begin{xmdsCode}
<?xml version="1.0"?>
<simulation>

  <!-- Global system parameters and functionality -->
  <name> </name>      <!-- the name of the simulation -->
  <author> </author>  <!-- the author of the simulation -->
  <description>
    <!-- a description of what the simulation is supposed to do -->
  </description>

  <prop_dim> </prop_dim>    <!-- name of main propagation dim -->

  <stochastic> no </stochastic>  <!-- defaults to no -->
  <!-- these three tags only necessary when stochastic is yes -->
  <paths> </paths>               <!-- no. of paths -->
  <seed> 1 2 </seed>             <!-- seeds for rand no. gen -->
  <noises> </noises>             <!-- no. of noises -->

  <use_mpi> no </use_mpi>            <!-- defaults to no -->
  <error_check> yes </error_check>   <!-- defaults to yes -->
  <use_wisdom> yes </use_wisdom>     <!-- defaults to no -->
  <benchmark> yes </benchmark>       <!-- defaults to no -->
  <use_prefs> yes </use_prefs>       <!-- defaults to yes -->

  <!-- Global variables for the simulation -->
  <globals>
  <![CDATA[
      
  ]]>
  </globals>

  <!-- Field to be integrated over -->
  <field>
    <name> main </name>
    <dimensions> </dimensions> <!-- transverse dims -->
    <lattice> </lattice>       <!-- no. of points for each dim -->
    <domains> (,) </domains>   <!-- domain of each dimension -->
    <samples> </samples>       <!-- sample 1st point of dim? -->
    
    <vector>
      <name> main </name>
      <type> complex </type>           <!-- data type of vector -->
      <components> </components>       <!-- names of components -->
      <fourier_space> </fourier_space> <!-- defined in k-space? -->
      <![CDATA[
	  
      ]]>
    </vector>
  </field>

  <!-- The sequence of integrations to perform -->
  <sequence>
    <integrate>
      <algorithm> </algorithm> <!-- RK4EX, RK4IP, ARK45EX, ARK45IP, SIEX, SIIP -->
      <iterations> </iterations> <!-- default=3 for SI- algs -->
      <interval> </interval>   <!-- how far in main dim? -->
      <lattice> </lattice>     <!-- no. points in main dim -->
      <samples> </samples> <!-- no. pts in output moment group -->
      
      <k_operators>
        <constant> yes </constant>         <!-- yes/no -->
	<operator_names> </operator_names>
	<![CDATA[
	    
	]]>
      </k_operators>
      
      <vectors> </vectors>     <!-- vector names -->
      <![CDATA[
	  
      ]]>
    </integrate>
  </sequence>

  <!-- The output to generate -->
  <output format="binary" precision="single">
    <group>
      <sampling>
        <fourier_space> </fourier_space> <!-- sample in k-space? -->
	<lattice> </lattice>           <!-- no. points to sample -->
	<moments> </moments>           <!-- names of moments -->
	<![CDATA[
	    
	]]>
      </sampling>
    </group>
  </output>

</simulation>
\end{xmdsCode}

\section{Ripping it to bits}

Now all we need to do is to work out what we need and don't need, and
to throw the relevant numbers and equations into the relevant places.
If the pace is too high, you might like to go back and re-read
\Chap{chap:tutFromScratch} to make sure you got it all.

\subsection{Global system parameters and functionality}

Looking at the block of code that sits between the
start \xmdsTag{simulation} tag and the \xmdsTag{globals} element, we
can add the following things: the name of the simulation is
\ttt{advection}, the author is \ttt{Paul Cochrane}, and the
description can be something like:
\begin{xmdsCode}
<description>
  Solves the one-dimensional advection equation for an initial 
  cosine-modulated Gaussian pulse.  
  Adapted from A. L. Garcia, "Numerical Methods in Physics" (1994).
</description>
\end{xmdsCode}

The propagation dimension is in time, so we set \xmdsTag{prop\_dim} to
\ttt{t}, the simulation \emph{isn't} stochastic, so we can leave the
code where it is, or remove it since it's set to the default setting
anyway.  We'll remove it in this case as we don't gain anything, and
it's extra code floating around that we don't need.  Since this isn't
a stochastic simulation, this implies that the \xmdsTag{paths},
\xmdsTag{seed} and \xmdsTag{noises} tags are unnecessary.  Also, we
don't need the \xmdsTag{use\_mpi} tag either, because we've not met it
before, the simulation is not stochastic, so making it use MPI (the
message passing interface for parallel simulations) is a waste of
time, and the default setting is off, so again, we rip this tag out.

We might as well leave error checking on (it's the default anyway),
and leave the \xmdsTag{error\_check} tag the way it is.  This is
especially important at the early stages of writing a simulation, as
one can then get an indication of the discretisation error of the
simulation and this information can tell us how to tweak the
simulation parameters if necessary.  Leaving the
\xmdsTag{error\_check} tag in the code is a good idea, as we'll
probably want to switch it off at some later stage, and if we leave it
in the code we can remember to do this if we want.

We definitely want to use FFTW's wisdom feature.  This is because we
have a differential in space, and it is nice and easy to define the
operator in $k$-space, implying that we'll need to use Fourier
transforms, and using ``wisdom'' speeds up the startup time of our
simulations.  Hence, we leave \xmdsTag{use\_wisdom} as is.

Benchmarking the code doesn't take up much room in the script, nor
does it take up much time in the code, and it can be interesting to
have around, so we'll leave the \xmdsTag{benchmark} tag there.
However, preferences are on by default anyway, and switching them off
probably won't be of much use, so we'll get rid of the
\xmdsTag{use\_prefs} tag, which will set it to the default value of
\ttt{yes}.

We've seen in \Chap{chap:extraAndAdvancedFeatures} how one can use
command line arguments with the \xmdsTag{argv} tagset.  At this stage
of simulation writing it's a good idea just to get things going, and
not worry about varying these parameters just yet, so what we'll do is
set them in the \xmdsTag{globals} block and add the \xmdsTag{argv}
stuff in later if we want to.

The first chunk of code is now:
\begin{xmdsCode}
  <!-- Global system parameters and functionality -->
  <name> advection </name>      <!-- the name of the simulation -->
  <author> Paul Cochrane </author>  <!-- the author of sim -->
  <description>
    Solves the one-dimensional advection equation for an initial 
    cosine-modulated Gaussian pulse.  
    Adapted from A. L. Garcia, "Numerical Methods in Physics"(1994).
  </description>

  <prop_dim> t </prop_dim>    <!-- name of main propagation dim -->

  <error_check> yes </error_check>   <!-- defaults to yes -->
  <use_wisdom> yes </use_wisdom>     <!-- defaults to no -->
  <benchmark> yes </benchmark>       <!-- defaults to no -->
\end{xmdsCode}

\subsection{Global variables for the simulation}

Our global variables are $v$, $k$, $x_0$ and $\sigma$ (from inspection
of the equations in \Sec{sec:theAdvectionEquation}), therefore, we
need to use the following code for the \xmdsTag{globals} block.
\begin{xmdsCode}
<!-- Global variables for the simulation -->
<globals>
<![CDATA[
    const double v = 1.0;
    const double x0 = 0.0;
    const double sigma = 0.1;
    double k = M_PI/sigma;
]]>
</globals>
\end{xmdsCode}

Notice that we've not used the \ttt{const} keyword in front of the
\ttt{k} declaration and assignment.  This is because we're deriving
the value of the wave number from the standard deviation of the wave,
and so the value itself (as far as C/C++ is concerned) isn't a
constant.  If you're worried that this may be a problem further down
the track, don't, because it isn't.

\subsection{The field to be integrated over}

The field, as per normal, has a name of \ttt{main}.  We have one
dimension other than the propagation dimension, and that is \ttt{x},
which we want to put say 50 grid points (i.e.~\xmdsTag{lattice} is set
to 50), and as mentioned earlier, we want the domain to go from -0.5
to 0.5, so the \xmdsTag{domains} tag is set to \ttt{(-0.5,0.5)}.  We
want to sample the first point of this dimension, so we set
\xmdsTag{samples} to \ttt{1}.

Within the \xmdsTag{vector} assignments we only have one vector to
define, and since we have to call at least one vector \ttt{main},
we'll use that.  It will have to have a complex type because we're
going to be using Fourier space for part of the integration, hence we
set \xmdsTag{type} to \ttt{complex}.  There is only one component we
have to define, and that is the field \ttt{A} that we'll be
integrating over.  We therefore use \ttt{A} as the
\xmdsTag{components} assignment.  This isn't going to be defined in
Fourier space, so the \xmdsTag{fourier\_space} assignment is set to
\ttt{no}.  

The trickiest part here is now defining the equation in the \CDATA
block.  Recalling the initial condition in
\eqn{eq:cosineModulatedGaussian}, we therefore declare the variable
\ttt{A} as
\begin{xmdsCode}
A = rcomplex(
      cos(k*(x-x0)) * exp(-(x-x0)*(x-x0)/(2.0*sigma*sigma)), 0.0);
\end{xmdsCode}
where we have used the \ttt{rcomplex} function with a zero imaginary
argument to define the (initially real) quantity, however, of
\ttt{complex} type.

The result of these definitions gives us the following code for the
\xmdsTag{field} element:
\begin{xmdsCode}
  <!-- Field to be integrated over -->
  <field>
    <name> main </name>
    <dimensions> x </dimensions> <!-- transverse dims -->
    <lattice> 50 </lattice>       <!-- no. pts for each dim -->
    <domains> (-0.5,0.5) </domains> <!-- domain of each dim -->
    <samples> 1 </samples>       <!-- sample 1st point of dim? -->
    
    <vector>
      <name> main </name>
      <type> complex </type>          <!-- data type of vector -->
      <components> A </components>    <!-- names of components -->
      <fourier_space> no </fourier_space> <!-- def in k-space? -->
      <![CDATA[
	  A = rcomplex(
	      cos(k*(x-x0)) * exp(-(x-x0)*(x-x0)/(2.0*sigma*sigma))
	        , 0.0);
      ]]>
    </vector>
  </field>
\end{xmdsCode}

\subsection{The sequence of integrations to perform}

Now we come to the \xmdsTag{sequence} section of the code.  There's
only one such sequence in this simulation, so we really only need to
worry about the \xmdsTag{integrate} block.  The algorithm we'll use
here is the fourth-order Runge-Kutta method in the explicit picture.
We want the wave to circle the system the once, so we'll choose the
\xmdsTag{interval} and \xmdsTag{lattice} so that it does so, while
having a step size of about 0.002.  We therefore set
\xmdsTag{interval} to \ttt{1}, and \xmdsTag{lattice} to \ttt{500}.
Only 50 points are really necessary for the output of this, hence
\xmdsTag{samples} is set to \ttt{50}.

The next section to define is the \xmdsTag{k\_operators} element.  The
$k$-space operator is constant in time, and we'll call it \ttt{L}
(which is sort of a convention in the \xmds community).  Since the
operator acts in Fourier space, the spatial derivative merely becomes
a multiplication, and so we can set the \CDATA block (within the
\xmdsTag{k\_operators} element) to:
\begin{xmdsCode}
<![CDATA[
    L = rcomplex(0.0, -v*kx);
]]>
\end{xmdsCode}
Note that we have used the \ttt{rcomplex()} function, and that the
operator is complex.  This is because of the mapping of derivatives in
$x$-space to $k$ vectors in $k$-space; remember that
\begin{equation}
\frac{\del}{\del x} \mapsto i k_x.
\end{equation}

There are no \xmdsTag{vectors} to define, so we can just delete this
line, however, we must write down the differential equation we're
trying to solve.  So, remembering \eqn{eq:advectionEquation}, and the
fact that \xmds uses a special syntax for writing the differential
equation in the \xmdsTag{integrate} element, the \CDATA section within
the \xmdsTag{integrate} element is:
\begin{xmdsCode}
<![CDATA[
    dA_dt = L[A];
]]>
\end{xmdsCode}
Note that we \emph{didn't} write down the equations as
\begin{xmdsCode}
<![CDATA[
    dA_dt = -v*L[A];
]]>
\end{xmdsCode}
and define the operator as \ttt{L = rcomplex(0.0, kx);}.  This is
because of the way \xmds transplants the equations into the code, and
specifying the constants within the operators is the most general way
\xmds can do this.  Heed a warning here though: \xmds at present
doesn't pick this kind of error up, so, one can write the equation as
just mentioned and \xmds will happily do its thing, however, your
answers will be \emph{wrong}.  So, the advice here is to be
\emph{really careful}.

The \xmdsTag{sequence} element now looks like this:
\begin{xmdsCode}
  <!-- The sequence of integrations to perform -->
  <sequence>
    <integrate>
      <algorithm> RK4EX </algorithm> <!--RK4EX,RK4IP,ARK45EX,ARK45IP,SIEX,SIIP-->
      <interval> 1 </interval>   <!-- how far in main dim? -->
      <lattice> 500 </lattice>     <!-- no. points in main dim -->
      <samples> 50 </samples><!-- no. pts in output moment group-->
      
      <k_operators>
        <constant> yes </constant>         <!-- yes/no -->
	<operator_names> L </operator_names>
	<![CDATA[
	    L = rcomplex(0.0, -v*kx);
	]]>
      </k_operators>
      
      <![CDATA[
	  dA_dt = L[A];
      ]]>
    </integrate>
  </sequence>
\end{xmdsCode}

\subsection{The output to generate}

We're in the home stretch now!  All we need to do is tell \xmds what
to spit out at the end of the simulation.  We'll use ascii output (a
bit more portable) and remove the precision assignment; we won't
sample the output moments in Fourier space; we only have one dimension
to sample (namely \ttt{x}) and we'll use 50 points here; there is only
one moment to output, and that is the field amplitude which we'll call
\ttt{amp}; and finally the code to sample the output moment is simply
equal to the amplitude of the field which is just \ttt{A}, so the code
put into the \CDATA block is \ttt{amp = A;}.  The \xmdsTag{output}
element code is therefore:
\begin{xmdsCode}
  <!-- The output to generate -->
  <output format="binary" precision="single">
    <group>
      <sampling>
        <fourier_space> no </fourier_space><!--sample in k-space?-->
	<lattice> 50 </lattice>           <!-- no. pts to sample -->
	<moments> amp </moments>          <!-- names of moments -->
	<![CDATA[
	    amp = A;
	]]>
      </sampling>
    </group>
  </output>
\end{xmdsCode}

\subsection{The final program}

And that's it!  The finished simulation is this:
\begin{xmdsCode}

  <!-- Global system parameters and functionality -->
  <name> advection </name>      <!-- the name of the simulation -->
  <author> Paul Cochrane </author>  <!-- the author of sim -->
  <description>
    Solves the one-dimensional advection equation for an initial 
    cosine-modulated Gaussian pulse.  
    Adapted from A. L. Garcia, "Numerical Methods in Physics"(1994).
  </description>

  <prop_dim> t </prop_dim>    <!-- name of main propagation dim -->

  <error_check> yes </error_check>   <!-- defaults to yes -->
  <use_wisdom> yes </use_wisdom>     <!-- defaults to no -->
  <benchmark> yes </benchmark>       <!-- defaults to no -->

  <!-- Global variables for the simulation -->
  <globals>
  <![CDATA[
      const double v = 1.0;
      const double x0 = 0.0;
      const double sigma = 0.1;
      double k = M_PI/sigma;
  ]]>
  </globals>

  <!-- Field to be integrated over -->
  <field>
    <name> main </name>
    <dimensions> x </dimensions> <!-- transverse dims -->
    <lattice> 50 </lattice>       <!-- no. pts for each dim -->
    <domains> (-0.5,0.5) </domains> <!-- domain of each dim -->
    <samples> 1 </samples>       <!-- sample 1st point of dim? -->
    
    <vector>
      <name> main </name>
      <type> complex </type>          <!-- data type of vector -->
      <components> A </components>    <!-- names of components -->
      <fourier_space> no </fourier_space> <!-- def in k-space? -->
      <![CDATA[
	  A = rcomplex(
	      cos(k*(x-x0)) * exp(-(x-x0)*(x-x0)/(2.0*sigma*sigma))
	        , 0.0);
      ]]>
    </vector>
  </field>

  <!-- The sequence of integrations to perform -->
  <sequence>
    <integrate>
      <algorithm> RK4EX </algorithm> <!--RK4EX,RK4IP,ARK45EX,ARK45IP,SIEX,SIIP-->
      <interval> 1 </interval>   <!-- how far in main dim? -->
      <lattice> 500 </lattice>     <!-- no. points in main dim -->
      <samples> 50 </samples><!-- no. pts in output moment group -->
      
      <k_operators>
        <constant> yes </constant>         <!-- yes/no -->
	<operator_names> L </operator_names>
	<![CDATA[
	    L = rcomplex(0.0, -v*kx);
	]]>
      </k_operators>
      
      <![CDATA[
	  dA_dt = L[A];
      ]]>
    </integrate>
  </sequence>

  <!-- The output to generate -->
  <output format="ascii">
    <group>
      <sampling>
        <fourier_space> no </fourier_space><!--sample in k-space?-->
	<lattice> 50 </lattice>           <!-- no. pts to sample-->
	<moments> amp </moments>          <!-- names of moments -->
	<![CDATA[
	    amp = A;
	]]>
      </sampling>
    </group>
  </output>

</simulation>
\end{xmdsCode}

Here is a link to the finished (gzipped) script file
\htmladdnormallink{advection.xmds.gz}{http://www.xmds.org/examples/advection.xmds.gz}
on the \xmds web site (\htmladdnormallink{http://www.xmds.org}{http://www.xmds.org}).

\section{Making the simulation and getting results}

As per usual, we just need to run \xmds on the simulation script, and
then run the simulation.  So, here we go:
\begin{shellCode}
% xmds advection.xmds
Output file name defaulting to 'advection.xsil'
compiling ...
        g++ -pthread  -O3 -ffast-math -funroll-all-loops 
	-fomit-frame-pointer -o advection advection.cc 
	-I/home/cochrane/bin -lstdc++ -lm  -lxmds 
	-L/home/cochrane/bin -lfftw_threads -lfftw
advection ready to execute
\end{shellCode}
then:
\begin{shellCode}
% advection
Performing fftw calculations
Standing upon the shoulders of giants... (Importing wisdom)
Making forward plan
Making backward plan
Keeping accumulated wisdom
Finished fftw calculations
Beginning full step integration ...
Sampled field (for moment group #1) at t        = 0.000000e+00
Sampled field (for moment group #1) at t        = 2.000000e-02
Sampled field (for moment group #1) at t        = 4.000000e-02
<snip>
Sampled field (for moment group #1) at t        = 9.600000e-01
Sampled field (for moment group #1) at t        = 9.800000e-01
Sampled field (for moment group #1) at t        = 1.000000e-00
maximum step error in moment group 1 was 7.801465e-06
Time elapsed for simulation is: 0 seconds
\end{shellCode}
That was fast eh?  And the error isn't too bad at about $10^{-5}$, so
we can be vaguely confident of the results.  Lets look at them now, in
both Matlab (or Octave) and Scilab.

\subsection{Matlab and Octave}

Using \ttt{xsil2graphics} we generate the Matlab or Octave script by the
command:
\begin{shellCode}
% xsil2graphics advection.xsil
\end{shellCode}
and then running the following commands in Matlab or Octave:
\begin{matlabCode}
>> advection
>> mesh(t_1,x_1,amp_1)
>> xlabel('t')
>> ylabel('x')
>> zlabel('A')
\end{matlabCode}
Doing all this should produce something very similar to that in
\fig{fig:advectionMatlabPlot}.
\begin{figure}[!h]
  \centerline{\includegraphics[width=\figwidth]{figures/advectionMatlabPlot}}
  \caption{Three dimensional plot in Matlab of a cosine-modulated
  Gaussian pulse according to the advection equation.  Parameters used
  were: $v = 1$, $\sigma = 0.1$, $x_0=0$, $k = \pi/\sigma$.  Notice
  that with the periodic boundary conditions that the pulse moves off
  one side of the figure and re-enters from the opposite side.}
  \label{fig:advectionMatlabPlot}
\end{figure}

\subsection{Scilab}

Using \ttt{xsil2graphics} we generate the Scilab script by the
command:
\begin{shellCode}
% xsil2graphics -scilab advection.xsil
\end{shellCode}
and then running the following commands in Scilab:
\begin{scilabCode}
-->exec('advection.sci')
 
-->temp_d1 = zeros(50,51);
 
-->t_1 = zeros(1,51);
 
-->temp_d2 = zeros(50,51);
 
-->x_1 = zeros(1,50);
 
-->amp_1 = zeros(50,51);
 
-->error_amp_1 = zeros(50,51);
 
 
-->advection1 = fscanfMat('advection1.dat');
Error Info buffer is too small (too many columns in your file ?)
 
-->temp_d1(:) = advection1(:,1);
 
-->temp_d2(:) = advection1(:,2);
 
-->amp_1(:) = advection1(:,3);
 
-->error_amp_1(:) = advection1(:,4);
 
-->t_1(:) = temp_d1(1,:);
 
-->x_1(:) = temp_d2(:,1);
 
 
-->clear advection1 temp_d1 temp_d2
 
 
 
-->plot3d(x_1,t_1,amp_1)
\end{scilabCode}
which should generate something similar to that in
\fig{fig:advectionScilabPlot}.
\begin{figure}[!h]
  \centerline{\includegraphics[width=\figwidth]{figures/advectionScilabPlot}}
  \caption{Three dimensional plot in Scilab of a cosine-modulated
  Gaussian pulse according to the advection equation.  Parameters used
  were: $v = 1$, $\sigma = 0.1$, $x_0=0$, $k = \pi/\sigma$.  Notice
  that with the periodic boundary conditions that the pulse moves off
  one side of the figure and re-enters from the opposite side.}
  \label{fig:advectionScilabPlot}
\end{figure}

\section{Adding command line arguments}

Now that we're happy with how the simulation is performing, we can
define some command line arguments so that we can investigate the
system more easily.  We might as well be able to change all of the
global variables except for $k$ (since it depends on one of the other
variables), so add the following code snippet just before the
\xmdsTag{globals} block:
\begin{xmdsCode}
  <!-- Command line arguments -->
  <argv>
    <arg>
      <name> v </name>
      <type> double </type>
      <default_value> 1.0 </default_value>
    </arg>
    <arg>
      <name> x0 </name>
      <type> double </type>
      <default_value> 0.0 </default_value>
    </arg>
    <arg>
      <name> sigma </name>
      <type> double </type>
      <default_value> 0.1 </default_value>
    </arg>
  </argv>
\end{xmdsCode}
But remember to comment out these variables in the \xmdsTag{globals}
block otherwise the compiler will throw an error.

Now you can have a play!  Try different variable options and see how
the equations and \xmds perform.

\section{The xmds --template option}

A new feature of \xmds, as of version 1.3-3, is the output of a
template code.  When \xmds is called with the \ttt{-template} (or
equivalently the \ttt{-t}) option, then a template code will be
written to either standard output (i.e.~the terminal), or to file, if
a filename is given after the \ttt{--template} flag.  For instance, if
one entered the following at the command line:
\begin{shellCode}
% xmds --template
\end{shellCode}
then you would see several lines of \xmds code scroll past.  What's
the use in it just scrolling past you say?  Well, you could pipe this
output to file like so:
\begin{shellCode}
% xmds --template > new_xmds_file.xmds
\end{shellCode}
Nice eh?  However, it is possible to save on keystrokes by getting
\xmds to make the file directly, saving you from having to use
shell-related commands to save the output.  To save a template
directly to file, just enter this command:
\begin{shellCode}
% xmds --template new_xmds_file.xmds
\end{shellCode}
and this will make a new file for you called
\ttt{new\_xmds\_file.xmds} in the same directory as \xmds was called.
Why have the ability to just send the template to the screen?  Well,
doing so doesn't slow things down, and it gives an extra level of
flexibility, and we're here to make your life as the user of \xmds as
easy as possible.