for George Vahala

Plot_surf creates graphics output files (frames) from vorticity or energy data files. Each frame created can contain a surface plot and/or an image plot from a time step from either one or two vorticity or energy data files. Each frame file written is a GIF image, which can be combined with other frames to make a movie. See Step 7 in "Usage" for how to do this.

Plot_surf uses IDL for its graphics routines. Besides creating the frame files, plot_surf can also plot to an X window.

The following steps detail how you access and use plot_surf.

1. Log on to escher.nersc.gov
2. Load IDL by doing:

% module load idl

% idl

 

3. When the IDL prompt is shown, you need to load and compile the plot_surf routines. (Note: there is a period in front of the word 'compile'.)

IDL> .compile /usr/local/pkg/graphics/plot_surf/plot_surf.pro

4. Now you can start creating your frames. See Examples below for using plot_surf. Complete descriptions of the parameters that control various action of plot_surf are detailed under Parameters below.
5. After creating your frames, to exit IDL type:

IDL> exit

6. You can view individual frames from escher.nersc.gov to your local X-workstation by doing:

% module load xv

% xv outf0003

Typing a 'q' in the display window will exit 'xv'. To use 'xv', you must have set the 'DISPLAY' environment variable.

7. Two ways of making a movie are detailed here. The first method is using SGI's 'mediaconvert'. Mediaconvert has a user interface and how to use it is detailed at /NERSC/HowTos/mpeg/ Please follow the steps exactly. The second method is to do:

Example 1: Create a series of frames for two vorticity files (vort.1 and vort.2). Each frame shows the data of each file in two forms: a surface plot and an image plot. The minimum and maximum of each data file is computed. The Z-axis for the plots is then computed (or scaled) where zmin = min(file1_min,file2_min) and zmax=max(file1_max,file2_max) Also, 30 title frames are generated. Each title frame gives the date that the program was run and the name of the data files (i.e., vort.1 & vort.2). The number of data frames created is computed from the number of time steps found in the data files.

Example 2: This example is similar to "Example 1", but the frames are created for just one vorticity files (vort.1).

Example 3: The same as example 1, except 10 data frames are created from the first 10 time steps, no title frames are created, and the zmin & zmax is not scaled between the data files.

Example 4: The same as example 3, except 5 title frames are created.

Example 5: This example creates frames which contain only a surface plot for each time step.

Example 6: Same as example 5, but the resolution of each frame file is 512 x 512 (pixels). This is more appropriate than the default resolution of 640x480 when you are doing only an image or surface plot. Please note that this does not change the X window size, only the GIF frames created.

Example 7: To process only the first frame on an X-window and see the values of all the parameters (useful for debugging purposes) do:

The following are optional parameters to the plot_surf program. Parameters can either be capitalized or not. Also, the parameters PREVIEW and STAT can be passed with a value or as a flag. For example, to get status information you can either say STAT=1 or /STAT. You can also abbreviate parameter names as long as there is no ambiguity. For example, 'file1_range' can be abbreviated to 'file1', but not 'file'. 'file' is not acceptable because there is ambiguity between using 'file1_range' or 'file2_range'.

A two-dimensional Array that specifies the size of each data time step in x and y. The default is 64x64.

Example:

The name of the file that contains the color table to use. The color system used is RGB where each color component various from 0 to 255, where 0,0,0 is black and 255,255,255 is white, and there are 256 entries for each component. The file must be an ASCII file where all the reds are first defined followed by the greens and then the blues. The default file is: /usr/local/pkg/graphics/plot_surf.

The minimum and maximum of each data file is automatically computed unless you pass the minimum and maximum for the specified with the appropriate keyword (FILE1_RANGE or FILE2_RANGE). If the program computes the minimum & maximum for you, the whole file is searched. This is true even if you have passed the number of time steps to process. When the minimum and maximum is computed, the number of time steps is also computed and will be used unless NSTEPS is defined. (See NSTEPS for more information on this.) Please note that finding the minimum and maximum can be a time-consuming operation on large files.

Examples:

The number of time steps (frames) to process. Each time step will create a separate GIF file of the form <name>nnnn. Unless you specify a new prefix and/or suffix, the files created will be of the form: outf0001 to outfnnnn. The actual number of times steps processed and the number of frames produced is the minimum of the number of time steps in the two files (if the system computes the minimum and maximum) and the value of NSTEPS, if passed.

Example:

The name of the frames or output files created is a combination of OUTFILE and START_NUMBER where 'out file' is the prefix and 'start_number' is the suffix. By default, the first frame created is outf0001 followed by outf0002, …, outfnnnn. Please note that if title frames are produced that will start either at outf00001 or START_NUMBER. Also, note that the number of frames created is the total of the number of title frames and the number of time steps plotted.

Defines the prefix to use for the files or frames created. The default name is 'outf'.

Example: OUTFILE='vortice'

A number that defines the first suffix of the frame file. Each subsequent frame file will increase by one.

Will create files named outf0900, outf0901,…..

The type of output created for each frame. By default, the same frame contains both an image and a surface plot. You can change the type of plots produced by this argument.

PLOT_TYPE=1 ( Both an image and a surface plot is created (default) for each time step.)

PLOT_TYPE=2 (Only an image plot is produced for each time step.)

PLOT_TYPE=3 (Only a surface plot it produced for each time step.)

If this flag is defined (PREVIEW=1), all output is sent to an X-window instead of creating individual GIF-files. You must have set the X environment variable to display to your workstation (i.e., SETENV DISPLAY myworkstation:0) and granted permission to Escher to plot to your workstation (i.e., xhost +escher.nersc.gov).

Examples:

PREVIEW=1

/PREVIEW

The size of the GIF output files in pixels. The default size is 640 by 480. 'Resolution' is a two-dimensional array and defines width x length.

Examples:

Resolution=[512,512]

Resolution=[xmin,ymin]

By default, the z-axis used for the plots is a combination of the minimum and maximum of both data files (if two datafiles are specified). That is, Zmin = min(File1_min,File2_min) and Zmax = max(file1_max,File2_max). These values are then used for both data files. This feature can be turned off by specifying the /NOSCALE flag and having each data file use its own min and max for the z-axis.

Example:

If nonzero, the values for the parameters are printed. This is useful for debugging purposes.

Examples:

The angle for the z-plane expressed in degrees. The default is 30 degrees.

Example:

There are a number of parameters that control how and if movies titles are added before the beginning of the movie. Title controls the number of titles frames (30 is the default if Title is not defined). NOTitle eliminates creating any movie titles. The text used is composed of two lines. The first line is in the center of the frame and can be either specified or if not specified, lists the name of the file(s) plotted. The second line of text contains the date the program was run. You can change the text of the first line by defining HEAD_TITLE.

Example 1: 5 title frames will be generated

Example 2: Eliminate the title frames

Example 3: Create 30 title frames (default) but define a new center title