plot.tex

%  Changed by: Chris ISELIN, 27-Jan-1997 
%  Changed by: Hans Grote, 25-Sep-2002 
%  Changed by: E. T. d'Amico, 20-Oct-2004 
%  Changed by: G. Roy, 2013-2104

\chapter{Plotting data}
\label{chap:plot}

Values contained in \madx tables can be plotted directly in \madx in the
form column versus column, with up to four differently scaled vertical
axes and up to 10 different variables in total for all vertical axes.

If the horizontal axis is the position "s" of the elements
in a sequence, a symbolic representation of the beamline can also
be displayed at the top of the plot. 

In certain conditions true interpolation of optical functions and
parameters inside the element is available through internal slicing of
the element and a call to the \hyperref[chap:twiss]{\texttt{TWISS}}
module for each slice. 

The basic plot attributes, such as line thickness, annotation size,
and PostScript format and interpolation can be set with the
\hyperref[sec:setplot]{\texttt{SETPLOT}} command and reset with the
\hyperref[sec:resplot]{\texttt{RESPLOT}} command.

Note also that for various reasons a sequence must be defined before the 
\texttt{PLOT} command can be invoked. 

\section{PLOT}	
\label{sec:plot}

\madbox{
xxxxxx\=xxxxxxxx\= \kill
PLOT, \>HAXIS=  \>string, HMIN=real, HMAX=real, \\ 
      \>VAXIS=  \>string\textit{1}, \ldots, string\textit{n}, \\
      \>VAXIS1= \>string\textit{1}, \ldots, string\textit{n}, \\ 
      \>VAXIS2= \>string\textit{1}, \ldots, string\textit{n}, \\ 
      \>VAXIS3= \>string\textit{1}, \ldots, string\textit{n}, \\
      \>VAXIS4= \>string\textit{1}, \ldots, string\textit{n}, \\
      \>VMIN=reals, VMAX=reals,  \\
      \>TITLE=string, \\
      \>BARS=integer, STYLE=integer, \\
      \>COLOUR=integer, SYMBOL=integer, \\
      \>INTERPOLATE=logical, ZERO\_SUPPR=logical, \\
      \>NOVERSION=logical, NOLINE=logical, NOTITLE=logical, \\
      \>MARKER\_PLOT=logical, RANGE\_PLOT=logical, RANGE=range, \\ 
      \>TABLE=tabname, PARTICLE=particle1,particle2,\ldots,particlen, \\
      \>MULTIPLE=logical, FILE=file\_name\_start, TRACKFILE=basename, \\
      \>PTC=logical, PTC\_TABLE=tabname; 
}

where the parameters have the following meaning: 
\begin{madlist}
   \ttitem{HAXIS} name of the horizontal variable 

   \ttitem{HMIN, HMAX} lower and upper edge for horizontal axis. Both
   values must be provided. 

   \ttitem{VAXIS} one or several variables from the table to be plotted
     against a single vertical axis. If more than 10 variables are
     specified, the plot is not produced.   

   \ttitem{VAXIS\textsl{i}} one or several variables from the table to be plotted
     against vertical axis number \textsl{i}. There is a maximum of 4
     vertical axes. \\
     If the number of variables given for a single vaxis\textsl{i} would
     push the total number of variables beyond the maximum of 10, the
     variables given for this vaxis\textsl{i}, as well as those for
     subsequent vaxes, are ignored but the plot is produced for the
     variables accumulated so far.  \\
     \textit{Important: VAXIS and VAXIS{1..4} are exclusive in their
       application! if VAXIS is given, VAXIS{1..4} will be simply ignored.} 

   \ttitem{VMIN, VMAX} lower and upper edge(s) for vertical axis or axes, up to
     four numbers separated by commas.\\
     Note that both vmin and vmax must be given for an axis to be effective.   

   \ttitem{TITLE} plot title string; if absent, the last overall title is
     used; if no such overall title as well, the sequence name is used.

   \ttitem{BARS} 0 (default) or 1 - with bars=1, all data points
     are connected to the horizontal axis with vertical bars.   

   \ttitem{STYLE} 1 (default), 2, 3, or 4: line style for connecting the
     successive data points, respectively solid, dashed, dotted, and dot-dashed; 
     the special value style=100 uses the four styles in turn for
     successive curves in the same plot. 
     With style=0 successive data points are not connected. 

   \ttitem{COLOUR} 1 (default), 2, 3, 4, or 5: colour for the symbols and lines, 
     respectively black, red, green, blue, and magenta; 
     The special value colour=100  uses the five colours in turn for
     successive symbols and lines.

   \ttitem{SYMBOL} 0 (default), 1, 2, 3, 4, or 5: The symbols to be
     plotted at data points, respectively none, dot ("."), plus ("+"),
     star ("*"), circle ("o"), and cross ("x").  
     The symbol size may have to be adapted through the SETPLOT command
     (see below). \\ 
     Note that if symbol and style are both zero, style is
     forced to its default value (style=1) otherwise the plot would be
     invisible. 

   \ttitem{INTERPOLATE} logical, default=false. The data points are
     normally connected by straight lines; if \texttt{INTERPOLATE} is
     specified, the following on-momentum Twiss parameters are
     interpolated with calls to the Twiss module inside 
     each element: beta, sqrt(beta), alfa, phase advance, orbit, angle,
     dispersion and its first derivative, for both planes. \\ 
     For all other variables splines are used to smooth
     the curves. \\ 
     \textbf{Note} that setting this option is ineffective if the
     \texttt{INTERPOLATE} option of the
     \hyperref[sec:setplot]{\texttt{SETPLOT}} command has been set to  
     true; in this case all plots will be interpolated. \\
     \textbf{Note} also that because the \texttt{INTERPOLATE} option
     causes \texttt{TWISS} to be called internally with a range, any
     range that might have been defined in a previous
     \hyperref[sec:use]{\texttt{USE}} command is lost. In this case the
     \texttt{USE} statement must be reiterated with the range, which in
     turn could cause assigned errors to be lost.  \\
     \textbf{Caution} the attribute \texttt{INTERPOLATE} actually replaces
     expressions stored into element attributes by their value. It is plan
     to correct the problem, but it is not yet fixed.

   \ttitem{ZERO\_SUPPR} To be documented (default = false)

   \ttitem{NOVERSION} logical, default=false. If \texttt{NOVERSION=true}, the
     information concerning the version of \madx and the date of the run
     are suppressed from the title.  
     This option frees additional space available for the user specified
     title of the plot.  

   \ttitem{NOLINE} logical, default=false. If \texttt{s} is the horizontal
     variable, then a symbolic representation of the beamline is plotted
     above the plot, except for tables that have been read back into \madx. 
     In case the horizontal scale is too large and the density of
     beamline elements is too high, this may result in hardly legible
     representation and a thick black block in the worst case. 
     The \texttt{NOLINE=true} option suppresses this symbolic representation 
     of the beamline. 

   \ttitem{NOTITLE} logical, default=false. If true, suppresses the title
     line, including the information on the version and date.  

   \ttitem{MARKER\_PLOT} logical, default=false. If true, plotting is done
     also at the location of marker elements. This is only useful for
     the plotting of non-continuous functions like the "N1" from the
     aperture module. Beware that the PS file might become very large if
     this flag is invoked.
  
   \ttitem{RANGE\_PLOT} logical, default=false. Allows the specification
     of a plotting range for the user defined horizontal axis.   

   \ttitem{RANGE} horizontal plot \hyperref[sec:range]{range} given by
   elements.   

   \ttitem{TABLE} name of the table from which data is plotted (default:
     twiss). \\ 
     If the first part of the name of the table is "track", the
     data to be plotted are taken from the tracking file(s) generated by
     a previous TRACK command for each requested particle as defined by
     the \textit{particle} attribute. If the required file has not been
     generated by a preceding TRACK command, no plot is done for that
     particle. \\  
     The plot is generated through the GNUPLOT program and is available
     in the format specified by the SETPLOT command. \\ 
     The preceding TRACK command should contain the attribute \textit{DUMP}
     and may contain the attribute \textit{ONETABLE}. The tracking plots
     are appended to the file file\_name.ps where file\_name can be
     specified via the attribute \textit{filename=file\_name}. Note that
     the plots are appended to this file and the file is not
     overwritten. \\
     The PLOT command uses the following tracking output files depending on
     the name of the table.\\  
     With the attribute \textit{table=trackone}, the data file is assumed
     to have been generated with the \textit{ONETABLE=true} attribute of
     the TRACK command, and the file name has the following format: 
     \textit{basisone} where the basis for the file name is defined by the
     attribute \textit{trackfile=basis} (default=track).\\
     With the attribute \textit{table=trackxxx} where xxx is any string
     other than "one", the data files are assumed to have been generated
     with the \textit{ONETABLE=false} attribute of the TRACK command, and
     the file names have the following format: \textit{basis.obs0001.p00i}
     where the basis for the file name is defined by the attribute
     \textit{trackfile=basis} (default=track), the observation point fixed
     is to 1 and the particle number \textit{i} is given by the attribute
     \textit{particle=i}.
 
   \ttitem{PARTICLE} one or several numbers associated to the tracked
     particles for which the specified plot has to be displayed.  

   \ttitem{MULTIPLE} logical, default=false. If true all the curves
     generated for each tracked particle are put on one plot. Otherwise
     there will be one plot for each particle.   

   \ttitem{FILE} basename for the Postscript
     file(s). Only the first occurrence of such a name will be
     used. Default is "madx" or "madx\_track" if the \textit{table}
     attribute is track.  Depending on the format (.ps or .eps, see
     below) the plots will either all be written into one file
     file\_name.ps, or one per plot into file\_name01.eps,
     file\_name02.eps, etc. \\
     \textbf{Note:} in the case of several \texttt{PLOT} commands in a
     single \madx job, the first \texttt{FILE} argument determines the
     basename and other \texttt{FILE} arguments in subsequent
     \texttt{PLOT} commands are ignored.  

   \ttitem{TRACKFILE} basename of the files containing
     tracking data for each particle (default: track)  

   \ttitem{PTC} logical, default=false. If set true, the data to be
     plotted are taken from the table defined by the attribute
     \textit{ptc\_table} which is expected to be generated previously by
     the ptc package. The data belong to the column identified by one of
     the names set in the definition of the ptc twiss
     table. Interpolation is not available and the attribute
     \textit{interpolate} has no effect. \\ 
     This option is recommended when plotting data
     obtained from \hyperref[chap:ptc-twiss]{\texttt{PTC\_TWISS}} since
     there is no mechanism for \texttt{PLOT} to physically interpolate
     the optical functions beyond using splines with no mechanism for
     constraints with derivatives. In most cases the
     \texttt{INTERPOLATE} option with data obtained with
     \texttt{PTC\_TWISS} produces unphysical data representation. 

   \ttitem{PTC\_TABLE} name of the ptc twiss table from which data is
     plotted (default: ptc\_twiss)

\end{madlist}

% Note on interpolation to be added :
% spline use only the data values and not the derivatives, eg in the
% case of orbit in a drift the orbit values are correctly taken into
% account account but the PX values, and in particular the fact that
% PX(END)=PX(START) is not taken as a constraint, This can lead to
% smooth curves that are pleasing to the eye but where the
% representation is wrong from a physics point of view. One way out of
% this is to slice elements with enough slices to constrain the spline
% mechanism. 


\section{SETPLOT}
\label{sec:setplot}
\madbox{
SETPLOT, \=POST= integer, FONT= integer, LWIDTH= real, \\
         \>XSIZE= real, YSIZE= real,\\
         \>ASCALE= real, LSCALE= real, SSCALE= real, RSCALE= real,\\
         \>INTERPOLATE= logical;
}

where the parameters have the following meaning: 
\begin{madlist}
   \ttitem{POST} default = 1. If =1, makes one PostScript file (.ps) with
     all plots; if =2, makes one Encapsulated PostSscript file (.eps)
     per plot.   

   \ttitem{FONT} there are two defaults: 1 for screen plotting: this uses
     characters made from polygons; -1 for PostScript files; this is
     Times-Italic. There are various fonts available for positive and
     negative integers, best to be tried out, since they will look
     different on different systems anyway. GhostView will show strange
     vertical axis annotations, but the printed versions are normally
     OK.   

   \ttitem{LWIDTH} default = 1. Allows the user to set the curve line
     width.  Depends on the system as well, so to be tried out.   

   \ttitem{XSIZE} bounding box size for PostScript, default=27 cm.   
   \ttitem{YSIZE} bounding box size for PostScript, default=19 cm.   
   \ttitem{ASCALE} annotation character height scale factor, default=1.   
   \ttitem{LSCALE} axis label character height scale factor, default=1.  
   \ttitem{SSCALE} curve symbol (see above) scale factor, default=1.  
   \ttitem{RSCALE} axis text character height scale factor, default=1.  

   \ttitem{INTERPOLATE} (default=false) The data points are
     normally connected by straight lines; if \texttt{INTERPOLATE} is
     specified, the following on-momentum Twiss parameters are
     interpolated with calls to the Twiss module inside 
     each element:  beta, sqrt(beta), alfa, phase advance, orbit, angle,
     dispersion and its first derivative, for both planes. \\ 
     For all other variables splines are used to smooth the curves. \\  
     Note that if \texttt{INTERPOLATE=true}, all subsequent \texttt{PLOT} 
     commands use interpolation, irrespective of the setting of their 
     \texttt{INTERPOLATE} attribute; \\
     If \texttt{INTERPOLATE=false} (default), all subsequent \texttt{PLOT} 
     commands respect the setting of their \texttt{INTERPOLATE} attribute.
\end{madlist}


\section{RESPLOT}
\label{sec:resplot}
\madbox{
RESPLOT;
}
resets all defaults for the \hyperref[sec:setplot]{\texttt{SETPLOT}} command.  


\section{First example for plots of tracking data}
\label{sec:plot_example_1}

The following \madx code sample defines the tracking of four particles 
with the generation of a single file with name \textit{basisone} 
holding the tracking data for all four particles.  

\madhline
\begin{verbatim}
// track particles
track, file=basis, dump, onetable;
 start, x= 2e-3, px=0, y= 2e-3, py=0;
 start, x= 4e-3, px=0, y= 4e-3, py=0;
 start, x= 6e-3, px=0, y= 6e-3, py=0;
 start, x= 8e-3, px=0, y= 8e-3, py=0;
 run,turns=1024;
endtrack;
\end{verbatim}
\madhline

The following sample code defines the plotting of the x-px and y-py
phase space coordinates for all four particles. 
It takes into account the fact that all coordinates are in a single file 
with \textit{table=trackone} and defines the filename where tracking data 
is to be found (\textit{basisone}) with \textit{trackfile=basis}. 

\madhline
\begin{verbatim}
// plot trajectories
setplot, post=1; 
title, "FODO phase-space test";
plot, file=plot, table=trackone, trackfile=basis, noversion, multiple, 
      haxis=x, vaxis=px, particle=1,2,3,4; 
plot, file=plot, table=trackone, trackfile=basis, noversion, multiple, 
      haxis=y, vaxis=py, particle=1,2,3,4;
\end{verbatim}
\madhline

With each plot command a temporary file \textit{gnu\_plot.gp} containing
GNUPLOT instructions is generated.  
The file generated by the first plot command reads: 

\madhline
{\footnotesize \begin{verbatim}  
set terminal postscript color
set pointsize 0.48
set output 'tmpplot.ps'
set title "FODO phase-space test"
set xlabel 'x'
set ylabel 'px'
plot 'basisone' using 3:($1==1 ? $4 : NaN) title 'particle 1' with points pointtype 1 , \
     'basisone' using 3:($1==2 ? $4 : NaN) title 'particle 2' with points pointtype 2 , \
     'basisone' using 3:($1==3 ? $4 : NaN) title 'particle 3' with points pointtype 3 , \
     'basisone' using 3:($1==4 ? $4 : NaN) title 'particle 4' with points pointtype 4 
\end{verbatim}}
\madhline
  
\madx then calls GNUPLOT as a subprocess to execute this file, which
generates the file \textit{tmpplot.ps}.  
The file \textit{tmpplot.ps} is then \textbf{appended} to the file 
{\textit plot.ps} determined by the attribute \textit{file=plot}.  
The files \textit{gnu\_plot.gp} and \textit{tmpplot.ps} are then
discarded. 

The same process is repeated for the second plot command, resulting in a
growing file \textit{plot.ps}.


\section{Second example for plots of tracking data}
\label{sec:plot_example_2}

The following \madx code sample defines the tracking of four particles 
with the generation of individual files with name
\textit{basis.obs0001.p000i} with \textit{i=1..4}  
holding the tracking data for each of the four particles.  

\madhline
\begin{verbatim}
// track particles
track, file=basis, dump;
 start, x= 2e-3, px=0, y= 2e-3, py=0;
 start, x= 4e-3, px=0, y= 4e-3, py=0;
 start, x= 6e-3, px=0, y= 6e-3, py=0;
 start, x= 8e-3, px=0, y= 8e-3, py=0;
 run,turns=1024;
endtrack;
\end{verbatim}
\madhline

The following sample code defines the plotting of the x-px and y-py
phase space coordinates for all four particles with the data of all four
particles on a single plot.  
It takes into account the fact that coordinates for all four particles
are in separate files with 
\textit{table={\underline track}fodo} and defines the filename where tracking
data is to be found (\textit{basis.obs0001.p000i}) with
\textit{trackfile=basis}.  

\madhline
\begin{verbatim}
// plot trajectories
setplot, post=1; 
title, "FODO phase-space test";
plot, file=plot, table=trackfodo, trackfile=basis, noversion, multiple, 
      haxis=x, vaxis=px, particle=1,2,3,4; 
plot, file=plot, table=trackfodo, trackfile=basis, noversion, multiple, 
      haxis=y, vaxis=py, particle=1,2,3,4;  
\end{verbatim}
\madhline

With each plot command a temporary file gnu\_plot.gp containing GNUPLOT instruction is generated. 
The file generated by the first plot command reads: 

{\footnotesize
\madhline
\begin{verbatim}
set terminal postscript color
set pointsize 0.48
set output 'tmpplot.ps'
set title "FODO phase-space test"
set xlabel 'x'
set ylabel 'px'
plot 'basis.obs0001.p0001' using 3:4 title 'particle 1' with points pointtype 1 , \
     'basis.obs0001.p0002' using 3:4 title 'particle 2' with points pointtype 2 , \
     'basis.obs0001.p0003' using 3:4 title 'particle 3' with points pointtype 3 , \
     'basis.obs0001.p0004' using 5:4 title 'particle 4' with points pointtype 4 
\end{verbatim}
\madhline
}

\madx then calls GNUPLOT as a subprocess to execute this file, which
generates the file \textit{tmpplot.ps}.  
The file \textit{tmpplot.ps} is then \textbf{appended} to the file
\textit{plot.ps} determined by the attribute \textit{file=plot}.  
The files \textit{gnu\_plot.gp} and \textit{tmpplot.ps} are then
discarded. 

The same process is repeated for the second plot command, resulting in a
growing file \textit{plot.ps}.


%\href{http://www.cern.ch/Hans.Grote/hansg_sign.html}{hansg}, June 17, 2002, 
%rdemaria \href{http://cern.ch/rdemaria}{rdemaria}, September 2007.