Plotting using Matlab

Before version 4.3, Clawpack used Matlab (Mathworks, Inc.) for plotting and visualizing results of simulations. For this purpose, an extensive set of plotting tools were developed. These are still available in $CLAW/visclaw/src/matlab. The user interface for these routines is essentially unchanged from the previous versions, although several new features have been added.

These graphics tools extend standard Matlab plotting routines by allowing for easy plotting of both 2d and 3d adaptively refined mesh data produced from AMRClaw and solutions on 2d manifolds, produced from either single grid Clawpack, or AMRClaw. In each of these cases, the user can easily switch on or off the plotting of grid lines (on a per-level basis), contour lines, isosurfaces, and AMR patch borders, cubes and other graphical items. In 3d, the user can create a custom set of slices, and then loop through the slices in the x,y or z directions. All visualization assumes finite volume data, and individual plot “patches” use cell-averaged values to color mesh cells directly. No graphical interpolation is done when mapping to the colormap.

The Matlab search path

To use the Matlab plotting tools with Clawpack, the user will need to first be sure that the necessary Matlab routines are on the Matlab search path. This can be done by explicitly setting the MATLABPATH environment variable. In bash, this is done via

$ export MATLABPATH ${CLAW}/visclaw/src/matlab

Alternatively, one can permanently add this directory to the Matlab search path using the Matlab “pathtool” command:

>> pathtool

Creating output files

To visualize Clawpack output using the Matlab plotting routines, first produce output files from an example using:

$ make .output

This will build the appropriate Clawpack executable, create necessary input files for the executable, and finally run the executable to create output files. These output files are stored by default in the directory ‘_output’.

The plotclaw command

Once output files, e.g. ‘fort.q0000’, ‘fort.q0001’, and so on, and corresponding fort.t0000’ or ‘fort.t0001’ files have been created, the user can plot them in Matlab by entering one of the following commands (depending on whether the output is one, two or three dimensional) at the Matlab prompt:

>> plotclaw1

or:

>> plotclaw2

or:

>> plotclaw3

Initially, the user is prompted to run a file `setplot`_. For example:

>> plotclaw2

plotclaw2  plots 2d results from clawpack or amrclaw
Execute setplot2 (default = yes)?

The setplot file sets various parameters in the base workspace needed to create the plot (see below for more details on this file). Entering [enter] at this prompt will run the file.

Successively hitting [enter] steps through and plots data from each of the fort files in order. In one and two dimensions, this plotting prompt is:

Frame 2 at time t = 0.2
Hit <return> for next plot, or type k, r, rr, j, i, q, or ?

In three dimensions, one can optionally step through user defined slices of data by entering ‘x’, ‘y’ or ‘z’ at the command prompt:

Frame 1 at time t = 0.0625
Hit <return> for next plot, or type k, r, rr, j, i, x, y, z, q, or ?

A description of the plot prompt options is given by entering ‘?’:

Frame 2 at time t = 0.2
Hit <return> for next plot, or type k, r, rr, j, i, q, or ?  ?
  k  -- keyboard input.  Type any commands and then "return"
  r  -- redraw current frame, without re-reading data
  rr -- re-read current file,and redraw frame
  j  -- jump to a particular frame
  i  -- info about parameters and solution
  x  -- loop over slices in x direction (3d only)
  y  -- loop over slices in y direction (3d only)
  z  -- loop over slices in z direction (3d only)
  q  -- quit

After the graphics routines have created the plot, but before the user is returned to the plot prompt, a file afterframe is called. This file contains user commands to set various plot properties. See below for more details on what the user might wish to include in this file.

The setplot file

The properties of the Matlab plot are controlled through two main user-defined files located, typically, in the current working directory. The first of these files, the ‘setplot’ file (e.g. setplot1.m, setplot2.m or setplot3.m) control basic plot properties that must be known before the plot is created. Such properties include

  • component of q to plot, (.e.g. rho=1, rhou=2, rhov=3 and so on).
  • a user defined quantity (e.g. pressure or velocity) to plot,
  • the maximum number of frames to plot
  • the location of the output files
  • the line type or symbol type for 1d plots or scatter plots. Different symbols or line types can be specified for each AMR level.
  • the plot type, e.g. a pseudo-color plot, a Schlieren type plot or a scatter plot.
  • grid mappings for mapped grids or manifold calculations,
  • user defined slices through the data (3d data)
  • isosurface properties (3d plots)

A typical setplot file might contain the following parameter settings:

% -----------------------------------------------
% file: setplot2.m (not all parameters are shown)
% -----------------------------------------------
OutputDir = '_output';
PlotType = 1;                % Create a pseudo-color plot
mq = 1;                      % which component of q to plot
UserVariable = 0;            % set to 1 to specify a user-defined variable
UserVariableFile = ' ';      % name of m-file mapping data to q
MappedGrid = 0;              % set to 1 if mapc2p.m exists for nonuniform grid
MaxFrames = 1000;            % max number of frames to loop over
MaxLevels = 6;               % max number of AMR levels
...

One of the main uses of the ‘keyboard’ option described in the plotclaw section is to allow the user to temporarily change the value of plotting parameters set in the setplot file.

To ensure that the required set of variables is defined, the user is encouraged to create and modify a local copy of setplot1.m, setplot2.m or setplot3.m found in ‘${CLAW}visclaw/src/matlab’.

To get more help on what types of settings can be specified in the setplot file, enter the following command:

>> help setplot

Each of the examples in Clawpack include a ‘setplot’ file which you can browse to get an idea as to what can be put in the file.

The afterframe file

The ‘afterframe.m’ script is the second file which control aspects of the plot and is called after the plot has been created. The following are commonly set in the afterframe file:

  • set axis limits and scaling
  • add a 1d reference solution (1d plots and scatter plots)
  • print out the current frame to a png, jpg or other graphics format file.
  • add, show or hide contour lines on slices (2d/3d)
  • show or hide AMR patch and cube borders (2d/3d)
  • modify the colormap (2d/3d)
  • set the color axis (2d/3d)
  • show or hide grid lines on different AMR levels (2d/3d)
  • add lighting to isosurfaces (3d)
  • hide or show isosurfaces (3d)
  • show or hide slices (3d)

A typical ‘afterframe’ file might contain the following commands:

% -----------------------------------------------
% file: afterframe.m
% -----------------------------------------------
axis([-1 1 -1 1]);      % Set the axis limits
daspect([1 1 1]);       % Set the aspect ratio

colormap(jet);

showpatchborders;       % Show outlines of AMR patch borders
showgridlines(1:2);     % Show gridlines on level 1 and 2 grids

cv = linspace(-1,1,21); % Values for contour levels
cv(cv == 0) = [];
drawcontourlines(cv);   % add contour lines to a plot

caxis([-1 1]);          % Set the color axis

shg;                    % Bring figure window to the front

fstr = framename(Frame,'frame0000','png','_plots');
print('-dpng',fstr);       % Create .png file of figure.

clear afterframe;

The final ‘clear’ statement is added so that any modifications that the user makes to the afterframe file while stepping through plot frames will take effect immediately.

When plotting results from AMR runs, the user can also create an ‘aftergrid.m’ file. This file will be called after each individual grid of data is plotted.

The user is encouraged to browse the ‘afterframe.m’ file available with each Clawpack example to get a better idea as to what one might include in this file.

Getting help

To get help on any of the topics available in the Matlab graphics tools, you can always issue the command:

>> help clawgraphics

at the Matlab prompt. This will bring up a list of topics which you can get further help on.

Trouble shooting

Below are a few potential problems one can run into with the Matlab plotting routines.

Output files not found

The following error message indicates that the output files have not been found:

Hit <return> for next plot, or type k, r, rr, j, i, x, y, z, q, or ?

Frame 2 (./fort.t0002) does not exist ***


Frame 2(ascii) does not exist ***

Be sure to check that that the variable ‘OutputDir’, set in the setplot file, points to the proper location of the output files that you wish to plot. Second, double check that you actually have fort.[t/q]XXXX files in that directory.

MaxFrames not set

The error message below most likely means that a ‘setplot’ script containing a definition for MaxFrames was not run:

>> plotclaw2

plotclaw2  plots 2d results from clawpack or amrclaw
Execute setplot2 (default = yes)? no

MaxFrames parameter not set... you may need to execute setplot2

To correct this problem, the user should make sure that they have local copy of a setplot file in their working directory, that it defines the required set of variables and that it is run at least once before the plotclaw command.

Switching examples

The graphics are controlled to a large extent using variables that are set in the Matlab base workspace. This can lead to unpredictable results when switching between Clawpack examples.

To illustrate what can go wrong, suppose one sets:

MappedGrid = 1;         % assumes that mapc2p file exists

in the setplot file for one example, and then switches to a second example which is not a simulation on a mapped grid. If the variable ‘MappedGrid’ is not explicitly set to zero in the setplot file for the second example, the Matlab routines will look for a grid mapping file ‘mapc2p.m’ which may not be found for the second example.

To avoid such potential clashes of variables, the user is strongly encouraged to enter the command:

>> clear all;

before switching examples. This will clear the base workspace of all plotting parameters and avoid potential conflicts in base variable settings.

The user is also encouraged to issue a command:

>> close all

in situations where the one example explicitly sets plotting features such as a colormap, or axes scaling that are not overridden by subsequent plot commands.