Tutorial 1 ========== Throughout the tutorial, you should consult the relevant pages of the User Guide, either using the hardcopy provided, or the web pages at www.cactuscode.org 1. Checkout and Compile Cactus ============================== Checkout the Cactus using CVS: cvs -d :pserver:cvs_anon@cvs.cactuscode.org:/cactus login > anon cvs -d :pserver:cvs_anon@cvs.cactuscode.org:/cactus checkout Cactus You could compile Cactus now, but it won't do anything interesting without any thorns. Checkout some thorns by moving into the Cactus home directory and using the provided make target gmake checkout Choose applications, and checkout all the WaveToy applications. Choose a name for a "configuration". This should be a name which will identify the build. For example "wave", or maybe "wednesday" or "tutorial", the name can be anything. Build a Cactus configuration by typing (let's assume you chose the name "wave" from now on) gmake wave Look at the information that the Cactus configuration process has found by looking at the file configs/wave/config-data/make.config.defn Also look in the file configs/wave/config-data/make.extra.defn Notice that the MPI section is empty, this is because we haven't instructed the configure script that we want to use MPI, so we are compiling a single-processor version of Cactus. Continue the configuration process by typing again gmake wave You will be asked if you want to edit the Thorn List. This is the list of all thorns that Cactus will compile into your executable. Cactus allows you to compile many thorns into your executable, but only execute those that you require at runtime so you could always compile in all thorns. But the more thorns you have the longer the code takes to compile (the first time), or maybe you have some thorns that you know don't compile on a particular platform, so you have a chance to shorten your Thorn List. Since you only have the Wave Toy thorns checked out, type "no" and the build will continue. Look at the output from the build process. First the CCL files are processed, and you are given information about the variables, parameters and scheduling in each thorn. Then the thorns are built one at a time and a library for each thorn created. If the build is successful, you will see an executable ./exe/cactus_wave 2. Running the Test Suite and Example Parameter Files ===================================================== Run the testsuite for these thorns to verify that everything is working. Type gmake testsuite and follow the instructions, selecting "All" tests. Each test parameter file will run and at the end you will be told if any have failed. Before we run Cactus, take a minute to locate some key files, first look at configs/wave/ThornList this is a list of the thorns you have chosen for this build. If you want to change this list, you can edit it by hand, or you can use the make target "gmake wave-thornlist" Now look at the postprocessed Fortran code, in configs/wave/build/WaveToyF77/WaveToy.f Note that all the macros, like the argument lists and parameters have been expanded. Find how Cactus currently implements parameters in Fortran by searching for "bound". Also look at WaveToy.F77.d, this file contains the "dependencies" for this file, if any of these files change, WaveToy.F77 will be rebuilt. Now we will run some of the example parameter files that come with Cactus. Each thorn should contain example parameter files in the "par" directory, these allow other users to see how to use the thorn. Cactus provides a make target to collect all the example thorns for a configuration together gmake wave-thornparfiles will collect all the parameter files together in the directory "thornparfiles". Now run one of the examples, for example wavetoyf77_rad.par. To do this type ./exe/cactus_wave thornparfiles/wavetoyf77_rad.par Look at the output in the directory wavetoyf77_rad using xgraph. xgraph is an easy package to use for quickly viewing 1D data files. xgraph wavetoyf77_rad/psi.xl To animate with xgraph use xgraph wavetoyf77_rad/psi.xl -dl 300 -a Now run the parameter file wavetoyc_rad.par. This is provided by a different "implementation" of the Wave Toy evolver (C instead of Fortran). Note that the two different implementations give the same results. Compare the two parameter files to see the difference. Remember that different implementations can have different private variables and parameters. Try changing the parameters in wavetoyf77_rad.par and see what happens when you run the code. Start by removing one of the thorns in the ActiveThorns parameter, and seeing what happens, or add a fictious thorn here. Try different initial data, you can found out what is available by typing ./exe/cactus_wave -o initial_data You can see all the parameters by typing ./exe/cactus_wave -O In particular, learn how to use the output parameters to get more or less output, and to add more variables. Look at the section on Command Line Options in the documentation, and try out some of them. Next we show how to add extra functionality to this wave application. More detailed handouts will be given at the time of the lab, but you will learn how to do the following: 3. Adding a Thorn ================= Now try adding your own thorn to the Wave Toy application. Here we suggest three possibilities a) A new initial data thorn b) A poststep thorn that will be executed after each iteration c) An analysis thorn that will only be executed if output is required In each case, create a new thorn using gmake newthorn and for your "arrangement" name use your surname. a) A new initial data thorn =========================== This thorn should give initial values to the two grid functions phi and phi_old. You can choose any initial values you like (although they may look strange when you evolve them). Look at the provided thorn IDScalarWave to see what you need to add. If you want to also be able to use the initial data from IDScalarWave you will need to EXTEND the initial_data parameter from IDScalarWave, and you will need a different implementation name than IDScalarWave. b) A new poststep thorn ======================= This thorn will be run after each evolution step. First try to just print to the screen after each iteration ... you don't need any grid variables or parameters for this. c) A new analysis thorn ======================= Remember that analysis thorns are special, they are always associated with output. The thorn will only be run if what it is calculating needs to be output. Thus analysis thorns should not modify and grid variables, they should just perform analysis of results. Try adding, for example, a thorn which calculates any power of the scalar field (that is phi**n, where n is a parameter). 4. Sharing Thorns ================= Here you get the chance to share your finished thorn with others, and to use other peoples thorns. Complete details for committing your thorns to the CVS repository will be given during the session. Before you commit your thorn to the repository be sure to add a testsuite and a parameter file, so that anyone checking out your thorn can see how it works. 5. More Complicated =================== For the adventurous, here are some more complicated examples for you to try. These are thorns that we would write for our Standard Arrangements if we had time ... please contact us if you complete any of these and would like to make it available to others! 1) Add an IO method for outputting 2D ASCII files that can be read into gnuplot 2) Add a unigrid driver (that is a driver without parallelism). 3) Add a utility thorn (that is callable and not scheduled) that will integrate a grid function over the 3D domain using Simpsons rule. Try and add the correct behaviour with the symmetry domains