Go on to Section 5.Index:
4 FLASH tools
4.1 The FLASH configuration script (setup)
4.2 FLASH output comparison utility (focu)
4.2.1 Building focu
4.2.2 Using focu
4.3 IDL routines for the analysis of FLASH output (fidlr)
4.3.1 Configuring your environment to use the IDL routines
4.3.2 Using the xflash graphical plotting tool
4.3.3 Other IDL routines
In this section we describe several of the tools distributed with FLASH. The source code for these programs (except for setup) can be found in the main FLASH source tree under the tools/ directory.
The setup script, found in the FLASH root directory, provides the primary command-line interface to the FLASH source code. It configures the source tree for a given problem and target machine and creates files needed to parse the runtime parameter file and make the FLASH executable. More description of what setup does may be found in Section 6.1. Here we describe its basic usage.
Running setup without any options prints a message describing the available options:
Available values for the two mandatory options, the name of the problem to configure and the type of machine to configure for, are determined by scanning the setups/ and source/systems/ directories, respectively.[sphere 5:09pm] % ./setup
usage: setup problem-name machine-type [options]
problems: 2blast advect mach rt sedov sod xrayburst
machines: asci_blue asci_bluemtn asci_red irix linux t3e
options: -verbose -portable -defaults -[123]d -maxblocks=#
A ``problem'' consists of a set of initial and boundary conditions, possibly additional physics (e.g., a subgrid model for star formation), and a set of adjustable parameters. The directory associated with a problem contains source code files which implement the initial and boundary conditions and extra physics, together with a configuration file, read by setup, which contains information on required physics modules and adjustable parameters.
A ``machine type'' consists of an architecture and an associated operating system. Normally it does not refer to a specific machine, but in the case of the (ASC) machines (Blue Pacific, Blue Mountain, and Red), the particular machine is unique and is treated as a separate architecture. The directory for each machine type contains a makefile fragment ( Makefile.h) which sets command names, compiler flags, and library paths, and any replacement or additional source files needed to compile FLASH for that machine type.
setup uses the problem and machine type, together with a user-supplied file called Modules which lists the code modules to include, to generate a directory called object/ which contains links to the appropriate source files and makefile fragments. It also creates the master makefile (object/Makefile) and several Fortran include files (object/rt_*) which are needed by the code in order to parse the runtime parameter file. After running setup, the user can make the FLASH executable by running make in the object/ directory (or from the FLASH root directory, if the -portable option is not used with setup). The optional command-line modifiers have the following interpretations:
| -verbose | Normally setup echoes to the standard output summary messages indicating what it is doing. Including the -verbose option causes it to also list the links it creates. |
| -portable | This option creates a portable build directory. Instead of object/, setup creates object_problem_machine/, and instead of creating links to the source files in source/ and setups/, it copies files from those directories into the build directory. The resulting build directory can be placed into a tar archive and sent to another machine for building. Because the makefile in the FLASH root directory is generic and does not know what problem or machine has been selected, it cannot be used to make code which has been configured with -portable. |
| -defaults | Normally setup requires that the user supply a plain
text file called Modules (in the FLASH root directory) which specifies
which code modules to include. A sample Modules file appears in
Figure 4. Each line is either a comment
(preceded by a hash mark (#)) or a module include statement of the
form INCLUDE module. Sub-modules are indicated by specifying the
path to the sub-module in question; in the example, the sub-module gamma
of the eos module is included. If a module has a default sub-module, but
no sub-module is specified, setup automatically selects the default
using information provided by the module's configuration file.
The purpose of the -defaults option is to enable setup to generate a ``rough draft'' of a Modules file for the user. The configuration file for each problem setup specifies a number of code module requirements; for example, a problem may require the perfect-gas equation of state (eos/gamma) and an unspecified hydro solver (hydro). With -defaults, setup creates a Modules file by converting these requirements into module include statements. In addition, it checks the configuration files for the required modules and includes any of their required modules, eliminating duplicates. This is only done for one level of requirement, but usually this is enough. Most users configuring a problem for the first time will want to run setup with -defaults to generate a Modules file, then edit Modules directly to specify different sub-modules (e.g., hydro solvers or I/O formats). After editing Modules in this way, re-run setup without -defaults to incorporate the changes into the code configuration. |
# Modules file constructed for rt problem by setup -defaults
INCLUDE driver
INCLUDE eos/gamma
INCLUDE grav
INCLUDE paramesh
INCLUDE mmpi
INCLUDE mpi_amr
INCLUDE hydro
INCLUDE io
| -[123]d | By default setup creates a makefile which produces a FLASH executable capable of solving one- or two-dimensional problems (equivalent to -2d). To generate a makefile with options appropriate to three-dimensional problems, use -3d. The resulting code will be able to solve 1D, 2D, or 3D problems. To generate a one-dimensional code, use -1d. While -3d provides maximum flexibility, it also allocates the most memory at runtime. It is generally very wasteful of memory to solve a 1D or 2D problem using an executable compiled with -3d. These options are mutually exclusive and cause setup to add the appropriate compilation option to the makefile it generates. |
| -maxblocks=# | This option is also used by setup in constructing the makefile compiler options. It determines the amount of memory allocated at runtime to the adaptive mesh refinement (AMR) block data structure. For example, to allocate enough memory on each processor for 500 blocks, use -maxblocks=500. If the default block buffer size is too large for your system, you may wish to try a smaller number here (the defaults are currently defined in source/driver/physicaldata.fh). Alternatively, you may wish to experiment with larger buffer sizes if your system has enough memory. |
The FLASH output comparison utility, or focu (pronounced faux-coup), is a command-line utility which compares FLASH output files according to specified criteria (e.g., local or global error criterion on any of the hydrodynamical variables) and reports whether they are the same or not. This is useful in determining whether a change to FLASH (or to the value of a runtime parameter) has changed the results obtained with a given problem.
The focu executable is configured and built in much the same way as is FLASH: obtain source tree, run setup to configure the source tree for a given architecture, and run make in the build directory. FLASH and focu are different in that focu is problem-independent, so only a machine type needs to be specified, and in that (at least at the present time) all of the modules included with focu are used, so setup is always run with the -defaults option. (See Section 4.1 for details regarding the usage of setup.) To summarize the steps in building focu:
Additional setup options are available and are interpreted as described in Section 4.1.
Running focu is very similar to running FLASH itself. First prepare a runtime parameter file, then run focu using
(or use the command used by your system to start MPI programs). Here N is the number of processors to use (which need not be the same as the number of processors used by the FLASH job which produced the output files to be read), and machine-type is the machine type specified in the setup step. If the parameter-file argument is not supplied, focu looks for a parameter file named focu.par in the current directory. The format of this file is identical to that used by FLASH (see Section 3).mpirun -np N focu_machine-type parameter-file
The runtime parameters understood by focu are as follows. Default values are listed in brackets following each description.
| file1 | Base file name for the first file to compare. The file name will be constructed by appending the file number, padded with zeros to four places, to the base file name. [``file1''] |
| num1 | The file number for the first file to compare. [0] |
| format1 | The format of the first file: ``HDF'' for Hierarchical Data Format, ``F77'' for Fortran unformatted. [``HDF''] |
| file2 | Base file name for the second file to compare. [``file2''] |
| num2 | File number for the second file. [0] |
| format2 | Format for the second file. [``HDF''] |
| variable | The name of the hydrodynamical variable to examine. Available values are ``density,'' ``pressure,'' ``x velocity,'' ``y velocity,'' ``z velocity,'' ``temperature,'' ``energy,'' ``kinetic energy,'' ``internal energy,'' ``x momentum,'' ``y momentum,'' ``z momentum,'' and ``abundance N,'' where N is the index of the abundance to use. [``density''] |
| criterion | The error criterion to apply in comparing the files. This must be of the form ``A B'', where A is either ``local'' or ``global,'' and B is either ``sum,'' ``min,'' or ``max.'' For the global criteria, focu first computes the volume-weighted average, minimum value, or maximum value of variable for each file, then computes the L1 deviation between the two global quantities. For the local criteria, the files are compared on a zone-by-zone basis. Consequently the AMR block structures of the two files must be the same in order for the comparison to succeed. If criterion is ``local sum,'' the volume-weighted average of the local L1 deviations is compared to threshold to determine success or failure. If criterion is ``local min'' or ``local max,'' the minimum or maximum L1 deviation is compared. The L1 deviation for two quantities X1 and X2 is defined as |X2-X1| / max{1/2|X1+X2|,10-99}. [``global sum''] |
| threshold | The error threshold to use in deciding success or failure. [10-6] |
| outfile | The name of the output file to create when generating the comparison report. Setting this to ``stdout'' causes focu to write to standard output. [``stdout''] |
FOCU: Flash Output Comparison Utility
Comparing: ßedov_4_f77_" # 3 ßedov_4_hdf_" # 3 Variable: density Criterion: local sum Threshold: 1.0000000000000E-09 Result: Error: 0.0000000000000E+00 Minimum: 0.0000000000000E+00 Maximum: 0.0000000000000E+00 SUCCESS
The output of focu is a short report listing the volume-averaged sum, minimum, and maximum deviations (local or global, depending on the setting of criterion) and reporting SUCCESS or FAILURE according to the supplied threshold. For example, if two runs of FLASH are performed using the Sedov problem, one with HDF output and one with Fortran unformatted output, the resulting output files should be identical. The report generated by a focu comparison of two such files is shown in Figure 5. Note that the last line of the report begins with SUCCESS or FAILURE, making it easy for a script to test the results. For example, with csh one might use
focu is used by the automated FLASH test script (Section 5.1) to compare FLASH outputs to the reference results supplied as part of the test suite.set result = `mpirun -np 2 focu_irix focu_sedov.par | grep SUCCESS`
if ("result" == "SUCCESS") then
...
endif
fidlr is a set of routines, written in the IDL language, which provide tools for plotting results obtained with FLASH. The routines include programs which can be run from the IDL command line to read 2D or 3D FLASH datasets and interpolate them onto uniform grids. An IDL program called xflash provides a graphical interface to these routines, enabling users to read and plot 2D AMR datasets without interpolating onto a uniform mesh.
The FLASH IDL routines are located in the tools/fidlr/ subdirectory of the FLASH root directory. To use them you must set two environment variables. First set the value of XFLASH_DIR to the location of the FLASH IDL routines; for example, under csh, use
setenv XFLASH_DIR flash-root-path/tools/fidlr
where flash-root-path is the absolute path of the FLASH root directory. Next add this directory to your IDL_PATH variable:
setenv IDL_PATH "${XFLASH_DIR}:$IDL_PATH"
If you have not previously defined IDL_PATH, omit :$IDL_PATH from the above command. You may wish to include these commands in your .cshrc file (or profile if you use another shell) to avoid having to reissue them every time you log in.
To begin using the routines, start IDL (idl). You may wish to make use of the program start.pro included with fidlr; this forces the use of an eight-bit colormap on 24-bit displays which have the ability to maintain two color depths (such as those found on SGIs). To use this program, start IDL using idl start.pro.
xflash provides a graphical interface to IDL for plotting one or several 2D AMR datasets. It plots variables using a shaded colormap and can overlay the outline of the AMR block structure or arrows showing the velocity field. It also enables users to zoom in to different regions of the dataset and to probe the dataset.
To use the graphical tool, from the IDL command line (idl>)
execute xflash. The widget is divided into sections controlling
the file location, output type, problem, variable to plot, colormap, plot
options, data range, zooming, and velocity vectors. At the bottom is
a status display. See Figure 2 for an example of the
appearance of the xflash window.
File location
The files to be read are specified by entering a path (by default the
current IDL working directory), a base name, and a range of suffixes.
If only the first suffix is entered, only that one is used; otherwise
all integers between the beginning and ending suffix are used.
Select the file type by choosing ``HDF'' for Hierarchical Data Format
or ``F77'' for Fortran unformatted output. At present the Fortran
reader does not convert little-endian files to big-endian or vice versa.
Output device
It is possible to direct output to the screen, to a Postscript file, or
to a GIF image. The plotting routine
will determine the orientation (portrait or landscape) using the
aspect ratio of the
domain to be plotted, and it will plot the largest area that maintains
this ratio.
Problem
The problem buttons load default data ranges, axis orientation, and
velocity information for different problems. New problems can be added
quite easily by modifying the file tools/fidlr/xflash_defaults.pro.
It is not necessary to add a problem in order to plot a dataset.
The problem selection exists only to provide rational default values
for data ranges; these values can be overridden through the widget.
Variables
Presently the following variables can be plotted: temperature, density,
pressure, total energy, velocity magnitude, and abundance conservation
error. The latter is the difference between the sum of the nuclear
abundances in a zone and unity. The choice of problem and variable
affects the default data range chosen.
Colormap
The colormaps used by xflash differ from the standard IDL
colormaps. The first 12 colors are uniform across the colormaps and
contain standard colors (red, green, blue, white, black) that are
used to set the background color, text color, and so forth.
Plotting options
Two plotting options are currently available. The ``log'' option plots
the common logarithm of the chosen variable, while the ``show blocks''
option overlays the boundaries of the AMR block structure on the colormap
used to represent the variable. For AMR grids with many levels of
refinement, the block boundaries can completely obscure the colormap;
however, this option can be useful for verifying that resolution elements
are being placed where they are needed.
Data range
The default data range may be overridden if desired by entering a new
minimum or maximum value here. The values of the defaults are set in
tools/fidlr/xflash_defaults.pro.
Zoom
A value of -1 here indicates that the default position for the
corresponding limit is to be used. Leave each limit at -1 to plot the
entire grid, or enter different limits to plot a smaller part of the
grid.
Velocity vectors
If this box is checked, velocity arrows will be overlaid on the colormap.
The arrow lengths are scaled according to a ``typical'' velocity
magnitude, and magnitudes outside of a specified range are not plotted.
The values of the typical velocity and the clipping range are set in
tools/fidlr/xflash_defaults.pro. If the velocity vector box is
checked, the xskip and yskip options become selectable. These options
set the number of zones to skip in each direction when plotting arrows.
For highly refined meshes this can help one to avoid obscuring the
colormap with arrows.
Control buttons
Once all of the options are set, press the ``Plot'' button to produce the plot. The status of the plot appears in the status window below the buttons. If only a single plot is made (ie. only one suffix was specified), additional plots can be made without reading in the dataset again. This permits one to easily experiment with color tables, data ranges, and so forth. Once the plot is complete, press the ``Query'' button and click anywhere in the plot to probe the dataset. Mouse clicks will bring up a window showing the position of the click and the values of the hydrodynamical variables at that position.
Press the ``Quit'' button to terminate the widget.
Following is a description of each of the IDL routines included with the
FLASH IDL tools in the tools/fidlr subdirectory.
Main programs
| xflash.pro | Widget routine and event handler. |
| xflash_defaults.pro | Contains problem-specific defaults. |
| xplot_amr.pro | Main plotting routine, called by xflash. |
| read3_amr.pro | Reads block-structured AMR data from an HDF 4 file. The data are stored in common blocks. |
| read_amr_f77.pro | Reads block-structured AMR data from a Fortran unformatted file. The data are stored in common blocks. |
| def_common.pro | Defines the common blocks which hold the AMR data. Run this from the command line in order to access the AMR data structure directly (e.g., in order to pass a variable name to one of the uniform resampling routines). |
| merge_amr.pro | Resamples a given AMR data structure on a uniform grid of a given coarseness. Currently the only way to manipulate 3D data. |
| scale2_amr.pro | Resamples a given AMR data structure on a uniform grid, producing a byte array for plotting purposes. |
Plotting routines
| partvelvec.pro | Plots velocity vectors. |
| draw_blocks.pro | Plots the outline of the AMR block structure. |
| colorbar2.pro | Produces a horizontal color key. |
| vcolorbar.pro | Produces a vertical color key. |
| cmcongrid.pro | A special version of congrid used by tvimage. |
| color_gif.pro | Captures a window and saves it to a GIF file. |
| nolabel.pro | A hack to allow unlabelled axes. |
| start.pro | When run at the start of an IDL session, sets up an eight-bit X visual on a 24-bit display (when supported by the X server). |
| tvimage.pro | Similar to the IDL tv command, but allows a byte array to be drawn on the screen or directly into a Postscript file. |
| undefine.pro | Frees up memory used by AMR data structures. |
Go on to Section 5.