Installation instructions¶
Prerequisites¶
Operating systems. Clawpack should work fine on Unix/Linux or Mac OS X systems. Much of it will work under Windows using Cygwin, but this is not officially supported.
On OS X you need to have the Xcode developer tools installed in order to have “make” working.
Fortran. The main Clawpack routines are written in Fortran (a mixture of Fortran 77 and Fortran 90/95) and so compiling and running the code requires a Fortran compiler, such as gfortran, which is part of the GNU gcc compiler suite. For Mac OSX, see hpc.sourceforge.net for some installation options.
Makefiles are used in libraries and directories and you will need some version of make.
Python. Starting with Version 4.4, we use Python for visualization of results (see Plotting options in Python) and also for user input (see Specifying run-time parameters in setrun.py). Older Matlab plotting scripts are still available but are no longer being developed and the examples now included in Clawpack include setplot.py files to facilitate use of the Python plotting tools (see Using setplot.py to specify the desired plots).
You will need Python Version 2.5 or above (but not 3.0 or above, which is not backwards compatible). You will also need NumPy and matplotlib for plotting.
See Python Hints for information on installing the required modules and to get started using Python if you are not familiar with it.
Virtual Machine. An alternative to installing the prerequisites and Clawpack itself is to use the Clawpack Virtual Machine.
Cloud Computing. Another alternative is to run Clawpack on the Cloud, see Amazon Web Services EC2 Clawpack AMI.
Downloading Clawpack¶
First download the tar file from the Clawpack download page:
This file will be of the form clawpack-N.tar.gz where N is the version number.
Move this tar file to the directory where you want to install claw and then:
$ tar -zxvf clawpack-N.tar.gz
$ cd clawpack-N
Setting environment variables¶
In this claw directory modify the setenv.py file if necessary and then:
$ python setenv.py
This will provide files to set environment variables appropriately. In particular, the variable CLAW should be set to point to this directory.
Now execute
$ source setenv.bash
if you are using the bash shell, or
$ source setenv.csh
if you use csh. If you don’t know what shell you are using, try both and see which one doesn’t give errors, you won’t hurt anything.
If you don’t know about Unix shells, see these class notes, for an introduction and other links.
Consider putting the commands contained in the appropriate file setenv.bash or setenv.csh in your .cshrc or .bashrc file (which is executed automatically in each new shell you create).
In particular, the commands found in these files set the following environment variables
- CLAW is set to the path to the main directory of the Clawpack files.
- PYTHONPATH is a list of paths that should include $CLAW/python. If this variable is already set in the shell from which you execute setenv.py then it should provide an extension of the original path to include this.
- FC is set to gfortran as the default compiler to use for Fortran. You may want to change this.
Testing your installation and running an example¶
There are a number of test cases bundled with Clawpack in the directories $CLAW/apps and $CLAW/book. Here and below it is assumed that the environment variable CLAW has been set properly as described above.
As a first test, go to the directory $CLAW/apps/advection/1d/example1. You can try the following test in this directory, or you may want to first make a copy of it (see the instructions in Copying an existing example).
The Makefiles are set up to do dependency checking so that in many application directories you can simply type:
$ make .plots
and the Fortran code will be compiled, data files created, the code run, and the results plotted automatically, resulting in a set of webpages showing the results.
However, if this is your first attempt to run a code, it is useful to go through these steps one at a time, both to understand the steps and so that any problems with your installation can be properly identified.
You might want to start by examining the Makefile. This sets a number of variables, which at some point you might need to modify for other examples, see Clawpack Makefiles for more about this. At the bottom of the Makefile is an include statement that points to a common Makefile that is used by most applications, and where all the details of the make process can be found.
To compile the code, type:
$ make .exe
If this gives an error, see Trouble running “make .exe”.
This should compile the example code (after first compiling the required library routines) and produce an executable named xclaw in this directory.
Before running the code, it is necessary to also create a set of data files that are read in by the Fortran code. This can be done via:
$ make .data
If this gives an error, see Trouble running “make .data”.
This uses the Python code in setrun.py to create data files that have the form *.data. For the 1d advection example, two files are created, claw.data and setprob.data. The file claw.data contains standard run-time parameters of Clawpack (such as the number of grid cells mx, indications of what method to use, what boundary conditions to impose, etc.). The file setprob.data typically contains parameters specific to a particular application, in this case the advection velocity u.
In Clawpack 4.3 and earlier versions, the user would modify the claw.data and setprob.data files directly. Starting with Clawpack 4.4, the recommended approach is to only modify the Python function setrun defined in the file setrun.py, and use “make .data” to create the *.data files. See Specifying run-time parameters in setrun.py for more details.
Once the executable and the data files all exist, we can run the code. The recommended way to do this is to type:
$ make .output
If this gives an error, see Trouble running “make .output”.
One could run the code by typing ”./xclaw”, but using the make option has several advantages. For one thing, this checks dependencies to make sure the executable and data files are up to date, so you could have typed “make .output” without the first two steps above.
Also, before running the code a subdirectory _output is created and the output of the code (often a large number of files) is directed to this subdirectory. This is convenient if you want to do several runs with different parameter values and keep the results organized. After the code has run you can rename the subdirectory, or you can modify the variable OUTDIR in the Makefile to direct results to a different directory. See Clawpack Makefiles for more details. Copies of all the data files are also placed in the output directory for future reference.
If the code runs successfully, you should see output like the following:
Reading data file, first 5 lines are comments: claw.data
running...
Reading data file, first 5 lines are comments: setprob.data
CLAW1EZ: Frame 0 output plot files done at time t = 0.0000D+00
CLAW1... Step 1 Courant number = 5.000 dt = 0.1000D+00 t = 0.1000D+00
CLAW1 rejecting step... Courant number too large
CLAW1... Step 1 Courant number = 0.900 dt = 0.1800D-01 t = 0.1800D-01
CLAW1... Step 2 Courant number = 0.900 dt = 0.1800D-01 t = 0.3600D-01
CLAW1... Step 3 Courant number = 0.900 dt = 0.1800D-01 t = 0.5400D-01
CLAW1... Step 4 Courant number = 0.900 dt = 0.1800D-01 t = 0.7200D-01
CLAW1... Step 5 Courant number = 0.900 dt = 0.1800D-01 t = 0.9000D-01
CLAW1... Step 6 Courant number = 0.500 dt = 0.1000D-01 t = 0.1000D+00
CLAW1EZ: Frame 1 output plot files done at time t = 0.1000D+00
--- etc --- etc ---
CLAW1EZ: Frame 9 output plot files done at time t = 0.9000D+00
CLAW1... Step 1 Courant number = 0.900 dt = 0.1800D-01 t = 0.9180D+00
CLAW1... Step 2 Courant number = 0.900 dt = 0.1800D-01 t = 0.9360D+00
CLAW1... Step 3 Courant number = 0.900 dt = 0.1800D-01 t = 0.9540D+00
CLAW1... Step 4 Courant number = 0.900 dt = 0.1800D-01 t = 0.9720D+00
CLAW1... Step 5 Courant number = 0.900 dt = 0.1800D-01 t = 0.9900D+00
CLAW1... Step 6 Courant number = 0.500 dt = 0.1000D-01 t = 0.1000D+01
CLAW1EZ: Frame 10 output plot files done at time t = 0.1000D+01
If you don’t like seeing output from every time step, you can suppress this by setting verbosity = 0 in the file setrun.py. You might try doing that and then typing:
$ make .output
It should recreate the data files and rerun the code, with less output along the way.
If the code runs properly, the subdirectory _output should contain the following files:
claw.data fort.q0003 fort.q0008 fort.t0002 fort.t0007
fort.info fort.q0004 fort.q0009 fort.t0003 fort.t0008
fort.q0000 fort.q0005 fort.q0010 fort.t0004 fort.t0009
fort.q0001 fort.q0006 fort.t0000 fort.t0005 fort.t0010
fort.q0002 fort.q0007 fort.t0001 fort.t0006 setprob.data
The fort.info file contains information about the run just completed. The files with names of the form fort.t000N and fort.q000N contain the computed results for Frame N. See fortfiles for more information about the contents of these files.
Normally you will not want to examine these files directly, but instead will use a plotting tool to plot the results.
Plotting the results. Once the code has run and the files listed above have been created, there are several options for plotting the results.
To try the Python tools, type:
$ make .plots
If this gives an error, see Trouble running “make .plots”.
If this works, it will create a subdirectory named _plots that contains a number of image files (the *.png files) and a set of html files that can be used to view the results from a web browser. See plotting_makeplots for more details.
An alternative is to view the plots from an interactive Python session, as described in the section Interactive plotting with Iplotclaw.
If you wish to use Matlab instead, see Plotting using Matlab.
Other visualization packages could also be used to display the results, but you will need to figure out how to read in the data. See fortfiles for information about the format of the files produced by Clawpack.
Creating html versions of source files.*
To best view the results, and the source code and README files, type:
$ make .htmls
and view the resulting README.html file with a web browser.
Starting a Python web server¶
This part is not required, but to best view README.html and other Clawpack generated html files, it is convenient to start a local webserver via:
$ cd $CLAW
$ python python/startserver.py
Note that this will take over the window, so do this in a new window, or else do:
$ xterm -e python python/startserver.py &
to execute it in a new xterm (if available). The setenv commands described above will define an alias so that this last command can be simplified to:
$ clawserver
The main $CLAW directory will then be available at http://localhost:50005 and jsMath should work properly to display latex on the webpages (once you’ve downloaded the required fonts, see http://www.math.union.edu/locate/jsMath/users/fonts.html).
