Quickstart Guide

The build environment for the VTF allows a user to keep multiple build directories (i.e. gnu-debug, gnu-opt, gnu-debug-mpi, gnu-opt-mpi, intel-debug, ...) under the same toplevel directory vtf. Scripts are provided to adjust the environment of the current shell to use executables conveniently from different build directories. These scripts are vtf/ac/paths.sh and vtf/ac/paths.csh. They can be run from an arbitrary directory in the following way:

• bash: source paths.sh [path to toplevel build directory] or . paths.sh [path to toplevel build-directory]
• sh, ksh: . paths.sh [path to toplevel build-directory]
• csh, tcsh: source paths.csh [path to toplevel build-directory]
  • Execution of paths.csh requires the previous inclusion of the script directory ac into the PATH with setenv PATH {path to toplevel src directory}/ac:$PATH .

In the following it is assumed that the VTF has been configured in serial, i.e. by running vtf/configure with the option --enable-mpi=no or specifying MPI=no before running setup, see InstallationConfiguration^?. Further, that the shell enviroment has been extended for the current build (for instance gnu-debug or gnu-opt) as explained above and at least the application examples

• clawpack/applications/euler/1d/Shocktube
• clawpack/applications/euler/2d/Ramp
• clawpack/applications/euler/3d/Pbc

have been compiled. This can be accomplished for all applications at once by running make in vtf/[build directory]/clawpack/applications or running make locally in vtf/[build directory]/clawpack/applications/euler/1d/Shocktube, vtf/[build directory]/clawpack/applications/euler/2d/Ramp, vtf/[build directory]/clawpack/applications/euler/3d/Pbc.

1. One-dimensional example: Shocktube

Go to vtf/clawpack/applications/euler/1d/Shocktube/Cal1 and simply type

shocktube1d

The program solves a typical one-dimensional Riemann problem for the Euler equations and dumps the result of intermediate time-steps into HDF-files. Parameters are given in solver.in, while the Riemann problem is defined in init.dat.

If you rerun this example multiple times, you will notice that the size of the HDF-files is growing. This is a specialty of the codes internally employed inside AMROC's DAGH that generate HDF-output. They always append data to files, but never delete them. Consequently, existing HDF-files should always be deleted before a new run.

To simplify the startup-procedure a Python script run.py is therefore supplied for each example. It is intended to be run in the background. Now type

run.py &

to restart the example. You can use tail -f out.txt to display the current state of the job. After the run, the script will automatically call hdf2file and will convert the HDF-files into ASCII-tabulars. Additionally, script-files for the popular Gnuplot-program will be generated. Type

gnuplot Density.gnu

to display the temporal development of the density or type

gnuplot 1280.gnu

to browse through the data of the final result. Compare your results to the reference data.

---

2. Two-dimensional example: Flow over a ramp

Go to vtf/clawpack/applications/euler/2d/Ramp and type

run.py &

Execution will take a few minutes. The HDF-files can be displayed with Matlab, Visual3 or with IBM's Data Explorer.

2.1 Matlab

To use Matlab, set the MATLABPATH -variable to the directory vtf/amroc/matlab before Matlab is started from the directory vtf/clawpack/applications/euler/2d/Ramp. Type

plothdf

in Matlab's command window to display the data. plotconf.m, filenames.m have to be adjusted, if the discretization or the output-filenames are changed in solver.in. menu_automation.m can be employed to automatically browse through the data.

Compare your results to the reference data that have been calculated with refinement factor 4 for the highest level.

2.2 Visual3

To use Visual3, ensure that hdf2v3 has been build successfully and your .Xresources are configured correctly (see installation notes for Visual3). Type

hdf2v3 496

to start the visualizer with all data of the last time-step. hdf2v3 reads its configuration from display.in and will display the density distribution. By typing ? all defined keys will be displayed for the active Visual3-window. If you activate for instance the 3D-window and press p the pressure distribution will be displayed. The visualizer assumes standard Euler equations for a polytropic gas, if being started without any options. See the Visual3 user's & programmer's manual for a detailed description on how to use Visual3. Instead of hdf2v3 496 you may also use hdf2v3 -s r 496 to start the visualizer. The option -s will force hdf2v3 to read only the HDF-file of the density. Derived quantities like pressure of temperature can not be displayed in this mode.

Hit the Esc-key in the 3D-window to terminate Visual3.

2.3 IBM's Data Explorer

hdf2file can be used as an external filter in IBM Data Explorer. As IBM's Data Explorer offers nearly unlimited graphical capabilities only an elementary example to demonstrate the import of AMROC's HDF-data will be provided here.

Ensure that hdf2file is in your path and start Data Explorer by typing dx & in the directory vtf/clawpack/applications/euler/2d/Ramp. Select Run Visual Programs and choose Density.dx.net. The program will produce a plane color plot of the density distribution of the last time-step with index 496 and a three-dimensional rubbersheet.

---

3. Three-dimensional example: Periodic boundary conditions

Go to vtf/clawpack/applications/euler/3d/Pbc and type

run.py &

Execution will take quiet a while, but you can start already visualizing HDF-files during the run.

3.1 Matlab

Set MATLABPATH and start Matlab from the directory vtf/clawpack/applications/euler/3d/Pbc. Start plothdf and answer the question Make 3d-cut? with 1. Choose a plane rectangular to the z-axis and position this plane at z=0.0 or z=0.5. Select the last time-step and Matlab should display a cut through the three-dimensional data set that should be comparable to the cuts through the reference data.

Note that the plothdf-script is written especially to generate two-dimensional pictures and will terminate with three-dimensional data, if no cut is selected.

3.2 Visual3

Type hdf2v3 32 to display the time-step for t=0.21 or type hdf2v3 118 to display the data for t=0.84, activate the 3D-window of Visual3 and hit F7. This toggles an isosurface and the picture should be similar to the reference data. Use the Scan-button in the dials-window to change the value of the isosurface.

3.3 Data Explorer

Ensure that hdf2file is in your path and start the Data Explorer by typing dx & in the directory vtf/clawpack/applications/euler/3d/Pbc. Select Run Visual Programs and choose DensityIso.dx.net. The program will produce a graphic for the last time-step with index 118 that is similar to the reference graphics produced with Visual3.

---

4. Parallel execution

Rerun vtf/configure with the option --enable-mpi=yes or specify MPI=yes before you rerun setup, see InstallationConfiguration^?. Then compile in the new build directory ...-mpi as usual and abjust your shell enviroment as outlined above for the new MPI-build directory.

Execute the examples again by typing

run.py [No. processors] &

in the directories of the different examples or use your local MPI submission command, for instance

mpirun -np [No. processors] [executable]

---

-- RalfDeiterding - 11 Jul 2005