[cig-commits] r1366 - in trunk/aspect/doc/manual: . viz viz/statistics
bangerth at dealii.org
bangerth at dealii.org
Thu Nov 15 06:44:14 PST 2012
Author: bangerth
Date: 2012-11-15 07:44:14 -0700 (Thu, 15 Nov 2012)
New Revision: 1366
Added:
trunk/aspect/doc/manual/viz/
trunk/aspect/doc/manual/viz/statistics/
trunk/aspect/doc/manual/viz/statistics/1.png
trunk/aspect/doc/manual/viz/statistics/2.png
Modified:
trunk/aspect/doc/manual/manual.tex
Log:
Complete section on gnuplot.
Modified: trunk/aspect/doc/manual/manual.tex
===================================================================
--- trunk/aspect/doc/manual/manual.tex 2012-11-15 00:00:58 UTC (rev 1365)
+++ trunk/aspect/doc/manual/manual.tex 2012-11-15 14:44:14 UTC (rev 1366)
@@ -28,11 +28,14 @@
\end{center}
}}
-% use the listings package for code snippets
+% use the listings package for code snippets. define keywords for prm files
+% and for gnuplot
\usepackage{listings}
\lstset{language=C++,basicstyle=\footnotesize}
\lstdefinelanguage{prmfile}{morekeywords={set,subsection,end},
morecomment=[l]{\#},}
+\lstdefinelanguage{gnuplot}{morekeywords={plot,using,title,with,set,replot},
+ morecomment=[l]{\#},}
% use the hyperref package; set the base for relative links to
% the top-level aspect directory so that we can link to
@@ -1740,26 +1743,38 @@
In addition to the graphical outputdiscussed above, \aspect{} produces a
statistics file that collects information produced during each time step.
+For the remainder of this section, let us assume that we have run \aspect{}
+with the input file discussed in Section~\ref{sec:cookbooks-simple-box},
+simulating convection in a box. After running \aspect{}, you will find
+a file called \texttt{statistics} in the output directory that, at the time
+of writing this, looked like this:
This file has a structure that looks like this:
\begin{lstlisting}[frame=single,language=ksh]
# 1: Time step number
-# 2: Time (years)
-# 3: Iterations for Stokes solver
-# 4: Time step size (year)
-# 5: Iterations for temperature solver
-# 6: Visualization file name
-# 7: RMS velocity (m/year)
-# 8: Max. velocity (m/year)
-# 9: Minimal temperature (K)
-# 10: Average temperature (K)
-# 11: Maximal temperature (K)
-# 12: Average nondimensional temperature (K)
-# 13: Core-mantle heat flux (W)
-# 14: Surface heat flux (W)
-0 0.0000e+00 33 2.9543e+07 8 "" 0.0000 0.0000 0.0000 0.0000 ...
-0 0.0000e+00 34 1.9914e+07 8 output/solution-00000 0.0946 0.1829 300.0000 3007.2519 ...
-1 1.9914e+07 33 1.9914e+07 8 output/solution-00001 0.1040 0.2172 300.0000 3007.8406 ...
-2 3.9827e+07 33 1.9914e+07 8 "" 0.1114 0.2306 300.0000 3008.3939 ...
+# 2: Time (seconds)
+# 3: Number of mesh cells
+# 4: Number of Stokes degrees of freedom
+# 5: Number of temperature degrees of freedom
+# 6: Iterations for temperature solver
+# 7: Iterations for Stokes solver
+# 8: Time step size (seconds)
+# 9: RMS velocity (m/s)
+# 10: Max. velocity (m/s)
+# 11: Minimal temperature (K)
+# 12: Average temperature (K)
+# 13: Maximal temperature (K)
+# 14: Average nondimensional temperature (K)
+# 15: Outward heat flux through boundary with indicator 0 (W)
+# 16: Outward heat flux through boundary with indicator 1 (W)
+# 17: Outward heat flux through boundary with indicator 2 (W)
+# 18: Outward heat flux through boundary with indicator 3 (W)
+# 19: Visualization file name
+ 0 0.0000e+00 256 2467 1089 1 22 1.2225e-02 1.79038621e+00 2.54812273e+00 ...
+ 1 1.2225e-02 256 2467 1089 40 16 3.7409e-03 5.88727814e+00 8.34299267e+00 ...
+ 2 1.5966e-02 256 2467 1089 25 15 2.0249e-03 1.08925316e+01 1.54185045e+01 ...
+ 3 1.7991e-02 256 2467 1089 19 15 1.3658e-03 1.61586242e+01 2.28690070e+01 ...
+ 4 1.9357e-02 256 2467 1089 16 14 1.0291e-03 2.14311381e+01 3.03519178e+01 ...
+ 5 2.0386e-02 256 2467 1089 14 14 8.2853e-04 2.65966688e+01 3.76989179e+01 ...
\end{lstlisting}
In other words, it first lists what the individual columns mean with a hash
@@ -1777,10 +1792,138 @@
of a full fledged spreadsheet engine and simply plot graphs. One that is
particularly simple to use and available on every major platform is \texttt{Gnuplot}.
It is extensively documented at \url{http://www.gnuplot.info/}.
-
-\marginpar{To be written}
+\texttt{Gnuplot} is a command line program in which you enter commands that
+plot data or modify the way data is plotted. When you call it, you will first
+get a screen that looks like this:
+\begin{lstlisting}[frame=single]
+/home/user/aspect/output$ gnuplot
+ G N U P L O T
+ Version 4.6 patchlevel 0 last modified 2012-03-04
+ Build System: Linux x86_64
+
+ Copyright (C) 1986-1993, 1998, 2004, 2007-2012
+ Thomas Williams, Colin Kelley and many others
+
+ gnuplot home: http://www.gnuplot.info
+ faq, bugs, etc: type "help FAQ"
+ immediate help: type "help" (plot window: hit 'h')
+
+Terminal type set to 'qt'
+gnuplot>
+\end{lstlisting}
+At the prompt on the last line, you can then enter commands. Given the
+description of the individual columns given above, let us first try to
+plot the heat flux through boundary 2 (which in this case is the bottom
+boundary of the box), i.e., column 17, as a function of time (column 2).
+This can be achieved using the following command:
+\begin{lstlisting}[frame=single,language=gnuplot]
+ plot "statistics" using 2:17
+\end{lstlisting}
+The left panel of Fig.~\ref{fig:viz-gnuplot-1} shows what \texttt{Gnuplot}
+will display in its output window. There are many things one can
+configure in these plots (see the \texttt{Gnuplot} manual referenced above).
+For example, let us assume that we want to add labels to the $x$- and $y$-axes,
+use not just points but lines and points for the curves,
+restrict the time axis to the range $[0,0.2]$ and the heat flux axis to
+$[-10:10]$,
+plot not only the flux through the bottom but also through the top boundary
+(column 18) and finally add a key to the figure, then the following
+commands achieve this:
+\begin{lstlisting}[frame=single,language=gnuplot]
+ set xlabel "Time"
+ set ylabel "Heat flux"
+ set style data linespoints
+ plot [0:0.2][-10:10] "statistics" using 2:17 title "Bottom boundary", \
+ "statistics" using 2:18 title "Top boundary"
+\end{lstlisting}
+If a line gets too long, you can continue it by ending it in a backslash as
+above. This is rarely used on the command line but useful when writing the
+commands above into a script file, see below. We have done it here to get
+the entire command into the width of the page.
+
+\begin{figure}
+ \centering
+ \phantom.
+ \hfill
+ \includegraphics[width=0.4\textwidth]{viz/statistics/1}
+ \hfill
+ \includegraphics[width=0.4\textwidth]{viz/statistics/2}
+ \hfill
+ \phantom.
+ \caption{Visualizing the statistics file obtained from the example in
+ Section~\ref{sec:cookbooks-simple-box} using \texttt{Gnuplot}: Output
+ using simple commands.}
+ \label{fig:viz-gnuplot-1}
+\end{figure}
+
+For those who are lazy, \texttt{Gnuplot} allows to abbreviate things in many
+different ways. For example, one can abbreviate most commands. Furthermore,
+one does not need to repeat the name of an input file if it is the same
+as the previous one in a plot command. Thus, instead of the commands above,
+the following abbreviated form would have achieved the same effect:
+\begin{lstlisting}[frame=single,language=gnuplot]
+ se xl "Time"
+ se yl "Heat flux"
+ se sty da lp
+ pl [:0.2][-10:10] "statistics" us 2:17 t "Bottom boundary", "" us 2:18 t "Top boundary"
+\end{lstlisting}
+This is of course unreadable at first but becomes useful once you become
+more familiar with the command offered by this program.
+
+Once you have gotten the commands that create the plot you want right, you probably
+want to save it into a file. \texttt{Gnuplot} can write output in many
+different formats. For inclusion in publications, either \texttt{eps} or
+\texttt{png} are the most common. In the latter case, the commands to
+achieve this are
+\begin{lstlisting}[frame=single,language=gnuplot]
+ set terminal png
+ set output "heatflux.png"
+ replot
+\end{lstlisting}
+The last command will simply generate the same plot again but this time
+into the given file. The result is a graphics file similar to the one
+shown in Fig.~\ref{fig:convection-box-stats} on page \pageref{fig:convection-box-stats}.
+
+\note{After setting output to a file, \textit{all} following plot commands will
+ want to write to this file. Thus, if you want to create more plots after
+ the one just created, you need to reset output back to the screen. On linux,
+ this is done using the command \texttt{set terminal X11}. You can then
+ continue experimenting with plots and when you have the next plot ready,
+ switch back to output to a file.}
+
+What makes \texttt{Gnuplot} so useful is that it doesn't just allow entering
+all these commands at the prompt. Rather, one can write them all into a file,
+say \texttt{plot-heatflux.gnuplot}, and then, on the command line, call
+\begin{lstlisting}[frame=single,language=ksh]
+ gnuplot plot-heatflux.gnuplot
+\end{lstlisting}
+to generate the \texttt{heatflux.png} file. This comes in handy if one wants
+to create the same plot for multiple simulations while playing with parameters
+of the physical setup. It is also a very useful tool if one wants to generate
+the same kind of plot again later with a different data set, for example when
+a reviewer requested additional computations to be made for a paper or if one
+realizes that one has forgotten or misspelled an axis label in a plot.%
+\footnote{In my own work, I usually save the \aspect{} input file, the
+ \texttt{statistics} output file and the \texttt{Gnuplot} script along with
+ the actual figure I want to include in a paper. This way, it is easy to
+ either re-run an entire simulation, or just tweak the graphic at a later
+ time. Speaking from experience, you will not believe how often one wants
+ to tweak a figure long after it was first created. In such situations it is
+ outstandingly helpful if one still has both the actual data as well as the script
+ that generated the graphic.}
+
+\texttt{Gnuplot} has many many more features we have not even touched upon. For
+example, it is equally happy to produce three-dimensional graphics, and it also
+has statistics modules that can do things like curve fits, statistical regression,
+and many more operations on the data you provide in the columns of an input file.
+We will not try to cover them here but instead refer to the manual at
+\url{http://www.gnuplot.info/}. You can also get a good amount of information
+by typing \texttt{help} at the prompt, or a command like \texttt{help plot} to
+get help on the \texttt{plot} command.
+
+
\subsubsection{Large data issues for parallel computations}
\label{sec:viz-data}
@@ -2460,7 +2603,8 @@
Fig.~\ref{fig:convection-box-stats} shows the results of visualizing the data
that can be found in columns 2 (the time) plotted against columns 9 and 10
(root mean square and maximal velocities). Plots of this kind can be generated with
-\texttt{gnuplot} by typing:
+\texttt{Gnuplot} by typing (see Section~\ref{sec:viz-stat} for a more thorough
+discussion):
\begin{verbatim}
plot "output/statistics" using 2:9 with lines
\end{verbatim}
Added: trunk/aspect/doc/manual/viz/statistics/1.png
===================================================================
(Binary files differ)
Property changes on: trunk/aspect/doc/manual/viz/statistics/1.png
___________________________________________________________________
Added: svn:mime-type
+ image/png
Added: trunk/aspect/doc/manual/viz/statistics/2.png
===================================================================
(Binary files differ)
Property changes on: trunk/aspect/doc/manual/viz/statistics/2.png
___________________________________________________________________
Added: svn:mime-type
+ image/png
More information about the CIG-COMMITS
mailing list