xgrafix.tex

xgrafix 是PTSG模拟程序中的图形截面库 改版本是最新版本

\documentstyle[12pt]{article}
\pagestyle{plain}
\topmargin -0.60in
\oddsidemargin 0.0625in
\textheight 9.00in
\textwidth 6.50in
\renewcommand{\baselinestretch}{1.4}
\parskip 0.10in

\begin{document}

\begin{center}
\Large
{\bf XGrafix library} \\
Version 2.0
\\
\large
V. Vahedi, P. Mirrashidi, D. K. Wong, and J. P. Verboncoeur \\
{\em University of California, Berkeley}
\end{center}

\normalsize
XGrafix is a windowing environment for interactive display of
results from any temporally evolving simulation of a physical
system.  XGrafix is distributed in library format by the University
of California Office of Technology Licensing, Berkeley California.
The source codes to the libraries are also distributed separately
by the Office of Technology Licensing.  The README file with the
source code describes how to compile the XGrafix library using
the distributed makefile.  Before running make, the flags and
variables in the makefile must be defined. After compiling XGrafix,
the makefile builds libraries which can be left in the XGrafix
directory or installed in {\bf /usr/lib}.  Two header files are
included in the distribution, only one of which is to be included
in the physics modules.  The file xgrafix.h contains function prototypes
and variable definitions that may be needed.  The other header file, 
xgrafixint.h, is used only to compile XGrafix and is not needed by 
the physics modules.

Another directory called {\bf ctest} is also
distributed with the XGrafix library to demonstrate how to use
XGrafix with C compilers. We will
describe the usage of XGrafix using the example in the {\bf ctest}
directory.

Another directory called {\bf ftest} is also distributed to
demonstrate how to use XGrafix with Fortran compilers. 
The usage of XGrafix with Fortran compilers is very similar
to its usage with C compilers. First follow the
explanation of the example given in {\bf ctest} before
trying the example in {\bf ftest}. When compiling Fortran programs with
the XGrafix libraries you will need the file {\bf extra.c} provided in {\bf ftest}.
Also, Depending on your system additional Fortran compilation flags and Fortran
libraries may be needed. This is because the implementation of the Fortran 
procedure $getarg()$ is system-dependent. For example, Sun machines will require
the library libF77.a while HP machines will require the compilation flag +U77 and
the library libU77.a. For more information, do a ``man getarg'' on your system. 

The XGrafix function calls in Fortran are nearly identical to those in C, 
except the functions are all in lowercase. For each C Xgrafix function,
there is a corresponding Fortran function which takes virtually identical
parameters. There are a few exceptions to this rule:

\begin{enumerate}
\item Unlike the C Function $XGInit()$, the Fortran function $xginit()$ 
has only one parameter: the time.

\item A Fortran equivalent is provided for $XGStructureArray()$ but not for
$XGStructure()$ because $XGStructureArray()$
does the same thing as $XGStructure()$ but with parameters which
are more compatible with Fortran. Also, in the Fortran version of
$XGStructureArray()$, the  parameters FILLED, HOLLOW are replaced
by the integers 0,1 respectively.

\item Fortran equivalents are provided for $XGCurve()$, $XGVector()$, $XGSurf()$ and \\ 
$XGIRSurf()$ but not for $XGCurveVector()$, $XGVectorVector()$,
$XGSurfVector()$ and $XGIRSurfVector()$. This is because the latter set of functions 
are used only when plotting 
data structures specific to C and not relevant to Fortran.

\item The Fortran functions $xgvector()$, $xgsurf()$, $xgirsurf()$ 
and $xgcont()$ are nearly identical to their C counterparts except that they 
take on two additional parameters: The dimensions of the 2D array they are 
passing. These should be inserted right before the "color" parameter.  

\item Instead of using the C function $SetupNewVar()$ to set up variables which can be 
changed dynamically by XGrafix, use the functions $setupnewint(integer, string)$, \\
$setupnewreal(real, string)$, $setupnewdouble(double precision, string)$, and \\
$setupnewchar(character, string)$. In each case,
``string'' is the label XGrafix will associate with the dynamic variable. 
Like $SetupNewVar()$, these functions must be called before $XGStart()$.
\end{enumerate}
For more information on the Fortran Xgrafix functions, read the comments in the file \\
{\bf xgfinterface.f} in the {\bf src} directory.
For usage of these functions, see the file {\bf test.f} in the {\bf ftest} directory.

XGrafix allows the application to initialize plotting windows for
displaying data.  All the arrays to be plotted must remain defined for
the duration of the simulation run.  XGrafix is initialized by calling
the {\em XGInit} () function before any plots can be set up.  In the
test example, the call to {\em XGinit} () appears in the function {\em
InitWindows} () which precedes the main event loop.  Definitions of
{\em XGInit} () and other XGrafix functions will appear at the end of
this document.  After XGrafix is initialized, subsequent calls to {\em
XGSet2D} (), {\em XGSet2DC} (), {\em XGSetVec} (), and {\em XGSet3D}
() initialize the appropriate plotting windows.  In the sample, these
functions are called in the {\em InitWindows} () function.  After a 2D
plotting window is initialized with a call to {\em XGSet2D} () the
application can request multiple graphs in the plotting window by
successive calls to {\em XGCurve} (), {\em XGCurveVector} () and/or {\em
XGScat2D} ().  This version of
XGrafix supports only one graph in any 3D plotting window set up by
{\em XGSet3D} ().

\newpage
Simulations of physical systems which evolve in time, typically have
a time loop in which various physics module are called and the
time step and various data arrays are updated.  XGrafix automatically handles
this loop and updates the physics and graphics.  An {\em XGMainLoop} () 
procedure needs to be supplied, which would update variables as needed for 
each iteration.  A call to {\em XGStart} () after all the initializations
are done will enter this loop and take over.
The functions listed below are XGrafix routines to
initialize the environments and set up windows for diagnostics.

\def\xlen{4in}
\begin{minipage}{\xlen}
\begin{flushright}
\rule{\xlen}{.5pt}
\end{flushright}
\end{minipage}

\begin{flushleft}
{\em XGInit} ($argc$, $argv$, $t$) \\
int $argc$; /* Number of arguments passed to the $main$ () */\\
char *$argv$ [ ]; /* Array of char pointers to list of input parameters on command line */ \\
double *$t$;  /* a pointer to the time variable */
\end{flushleft}
This function must be called to initialize XGrafix before any other XGrafix routine is
called.  The parameters $argv$ and $argc$ are the standard parameters passed to
$main$ () at the command line.  The pointer to the time variable $t$ is 
used by XGrafix to display the simulation time.  XGrafix uses argv[0] to 
obtain the name of the executable program.  XGrafix also allows for several command line options.  The $-h$ option will output a list of other supported options:

\begin{tabbing}
\verb+    +\=$-d$ $dumpfile[.dmp]$: \verb+ +\=Specify dump file name. Default is output.dmp \\
\>$-dp$ $n$:\>Dump every $n$ steps. Default is 0 (no periodic dumps) \\
\>$-h$:\>This help message \\
\>$-i$ $inputfile[.inp]$:\>Specify input file name. Default is no input file \\
\>$-nox$:\>Run without X \\
\>$-p$ $psfile[.ps]$:\>Specify ps file name. Default is output.ps \\
\>$-s$ $n$:\>Run for $n$ steps. Default is 0 (run forever) \\
\>$-u$ $n$:\>Run $n$ XGMainLoops every graphics update.  Default is 1. \\
\end{tabbing}

\newpage
After the call to XGInit, several variables will be available to the physics 
module.  These are:

\begin{tabbing}
\verb+    +\=int\verb+    +\=$theRunWithXFlag$\verb+    +\=FALSE if $-nox$ is given, TRUE otherwise \\
\>int\>$theNumberOfSteps$\>The number of steps simulation will run, 0 if forever \\
\>int\>$theCurrentStep$\>The current step in the simulation \\
\>int\>$theDumpPeriod$\>The number of steps between automatic dumps \\
\>int\>$WasDumpFileGiven$\>TRUE if $-d$ option is given, FALSE otherwise \\
\>int\>$WasInputFileGiven$\>TRUE if $-i$ option is given, FALSE otherwise \\
\>char *\>$theCodeName$\>The name of the physics executable, same as argv[0] \\
\>char *\>$theInputFile$\>The name of the input file \\
\>char *\>$theDumpFile$\>The name of the dump file \\
\>char *\>$theEPSFile$\>The name of the encapsulated postscript file
\end{tabbing}

\def\xlen{4in}
\begin{minipage}{\xlen}
\begin{flushright}
\rule{\xlen}{.5pt}
\end{flushright}
\end{minipage}

\begin{flushleft}
$XGSet2D$($PlotType$, $X\_Label$, $Y\_Label$, $State: Exp $, $ulx$, $uly$, $X\_Scale$, $Y\_Scale$, \\
\hspace{.8in} $X\_Auto\_Rescale$, $Y\_Auto\_Rescale$, $X\_Min$, $X\_Max$, $Y\_Min$, $Y\_Max$) \\
char  *$PlotType$;         /* ``linlin'', ``linlog'', ``loglog'', or ``loglin'' */ \\
char  *$X\_Label$;         /* x label for the frame                            */ \\
char  *$Y\_Label$;         /* y label for the frame                            */ \\
char  *$State: Exp $;            /* ``open'' or ``closed''                           */ \\
int    $ulx$, $uly$;       /* requested position of frame's upper left corner   */ \\
SCALAR  $X\_Scale$;         /* scaling factor for the x array                   */ \\
SCALAR  $Y\_Scale$;         /* scaling factor for the y array                   */ \\
int    $X\_Auto\_Rescale$; /* if True $X\_Min$ and $X\_Max$ are ignored       */ \\
int    $Y\_Auto\_Rescale$; /* if True $Y\_Min$ and $Y\_Max$ are ignored       */ \\
SCALAR  $X\_Min$, $X\_Max$; /* x bounds for the plot if $X\_Auto\_Rescale$ is False  */ \\
SCALAR  $Y\_Min$, $Y\_Max$; /* y bounds for the plot if $Y\_Auto\_Rescale$ is False  */ 
\end{flushleft}

{\em XGSet2D} () initializes a plotting frame for a 2D plot.  The plot type is passed 
as a character string and can be one of the four strings defined in the comments.  If
$PlotType$ is defined as ``linlog,'' the $x$ axis will have a linear scale, and the $y$
axis will have a logarithmic scale.  Note that when the $x$ and/or $y$ axes are set to have
a logarithmic scale, XGrafix WILL take the logarithm of the data along that axis.
The name of the X-Windows frame, which appears as a window on the display will be
the same $Y\_Label$.  The $State: Exp $ parameter (``open'' or ``closed'') defines the
initial state of the window; if ``closed,''
the window will initially be hidden.  If the flag $X\_Auto\_Rescale$ is
set to zero (False), XGrafix uses $X\_Min$ and $X\_Max$ as the plot limits on the $x$
axis in the plotting window.  If $X\_Auto\_Rescale$ is not False, set to 1, XGrafix will
scan the whole $x$ data array to find the maximum and the minimum of each plot.  The 
same is true for the parameters pertaining to $y$ axis.  Note that, {\em XGSet2D} ()
only sets up a 2D frame, and does not have any information about the data arrays which
are to be plotted in this frame.  A call to {\em XGSet2D} () must be followed by at
least one call to $XGCurve$ (), $XGCurveVector$ () or $XGScat2D$ () .  Multiple calls to $XGCurve$ (), $XGCurveVector$ ()  
and/or $XGScat2D$ () result in multiple graphs in that plotting frame. The integers
$ulx$ and $uly$ define the initial position of frame's upper left corner.  The default
size of a 2D frame is 300 by 400 pixels which can be resized at run time.

\begin{flushleft}
$XGCurve$($x\_array$, $y\_array$, $npoints$, $color$) \\
SCALAR   *$x\_array$;    /* x array to be plotted                         */ \\
SCALAR   *$y\_array$;    /* y array to be plotted                         */ \\
int     *$npoints$;    /* number of points in the x (and y) direction    */ \\
int      $color$;      /* plot color chosen from 0-9                   */
\end{flushleft}

\begin{flushleft}