Quick Start Guide to Cactus
===========================
September 12th 1999

This document is designed for those who want to checkout Cactus,
compile it, run it, and look at some results without having to
wade through all the documentation. Of course, we heartily 
recommend that you read all the documentation before trying 
this at home, but for the very brave:

0. We are going to explain how to run the WaveToy applications
   in Cactus. These enable 3D evolutions of the simple
   scalar wave equation, using different initial data and 
   boundary conditions. This thorn is our standard example thorn.

1. Get hold of a copy of the latest version of the Cactus, 
   preferably from our CVS server:
 
   cvs -d :pserver:cvs_anon@cvs.cactuscode.org:/cactus login
   > anon

   cvs -d :pserver:cvs_anon@cvs.cactuscode.org:/cactus co Cactus

   To get the thorns, in the Cactus directory type

   gmake checkout

   and then follow the instructions to checkout one or more 
   of the "WaveToy" applications.

   The alternative to CVS is grabbing a tar file or the complete
   code and thorns from www.cactuscode.org

2. Now compile the code, if you want to compile with MPI, your
   best chance if you are on a T3E or origin is to type

   gmake wave-config MPI=NATIVE

   or if you know your machine has MPICH installed try

   gmake wave-config MPI=MPICH

   If you want to compile without MPI, the command is just

   gmake wave-config

   If you run in to problems at this stage, you really need
   to look at the documentation.

3. If you have configured OK, the next stage is to compile
   the code. Type

   gmake wave

   You will then be asked if you want to edit the ThornList, 
   if you checked out with CVS just the WaveToy applications
   then you can say no here. Hopefully the code will now
   compile, and you will see an executable exe/cactus_wave

4. Now it is time to test the code. The WaveToy thorns contain
   several "test suites" which contain the results from an 
   earlier run, so that we can check we get the same answers.
   Type

   gmake wave-testsuite

   and follow the instructions, hopefully you just need to use
   the default values. You should then see messages telling you
   if the test suites are working or not.

5. Finally, we can look at the parameter files that come with 
   the WaveToy application. Type 

   gmake wave-thornparfiles

   which should move all the parameter files from the WaveToy
   application into the directory "thornparfiles". To run a 
   parameter file with Cactus use 

   e.g. with MPI

   mpirun -np 2 ./exe/cactus_wave thornparfiles/<par file from thornparfiles>

   or with no MPI

   ./exe/cactus_wave thornparfiles/<par file from thornparfiles>

   The output from the run should be in a directory with the same name as
   the parameter file (this is specified in the parameter file). In this
   directory there are 1D output files containing the evolution of
   the scalar wave, called "phi.xl" (the value along the x-axis), and
   "phi.dl" (the value along the diagonal). They are output in xgraph 
   format, try
 
   xgraph phi.dl -dl 300 -a 

   to see an animated evolution of the wave. Most of the parameter files 
   specify that the evolution should take place in just an octant of a 
   full grid to save memory/time. 
   Try running e.g wavetoyf90_rad.par and wavetoy90_none.par,
   these both start with a gaussian wave, but one implements radiation
   boundary conditions so that the wave goes smoothly off the grid,
   while the other uses no boundary condition and the wave is reflected 
   back.