.. _matlabplots: *************************************** Plotting using Matlab *************************************** .. _Matlab: http://www.mathworks.com 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. .. _setting_up_matlab: 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 .. _create_output_for_matlab: 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'. .. _plotclaw: 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 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 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 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. .. _matlab_setplot: 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. .. _afterframe: 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. .. _matlab_help: 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. .. _base_variables: 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 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. .. _matlab_gallery: Matlab Gallery -------------- The interested user is encouraged to browse the `Matlab Gallery`_ for examples of the types of plots that can be created with the Clawpack Matlab plotting routines. .. _Matlab Gallery: http://math.boisestate.edu/~calhoun/visclaw/matlab_gallery/test_graphics/index.html