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.
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.
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