File: UsersGuide.html

package info (click to toggle)
grace6 5.99.1%2Bdev4-3
links: PTS
area: main
in suites: etch, etch-m68k
size: 10,492 kB
ctags: 13,269
sloc: ansic: 103,384; sh: 5,021; yacc: 617; makefile: 574; lex: 253; fortran: 56
file content (2457 lines) | stat: -rw-r--r-- 106,430 bytes
parent folder | download | duplicates (2)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.21">
 <TITLE>Grace User's Guide (for Grace-5.99.1)</TITLE>
</HEAD>
<BODY>
<H1>Grace User's Guide (for Grace-5.99.1)</H1>

<H2>The Grace Team</H2>06.05.2006
<HR>
<EM>    This document explains the usage of
    <B>Grace</B>, a WYSIWYG 2D plotting tool for numerical data.
  </EM>
<HR>
<P>
<H2><A NAME="toc1">1.</A> <A HREF="UsersGuide.html#s1">Introduction</A></H2>

<UL>
<LI><A NAME="toc1.1">1.1</A> <A HREF="UsersGuide.html#ss1.1">What is Grace?</A>
<LI><A NAME="toc1.2">1.2</A> <A HREF="UsersGuide.html#ss1.2">Copyright statement</A>
</UL>
<P>
<H2><A NAME="toc2">2.</A> <A HREF="UsersGuide.html#s2">Installation guide</A></H2>

<UL>
<LI><A NAME="toc2.1">2.1</A> <A HREF="UsersGuide.html#ss2.1">Installing from sources</A>
<LI><A NAME="toc2.2">2.2</A> <A HREF="UsersGuide.html#ss2.2">Binary installation</A>
</UL>
<P>
<H2><A NAME="toc3">3.</A> <A HREF="UsersGuide.html#s3">Getting started</A></H2>

<UL>
<LI><A NAME="toc3.1">3.1</A> <A HREF="UsersGuide.html#ss3.1">General concepts</A>
<LI><A NAME="toc3.2">3.2</A> <A HREF="UsersGuide.html#ss3.2">Invocation</A>
<LI><A NAME="toc3.3">3.3</A> <A HREF="UsersGuide.html#ss3.3">Customization</A>
</UL>
<P>
<H2><A NAME="toc4">4.</A> <A HREF="UsersGuide.html#s4">Guide to the graphical user interface</A></H2>

<UL>
<LI><A NAME="toc4.1">4.1</A> <A HREF="UsersGuide.html#ss4.1">GUI controls</A>
<LI><A NAME="toc4.2">4.2</A> <A HREF="UsersGuide.html#ss4.2">The main window</A>
<LI><A NAME="toc4.3">4.3</A> <A HREF="UsersGuide.html#ss4.3"> File menu </A>
<LI><A NAME="toc4.4">4.4</A> <A HREF="UsersGuide.html#ss4.4"> Edit menu </A>
<LI><A NAME="toc4.5">4.5</A> <A HREF="UsersGuide.html#ss4.5"> Data menu </A>
<LI><A NAME="toc4.6">4.6</A> <A HREF="UsersGuide.html#ss4.6">View menu</A>
<LI><A NAME="toc4.7">4.7</A> <A HREF="UsersGuide.html#ss4.7">Tools menu</A>
<LI><A NAME="toc4.8">4.8</A> <A HREF="UsersGuide.html#ss4.8">Help menu</A>
</UL>
<P>
<H2><A NAME="toc5">5.</A> <A HREF="UsersGuide.html#s5">Command interpreter </A></H2>

<UL>
<LI><A NAME="toc5.1">5.1</A> <A HREF="UsersGuide.html#ss5.1">General notes</A>
<LI><A NAME="toc5.2">5.2</A> <A HREF="UsersGuide.html#ss5.2">Definitions</A>
<LI><A NAME="toc5.3">5.3</A> <A HREF="UsersGuide.html#ss5.3">Variables</A>
<LI><A NAME="toc5.4">5.4</A> <A HREF="UsersGuide.html#ss5.4">Numerical operators and functions</A>
</UL>
<P>
<H2><A NAME="toc6">6.</A> <A HREF="UsersGuide.html#s6">Advanced topics</A></H2>

<UL>
<LI><A NAME="toc6.1">6.1</A> <A HREF="UsersGuide.html#ss6.1">Fonts</A>
<LI><A NAME="toc6.2">6.2</A> <A HREF="UsersGuide.html#ss6.2">Interaction with other applications</A>
<LI><A NAME="toc6.3">6.3</A> <A HREF="UsersGuide.html#ss6.3">FFTW tuning</A>
<LI><A NAME="toc6.4">6.4</A> <A HREF="UsersGuide.html#ss6.4">DL modules </A>
</UL>
<P>
<H2><A NAME="toc7">7.</A> <A HREF="UsersGuide.html#s7"> References</A></H2>

<UL>
<LI><A NAME="toc7.1">7.1</A> <A HREF="UsersGuide.html#ss7.1">Typesetting</A>
<LI><A NAME="toc7.2">7.2</A> <A HREF="UsersGuide.html#ss7.2">Device-specific limitations</A>
<LI><A NAME="toc7.3">7.3</A> <A HREF="UsersGuide.html#ss7.3">Device-specific settings</A>
<LI><A NAME="toc7.4">7.4</A> <A HREF="UsersGuide.html#ss7.4">Dates in Grace </A>
<LI><A NAME="toc7.5">7.5</A> <A HREF="UsersGuide.html#ss7.5">Xmgr to Grace migration guide</A>
</UL>

<HR>
<H2><A NAME="s1">1.</A> <A HREF="#toc1">Introduction</A></H2>

<H2><A NAME="ss1.1">1.1</A> <A HREF="#toc1.1">What is Grace?</A>
</H2>

<P>Grace is a WYSIWYG tool to make two-dimensional plots of scientific
data. It runs under various (if not all) flavors of Unix with X11
and M*tif (LessTif or Motif). It also runs under VMS, OS/2, and
Windows (95/98/NT/XP). Its capabilities are roughly similar to
GUI-based programs like Sigmaplot or Microcal Origin plus
script-based tools like Gnuplot or Genplot. Its strength lies in the
fact that it combines the convenience of a graphical user interface
with the power of a scripting language which enables it to do
sophisticated calculations or perform automated tasks.</P>
<P>Grace is derived from Xmgr (a.k.a. ACE/gr), originally written by
Paul Turner.</P>
<P>From version number 4.00, the development was taken over by a
team of volunteers under the coordination of Evgeny Stambulchik.
You can get the newest information about Grace and download the
latest version at the 
<A HREF="http://plasma-gate.weizmann.ac.il/Grace/">Grace home page</A>.</P>
<P>When its copyright was changed to GPL, the name was changed to Grace,
which stands for ``GRaphing, Advanced Computation and Exploration of
data'' or ``Grace Revamps ACE/gr''. The first version of Grace available
is named 5.0.0, while the last public version of Xmgr has the version
number 4.1.2. Paul still maintains and develops a non-public version of
Xmgr for internal use.</P>
<P>As of now, most of the Grace codebase has been re-written from scratch.</P>
<H2><A NAME="ss1.2">1.2</A> <A HREF="#toc1.2">Copyright statement</A>
</H2>


<P>
<BLOCKQUOTE><CODE>
<PRE>
Copyright (&copy;) 1996-2006 Grace Development Team
Portions Copyright (&copy;) 1991-1995 Paul J Turner, Portland, OR

Maintained by Evgeny Stambulchik


                         All Rights Reserved

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>For certain libraries required to build Grace
(which are therefore even included in a suitable version)
there may be different Copyright/License statements. Though their
License may by chance match the one used for Grace,
the Grace Copyright holders can not influence or change them.</P>
<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Package </TD><TD> License </TD></TR><TR><TD>
T1lib </TD><TD> LGPL </TD></TR><TR><TD>
Expat </TD><TD> MIT/X </TD></TR><TR><TD>
Xbae widget </TD><TD> BSD-like </TD></TR><TR><TD>
Tab widget </TD><TD> BSD-like </TD></TR><TR><TD>
ListTree widget </TD><TD> LGPL </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>       Third-party license terms
     </CAPTION>
</CENTER><BR>
</P>
<H2><A NAME="s2">2.</A> <A HREF="#toc2">Installation guide</A></H2>

<H2><A NAME="ss2.1">2.1</A> <A HREF="#toc2.1">Installing from sources</A>
</H2>

<P>
<OL>
<LI> Configuration 
<A NAME="configuration"></A> 
<UL>
<LI> Requirements.
Grace usually compiles out of the box in a regular Unix-like
environment. You need an ANSI C compiler (gcc is just fine),
the X11R5 or above libraries and headers, and an
implementaion of the M*tif API, version 1.2 or above (2.1 is
highly recommended).
If you want to compile your own changes to certain parts of
Grace, you will need a parser generator (<CODE>yacc</CODE> or,
better, <CODE>bison</CODE>).</LI>
<LI> Extra libraries. Some features will be available only if
additional libraries are installed. Those are:
<UL>
<LI> Multi-level undo functionality is based on the libundo
library, version 0.8.0.</LI>
<LI> All raster backends (PNG, JPEG, ...) are based on the
(
<A HREF="http://www.gnu.org/software/libxmi/libxmi.html">Xmi library</A>),
version 1.2.</LI>
<LI> The JPEG backend needs the IJG's
(
<A HREF="ftp://ftp.uu.net/graphics/jpeg/">JPEG library</A>),
version 6.x.</LI>
<LI> The PNG backend needs the 
<A HREF="http://www.libpng.org/pub/png/libpng.html">libpng</A>
library (version 0.96 or above).</LI>
<LI> The PDF driver requires the PDFlib library to be
installed, which is available
<A HREF="http://www.pdflib.com/">here</A>, version
6.0.0 or above.</LI>
<LI> If your computer has the FFTW library (see the
<A HREF="http://www.fftw.org">FFTW Home page</A>)
installed when Grace is compiled, Grace will link itself
to this, and drop all conventional FFT's and DFT's. All
Fourier transforms will be routed through this package,
resulting in higher accuracy and better (much better
in many cases) performance. You'll need version 2.1.*,
since the FFTW-3 API is not supported as of yet.</LI>
<LI> In order to read/write sets in the NetCDF data format, you
will also need the 
<A HREF="http://unidata.ucar.edu/packages/netcdf/index.html">NetCDF libraries</A>.</LI>
</UL>
</LI>
<LI> Decide whether you want to compile in a separate place (thus
leaving the source tree pristine). You most probably would
want it if compiling Grace for more than one OS and keeping
the sources in a central shared (e.g. via NFS) location.
If you don't need it, skip the rest of this paragraph and go
right to the next step. Otherwise, assuming the sources are
in <CODE>/usr/local/src/grace-x.y.z</CODE> and the compilation
will be performed in <CODE>/tmp/grace-obj</CODE>, do the following:
<PRE>
  % mkdir /tmp/grace-obj
  % cd /tmp/grace-obj
  % /usr/local/src/grace-x.y.z/ac-tools/shtool mkshadow \
    /usr/local/src/grace-x.y.z .
                 
</PRE>
</LI>
<LI> The <CODE>configure</CODE> shell script attempts to guess correct
values for various system-dependent variables used during
compilation. It uses those values to create <CODE>Make.conf</CODE> in the
top directory of the package. It also create <CODE>config.h</CODE> file
containing system-dependent definitions. Finally, it creates a shell
script <CODE>config.status</CODE> that you can run in the future to
recreate the current configuration, a file <CODE>config.cache</CODE> that
saves the results of its tests to speed up reconfiguring, and a file
<CODE>config.log</CODE> containing compiler output (useful mainly for
debugging <CODE>configure</CODE>). If at some point <CODE>config.cache</CODE>
contains results you don't want to keep, you may remove or edit it.</LI>
<LI> Run <CODE>./configure --help</CODE>
to get list of additional switches specific to Grace</LI>
<LI> Run <CODE>./configure &lt;options&gt;</CODE>. Just an example:
<PRE>
  % ./configure --enable-grace-home=/opt/grace 
    --with-extra-incpath=/usr/local/include:/opt/include \
    --with-extra-ldpath=/usr/local/lib:/opt/lib --prefix=/usr
                 
</PRE>

would use <CODE>/usr/local/include</CODE> and
<CODE>/opt/include</CODE> in addition to the default include path
and <CODE>/usr/local/lib</CODE> and <CODE>/opt/lib</CODE> in addition
to the default ld path. As well, all stuff would be put under
the /opt/grace directory and soft links made to
<CODE>/usr/bin</CODE>, <CODE>/usr/lib</CODE> and <CODE>/usr/include</CODE>.</LI>
</UL>
</LI>
<LI> Compilation
<UL>
<LI> Issue <CODE>make</CODE>
If something goes wrong, try to see if the problem has been
described already in the <B>Grace FAQ</B> (in the <CODE>doc</CODE>
directory).</LI>
</UL>
</LI>
<LI> Testing
    
<UL>
<LI> <CODE>make tests</CODE>
This will give you a slide show demonstrating some nice
features of Grace.</LI>
</UL>
</LI>
<LI> Installation
<UL>
<LI> <CODE>make install</CODE></LI>
<LI> <CODE>make links</CODE>
The later (optional) step will make soft links from some files
under the Grace home directory to the system-wide default
locations (can be changed by the <CODE>--prefix</CODE> option
during the configuration, see above).</LI>
</UL>
</LI>
</OL>
</P>
<H2><A NAME="ss2.2">2.2</A> <A HREF="#toc2.2">Binary installation</A>
</H2>

<P>We neither provide nor support binary builds. Please contact your
vendor. Practically all general-purpose GNU/Linux and other Open Source
distributions have a Grace package in either main or contributed
sections.</P>
<H2><A NAME="s3">3.</A> <A HREF="#toc3">Getting started</A></H2>

<P>For a jump-in start, you can browse the demos ("Help/Examples" menu tree).
These are ordinary Grace projects, so you can play with them and modify
them.</P>
<P>O.k. Here's a VERY quick introduction:
<OL>
<LI> Start the GUI version: xmgrace (return).</LI>
<LI> Load your data with Data/Import/ASCII. 'Load as': 'Single set' for
two-column ASCII data, 'Block data' for multi-column ASCII data.</LI>
<LI> Fire up project explorer (Edit/Explorer).</LI>
<LI> Click on the top-level node of the project tree and select/check
the page size.</LI>
<LI> Adjust the scales, axis labels and tick marks in "Axis" quark
properties.</LI>
<LI> Adjust lines, symbols, legends in "Set" properties.</LI>
<LI> Continue exploring the quark tree for finer tuning.</LI>
<LI> Data can be manipulated in Data/Transformations. To shift a
data set by 20 to the left, e.g., in 'Evaluate Expression'
select the same set on the left and the right, and say Formula:
y = y - 20.
As you'll probably notice, Grace can do MUCH more than that.
Explore at your leisure.</LI>
<LI> When you like your plot, select 'File/Save'.</LI>
<LI> Select 'File/Print setup' and then 'File/Print' to get a hardcopy.
That's it!</LI>
</OL>
</P>
<H2><A NAME="ss3.1">3.1</A> <A HREF="#toc3.1">General concepts</A>
</H2>

<H3><A NAME="project-tree"></A> Project tree</H3>

<P>A plot in Grace is built in a tree-like manner (reflected
1:1 in the Explorer tool) out of "Quarks". Quark is an object that
may have its own presentation properties plus a number of children
quarks.</P>
<H3><A NAME="coordinates"></A> Coordinate frames </H3>

<P>Some quarks impose a coordinate transform; these are "Project",
"Frame", and "Graph". Correspondly, there are three types of
coordinates in Grace: the <B>viewport</B>, the <B>frame</B>, and
the <B>world coordinates</B>. A child position is <I>always</I>
defined in the coordinate frame of its parent, so e.g.   points of
data sets are defined in the graph's world coordinates.</P>
<P>The frame
coordinates go from 0 to 1 in both X and Y dimensions of a Frame. </P>
<P>The viewport coordinates correspond to the image of the plot drawn on
the canvas (or printed on, say, PS output page).
Actually, there is yet another level in the hierarchy of coordinates
- the <B>device coordinates</B>. However, you (as a user of Grace)
should not worry about the latter. The mapping between the viewport
coordinates and the device coordinates is always set in such a way
that the origin of the viewport corresponds to the left bottom corner
of the device page, the smallest of the device dimensions corresponds
to one unit in the viewport coordinates. Oh, and the most important
thing about the viewport -&gt; device transformation is that it is
homotetic, i.e. a square is guaranteed to remain a square, not a
rectangle, a circle remains a circle (not an ellipse) etc.</P>
<P>The transformation converting the world coordinates into the frame
and further into the viewport ones is determined by both the graph
type and the axis scaling.</P>

<H3><A NAME="frame"></A> Frames</H3>

<P>Frame is a rectangular placeholder for one or more graphs (if there
are more than one graph in a frame, such graphs are called
<B>overlaid</B>), and optional annotating objects (texts, boxes,
etc). As well, Frame is responsible for displaying legend box holding
legend entries for all of its children graphs.</P>
<H3><A NAME="graph"></A> Graphs</H3>

<P>A graph may hold (every element is optional) Axes, Sets, and
additional annotative objects.</P>
<P>The graph type can be any of:
<A NAME="graph-types"></A> 
<UL>
<LI> XY Graph </LI>
<LI> XY Chart </LI>
<LI> Polar Graph </LI>
<LI> Fixed Graph </LI>
<LI> Pie chart </LI>
</UL>
</P>
<H3><A NAME="sets"></A> Sets</H3>

<P>A set is a way of representing datasets. It consists
of a pointer to a dataset plus a collection of parameters describing
the visual appearance of the data (like color, line dash pattern etc).</P>
<P>The set type can be any of the following:</P>
<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Set type </TD><TD> # of num. cols </TD><TD> Description </TD></TR><TR><TD>
XY </TD><TD> 2 </TD><TD> An X-Y scatter and/or line plot, plus (optionally) an annotated value </TD></TR><TR><TD>
XYDX </TD><TD> 3 </TD><TD> Same as XY, but with error bars (either one- or two-sided) along X axis </TD></TR><TR><TD>
XYDY </TD><TD> 3 </TD><TD> Same as XYDX, but error bars are along Y axis </TD></TR><TR><TD>
XYDXDX </TD><TD> 4 </TD><TD> Same as XYDX, but left and right error bars are defined separately </TD></TR><TR><TD>
XYDYDY </TD><TD> 4 </TD><TD> Same as XYDXDX, but error bars are along Y axis </TD></TR><TR><TD>
XYDXDY </TD><TD> 4 </TD><TD> Same as XY, but with X and Y error bars (either one- or two-sided) </TD></TR><TR><TD>
XYDXDXDYDY </TD><TD> 6 </TD><TD> Same as XYDXDY, but left/right and upper/lower error bars are defined separately </TD></TR><TR><TD>
BAR </TD><TD> 2 </TD><TD> Same as XY, but vertical bars are used instead of symbols </TD></TR><TR><TD>
BARDY </TD><TD> 3 </TD><TD> Same as BAR, but with error bars (either one- or two-sided) along Y axis </TD></TR><TR><TD>
BARDYDY </TD><TD> 4 </TD><TD> Same as BARDY, but lower and upper error bars are defined separately </TD></TR><TR><TD>
XYHILO </TD><TD> 5 </TD><TD> Hi/Low/Open/Close plot </TD></TR><TR><TD>
XYZ </TD><TD> 3 </TD><TD> Same as XY; makes no sense unless the annotated value is Z </TD></TR><TR><TD>
XYR </TD><TD> 3 </TD><TD> X, Y, Radius. Only allowed in Fixed graphs </TD></TR><TR><TD>
XYSIZE </TD><TD> 3 </TD><TD> Same as XY, but symbol size is variable </TD></TR><TR><TD>
XYCOLOR </TD><TD> 3 </TD><TD> X, Y, color index (of the symbol fill)</TD></TR><TR><TD>
XYCOLPAT </TD><TD> 4 </TD><TD> X, Y, color index, pattern index (currently used for Pie charts only) </TD></TR><TR><TD>
XYVMAP </TD><TD> 4 </TD><TD> Vector map </TD></TR><TR><TD>
XYBOXPLOT </TD><TD> 6 </TD><TD> Box plot (X, median, upper/lower limit, upper/lower whisker) </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>            Set types
          </CAPTION>
</CENTER><BR>
</P>
<P>Not all set types, however, can be plotted on any graph type. The
following table summarizes it:</P>
<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Set type </TD><TD> XY Graph </TD><TD> XY Chart </TD><TD> Fixed </TD><TD> Polar </TD><TD> Pie </TD></TR><TR><TD>
XY </TD><TD> + </TD><TD> + </TD><TD> + </TD><TD> + </TD><TD> + </TD></TR><TR><TD>
XYDX </TD><TD> + </TD><TD> - </TD><TD> + </TD><TD> - </TD><TD> - </TD></TR><TR><TD>
XYDY </TD><TD> + </TD><TD> + </TD><TD> + </TD><TD> - </TD><TD> - </TD></TR><TR><TD>
XYDXDX </TD><TD> + </TD><TD> - </TD><TD> + </TD><TD> - </TD><TD> - </TD></TR><TR><TD>
XYDYDY </TD><TD> + </TD><TD> + </TD><TD> + </TD><TD> - </TD><TD> - </TD></TR><TR><TD>
XYDXDY </TD><TD> + </TD><TD> - </TD><TD> + </TD><TD> - </TD><TD> - </TD></TR><TR><TD>
XYDXDXDYDY </TD><TD> + </TD><TD> - </TD><TD> + </TD><TD> - </TD><TD> - </TD></TR><TR><TD>
BAR </TD><TD> + </TD><TD> + </TD><TD> + </TD><TD> - </TD><TD> - </TD></TR><TR><TD>
BARDY </TD><TD> + </TD><TD> + </TD><TD> - </TD><TD> - </TD><TD> - </TD></TR><TR><TD>
BARDYDY </TD><TD> + </TD><TD> + </TD><TD> - </TD><TD> - </TD><TD> - </TD></TR><TR><TD>
XYHILO </TD><TD> + </TD><TD> - </TD><TD> - </TD><TD> - </TD><TD> - </TD></TR><TR><TD>
XYZ </TD><TD> + </TD><TD> - </TD><TD> + </TD><TD> + </TD><TD> - </TD></TR><TR><TD>
XYR </TD><TD> - </TD><TD> - </TD><TD> + </TD><TD> - </TD><TD> - </TD></TR><TR><TD>
XYSIZE </TD><TD> + </TD><TD> + </TD><TD> + </TD><TD> + </TD><TD> - </TD></TR><TR><TD>
XYCOLOR </TD><TD> + </TD><TD> + </TD><TD> + </TD><TD> + </TD><TD> + </TD></TR><TR><TD>
XYCOLPAT </TD><TD> - </TD><TD> - </TD><TD> - </TD><TD> - </TD><TD> + </TD></TR><TR><TD>
XYVMAP </TD><TD> + </TD><TD> - </TD><TD> + </TD><TD> - </TD><TD> - </TD></TR><TR><TD>
XYBOXPLOT </TD><TD> + </TD><TD> - </TD><TD> - </TD><TD> - </TD><TD> - </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>            Graph/Set type connection
          </CAPTION>
</CENTER><BR>
</P>
<H3><A NAME="regions"></A> Regions</H3>

<P>Regions are sections of a graph defined by the interior or exterior
of a polygon, or a half plane defined by a line. Regions are used to
restrict data transformations to a geometric area covered by region.</P>
<P>Regions are auxiliary objects which are not displayed in print
outputs.</P>
<H3><A NAME="project-file"></A> Project files</H3>

<P>A project file contains all information necessary to restore a plot
created by Grace. Each plot is represented on a single page (this may
change in future), but may have an unlimited number of graphs.You
create a project file of your current plot with File/Save,Save as.</P>
<H3><A NAME="datasets"></A> Datasets</H3>

<P>A dataset is an array of points with X and Y coordinates, up to
four optional data values (which, depending on the set presentation
type, can be displayed as error bars or like) and one optional
character string.</P>
<H3><A NAME="files-formats"></A> Input File formats </H3>

<P>Grace understands several input files formats. The most basic one is
ASCII text files containing space and comma separated columns of
data. The data fields can be either numeric (Fortran 'd' and 'D'
exponent markers are supported) or alphanumeric (with or without
quotes). Several calendar date formats are recognized automatically
and you can specify your own reference for numeric dates formats.
Depending on configuration, Grace can also read NetCDF files (see
<A HREF="#configuration">configuration</A>).</P>
<H3><A NAME="RTI"></A> Real Time Input </H3>

<P>Real Time Input refers to the ability Grace has to be
fed in real time by an external program. The Grace
process spawned by the driver program is a full-featured
Grace instance: the user can interact using the GUI at the
same time the program sends data and commands. The process
will adapt itself to the incoming data rate.</P>
<H3><A NAME="hotlinks"></A> Hotlinks </H3>

<P>Hotlinks are sources containing varying data. Grace can be
instructed a file or a pipe is a hotlink in which case it
will provide specific commands to refresh the data on a
mouse click (a later version will probably allow automatic
refresh).</P>
<H3><A NAME="devices"></A> Devices</H3>

<P>Grace allows the user to choose between several output
devices to produce its graphics. The current list of
supported devices is:</P>
<P>
<UL>
<LI> X11</LI>
<LI> PostScript (level 1 and level 2), suitable for printing</LI>
<LI> EPS (encapsulated PostScript)</LI>
<LI> Metafile (which is Grace format, used at the moment mostly
for debugging purposes)</LI>
<LI> MIF (Maker Interchange Format used by FrameMaker)</LI>
<LI> SVG (Scalable Vector Graphics, a language for describing
two-dimensional vector and mixed vector/raster graphics
in XML)</LI>
<LI> PDF (depends on extra libraries,
see 
<A HREF="#configuration">configuration</A>)</LI>
<LI> PNM (portable anymap file format, depends on extra
libraries, see 
<A HREF="#configuration">configuration</A>)</LI>
<LI> JPEG (depends on extra libraries,
see 
<A HREF="#configuration">configuration</A>)</LI>
<LI> PNG (depends on extra libraries,
see 
<A HREF="#configuration">configuration</A>)</LI>
</UL>
</P>
<P>Grace can also be instructed to launch conversion programs
automatically based on file name. As an example you can produce many
vector formats using pstoedit, or almost any image format using the
netpbm suite (see also the 
<A HREF="FAQ.html">FAQ</A>).</P>
<H3><A NAME="magic-path"></A> Magic path</H3>

<P>In many cases, when Grace needs to access a file given with a
relative <CODE>pathname</CODE>, it searches for the file along the
following path:
<CODE>./pathname:./.grace/pathname:~/.grace/pathname:$GRACE_HOME/pathname</CODE></P>
<H3><A NAME="dynamic-modules"></A> Dynamic modules</H3>

<P>Grace can access external functions present in either system or
third-party shared libraries or modules specially compiled for use
with it. The term dynamic refers to the possibility Grace has to open
the library at run time to find the code of the external function,
there is no need to recompile Grace itself (the functions already
compiled in Grace are "statically linked").</P>
<H2><A NAME="ss3.2">3.2</A> <A HREF="#toc3.2">Invocation</A>
</H2>

<H3>Operational mode</H3>

<P>With respect to the user interface, there are three modes of
operation that Grace can be invoked in. The full-featured GUI-based
version is called <CODE>xmgrace</CODE>. A batch-printing version is
called <CODE>gracebat</CODE>. A command-line interface mode is called
<CODE>grace</CODE>. Usually, a single executable is called in all cases,
with two of the three files being (symbolic) links to a "real" one.</P>
<H3>Command line options</H3>

<P>
<DL>
<DT><B> -autoscale <I>x|y|xy</I> </B><DD><P>Set autoscale type</P>
<DT><B> -barebones </B><DD><P>Turn off all toolbars</P>
<DT><B> -block <I>block_data</I> </B><DD><P>Assume data file is block data</P>
<DT><B> -datehint <I>iso|european|us|days|seconds|nohint</I> </B><DD><P>Set the hint for dates analysis</P>
<DT><B> -dpipe <I>descriptor</I> </B><DD><P>Read data from descriptor (anonymous pipe) on startup</P>
<DT><B> -fixed <I>width</I> <I>height</I> </B><DD><P>Set canvas size fixed to width*height</P>
<DT><B> -free </B><DD><P>Use free page layout</P>
<DT><B> -hardcopy </B><DD><P>No interactive session, just print and quit</P>
<DT><B> -hdevice <I>hardcopy_device_name</I> </B><DD><P>Set default hardcopy device</P>
<DT><B> -hdevice-options <I>option_string</I> </B><DD><P>Set options for default hardcopy device</P>
<DT><B> -install </B><DD><P>Install private colormap</P>
<DT><B> -noask </B><DD><P>Assume the answer is yes to all requests - if the operation would
overwrite a file, Grace will do so without prompting</P>
<DT><B> -noinstall </B><DD><P>Don't use private colormap</P>
<DT><B> -noprint </B><DD><P>In batch mode, do not print</P>
<DT><B> -nosigcatch </B><DD><P>Don't catch signals</P>
<DT><B> -npipe <I>file</I> </B><DD><P>Read data from named pipe on startup</P>
<DT><B> -nxy <I>nxy_file</I> </B><DD><P>Assume data file is in X Y1 Y2 Y3 ... format</P>
<DT><B> -printfile <I>file</I> </B><DD><P>Save print output to file</P>
<DT><B> -results <I>results_file</I> </B><DD><P>Write results of some data manipulations to results_file</P>
<DT><B> -saveall <I>save_file</I> </B><DD><P>Save all graphs to save_file</P>
<DT><B> -seed <I>seed_value</I> </B><DD><P>Integer seed for random number generator</P>
<DT><B> -timer <I>delay</I> </B><DD><P>Set allowed time slice for real time inputs to delay ms</P>
<DT><B> -settype <I>xy|xydx|...</I> </B><DD><P>Set the type of the next data file</P>
<DT><B> -version </B><DD><P>Show the program version</P>
<DT><B> -wd <I>directory</I> </B><DD><P>Set the working directory</P>
<DT><B> -usage|-help </B><DD><P>This message</P>
</DL>
</P>
<H2><A NAME="ss3.3">3.3</A> <A HREF="#toc3.3">Customization</A>
</H2>

<H3><A NAME="environment-variables"></A> Environment variables </H3>

<P>
<DL>
<DT><B> GRACE_HOME </B><DD><P>Set the location of Grace. This will be where help files,
auxiliary programs, and examples are located. If you are unable
to find the location of this directory, contact your system
administrator.</P>
<DT><B> GRACE_PRINT_CMD </B><DD><P>Print command. If the variable is defined but is an empty
string, "Print to file" will be selected as default.</P>
<DT><B> GRACE_EDITOR </B><DD><P>The editor used for manual editing of dataset values.</P>
<DT><B> GRACE_HELPVIEWER </B><DD><P>Invocation string of an HTML viewer for on-line browsing of
help documents. Must include "%s" to be replaced with an
URL string.</P>
<DT><B> GRACE_FFTW_WISDOM_FILE and
GRACE_FFTW_RAM_WISDOM </B><DD><P>These flags control behavior of the FFTW planner (see
<A HREF="#fftw-tuning">FFTW tuning</A> for detailed info).</P>
</DL>
</P>
<H3><A NAME="default-template"></A> Default template</H3>

<P>Whenever a new project is started, Grace loads the default template,
<CODE>templates/Default.xgr</CODE>. The file is searched for in the magic
path (see  
<A HREF="#magic-path">magic path</A>); once found, the
rest of the path is ignored.</P>
<H3>X resources</H3>

<P>The following Grace-specific X resource settings are supported:</P>
<P>
<UL>
<LI> XMgrace.invertDraw<BR>
Use GXinvert rather than GXxor for rubber-band lines.
If the rubber-banding for zooms and lines, etc. doesn't
appear on the canvas, set this resource to yes.</LI>
<LI> XMgrace.toolBar<BR>
Enables button toolbar</LI>
<LI> XMgrace.statusBar<BR>
Enables status bar</LI>
<LI> XMgrace.locatorBar<BR>
Enables locator bar</LI>
<LI> XMgrace.instantUpdate<BR>
Enables instant update feature of Explorer</LI>
</UL>
</P>

<P>It is also possible to customize menus by assigning key accelerators to
any item.</P>
<P>You'll need to derive the item's X resource name from the respective
menu label, which is easily done following these rules:
<UL>
<LI> All non-alphanumeric characters are skipped</LI>
<LI> Start with lower case; each new word (if any) continues from
the capital letter</LI>
<LI> Add the item's type to the end - "Menu" for pulldown menus,
"Button" for menu buttons.</LI>
</UL>
</P>
<P>For example, in order to make Grace popup the Non-linear curve fitting
by pressing Control+F, you would add the following two lines</P>
<P><CODE>XMgrace*transformationsMenu.nonLinearCurveFittingButton.acceleratorText: Ctrl+F<BR>
XMgrace*transformationsMenu.nonLinearCurveFittingButton.accelerator: Ctrl&lt;Key&gt;f</CODE></P>

<P>to your <CODE>.Xresources</CODE> file (the file which is read when an X
session starts; it could be <CODE>.Xdefaults</CODE>, <CODE>.Xsession</CODE> or
some other file - ask your system administrator when in doubt). </P>
<P>Similarly, it may be desirable to alter default filename patterns of
file selection dialogs. The recipe for the dialog's name is like for
menu buttons outlined above, with "Button" being replaced with "FSB".
E.g., to list all files in the "Open project" dialog ("File/Open..."),
set the following resource:</P>
<P><CODE>XMgrace*openProjectFSB.pattern: *</CODE></P>

<H2><A NAME="GUI-guide"></A> <A NAME="s4">4.</A> <A HREF="#toc4">Guide to the graphical user interface</A></H2>

<H2><A NAME="ss4.1">4.1</A> <A HREF="#toc4.1">GUI controls</A>
</H2>

<P>This section describes interface controls - basic building blocks, used in
many popups.</P>
<H3><A NAME="FS-dialog"></A> File selection dialogs </H3>

<P>Whenever the user is expected to provide a filename, either for reading
in or writing some data, a file selection dialog is popped up. In
addition to the standard entries (the directory and file lists and the
filter entry), there is a pulldown menu for quick directory change to
pre-defined locations (the current working directory, user's home
directory and the file system root). Also, a "Set as cwd" button is
there which allows to set any directory as you navigate through the
directory tree as the current working directory (cwd). Once defined, it
can be used in any other file selection dialog to switch to that
directory quickly.</P>
<H3><A NAME="list-selector"></A> List selectors </H3>

<P>Various selectors are available in several popups. They all display
lists of objects (graphs, sets, ...) and can be used to perform
simple operations on these objects (copying, deleting, ...). The
operations are available from a popup menu that appears when pressing
mouse button 3 on them. Depending on the required functionality, they
may allow multiple choices or not.</P>
<P>
<UL>
<LI> hide </LI>
<LI> show </LI>
<LI> delete </LI>
<LI> bring to front </LI>
<LI> move up </LI>
<LI> move down </LI>
<LI> send to back </LI>
<LI> selector operations
<UL>
<LI> select all </LI>
<LI> unselect all </LI>
<LI> invert selection </LI>
<LI> update list </LI>
</UL>
</LI>
</UL>
</P>
<P>The following shortcuts are enabled (if the result of an action would
contradict the list's selection policy, this would be ignored):
<UL>
<LI> Ctrl+a select all </LI>
<LI> Ctrl+u unselect all </LI>
<LI> Ctrl+i invert selection </LI>
</UL>
</P>
<H3><A NAME="frame-selector"></A>  Frame selector </H3>

<P>An extension of the 
<A HREF="#list-selector">list selector</A>.
The additional operations that can be performed on frames through
the frame selector's popup menu are:
<UL>
<LI> create new </LI>
</UL>
</P>
<H3><A NAME="graph-selector"></A>  Graph selector </H3>

<P>An extension of the 
<A HREF="#list-selector">list selector</A>.
The additional operations that can be performed on graphs through
the graph selector's popup menu are:
<UL>
<LI> create new </LI>
<LI> focus to selected </LI>
</UL>
</P>
<P>Double-clicking on a list entry will switch the focus to that graph.</P>
<H3><A NAME="set-selector"></A>  Set selector </H3>

<P>An extension of the 
<A HREF="#list-selector">list selector</A>.
The additional operations that can be performed on sets through the
set selector's popup menu are:
<UL>
<LI> edit
<UL>
<LI> in spreadsheet (see
<A HREF="#SSEditor">Spreadsheet data set editor</A>)</LI>
<LI> in text editor</LI>
</UL>
</LI>
<LI> create new
<UL>
<LI> by formula</LI>
<LI> in spreadsheet (see
<A HREF="#SSEditor">Spreadsheet data set editor</A>)</LI>
<LI> in text editor</LI>
<LI> from block data</LI>
</UL>
</LI>
</UL>
</P>
<P>Double-clicking on a list entry will open the spreadsheet editor
(see 
<A HREF="#SSEditor">Spreadsheet data set editor</A>) on
the set data.</P>
<H3><A NAME="pen-chooser"></A> Pen chooser</H3>

<P>Pen chooser lets you select a pen (a color+pattern combination) for
drawing a line or filling in an object. When you click on the button,
a dialog with color and pattern selectors will appear. When applied,
the pen chooser will itself be painted by the pen. A faster way to
alter pen's color is to press the right mouse button on it, which will
invoke a color-change menu.</P>
<H3><A NAME="SSEditor"></A> Spreadsheet data set editor</H3>

<P>The dialog presents an editable matrix of numbers, corresponding
to the data set being edited. The set type (and hence, the number
of data columns) can be changed using the "Type:" selector.
Clicking on a column label pops up a dialog allowing to adjust
the column formatting. Clicking on the row labels toggles the
respective row state (selected/unselected). The selected rows can
be deleted via the dialog's "Edit" menu. Another entry in this
menu lets you add a row; the place of the new row is determined
by the row containing a cell with the keyboard focus on. As well,
just typing in an empty cell will add one or several rows
(filling the intermediate rows with zeros).</P>
<P>To resize columns, drag the vertical rules using Shift+Button 2.</P>
<H2><A NAME="main-window"></A> <A NAME="ss4.2">4.2</A> <A HREF="#toc4.2">The main window</A>
</H2>

<H3><A NAME="canvas"></A> The canvas</H3>

<H3>Canvas hotkeys</H3>


<P>When the pointer focus is on the canvas (where the graph is drawn),
there are some shortcuts to activate several actions. They are:</P>
<P>
<UL>
<LI> Ctrl &lt;Key&gt;A: Autoscale the current graph </LI>
<LI> Ctrl &lt;Key&gt;U: Refresh hotlinks </LI>
<LI> Ctrl &lt;Key&gt;Z: Zoom </LI>
</UL>
</P>
<H3><A NAME="clicks"></A> Clicks and double clicks</H3>

<P>Mouse wheel (if you got one) scrolls the canvas vertically. With
&lt;Ctrl&gt; pressed, the scroll direction is horizontal.
Alternatively, simply drag the canvas with the mouse.</P>
<P>A single click inside a graph switches focus to that graph. This is
the default policy, but it can be changed from the "Edit/Preferences"
popup.</P>
<P>Double clicking on an object will invoke Explorer with the relevant
Quark selected.</P>
<P>Dragging an object with mouse is possible while &lt;Ctrl&gt; is
pressed.</P>
<P>Pressing 3-rd mouse button on an object pops up a context-sensitive
menu.</P>
<H3><A NAME="toolbar"></A> Toolbar buttons</H3>

<P>Along the left-hand side of the canvas (if shown) is the ToolBar. It
is armed with several buttons to provide quick and easy access to the
more commonly used Grace functions; most of them operate on the current
graph.</P>

<H2><A NAME="file-menu"></A> <A NAME="ss4.3">4.3</A> <A HREF="#toc4.3"> File menu </A>
</H2>

<P>The file menu contains all entries related to the input/output features
of Grace.</P>
<H3><A NAME="new"></A>  New </H3>

<P>Reset the state of Grace as if it had just started (one empty
graph ranging from 0 to 1 along both axes). If some work has
been done and not yet saved, a warning popup is displayed to
allow canceling the operation.</P>
<H3><A NAME="open"></A>  Open </H3>

<P>Open an existing 
<A HREF="#project-file">project file</A>. A
popup is displayed that allow to browse the file system.</P>
<H3><A NAME="save"></A>  Save </H3>

<P>Save the current work in a project file, using the name that was
used for the last open or save. If no name has been set (i.e.,
if the project has been created from scratch) act as 
<A HREF="#save-as">save as</A>.</P>
<H3><A NAME="save-as"></A>  Save as </H3>

<P>Save the current work in a project file with a new name. A popup allows
to browse the file system and set the name, the format to use for saving
data points (the default value is "%16.8g"), and a textual description of
the project. A warning is displayed if a file with the same name already
exists.</P>
<H3><A NAME="revert-to-saved"></A>  Revert to saved </H3>

<P>Abandon all modifications performed on the project since the
last save. A confirmation popup is fired to allow the user
canceling the operation.</P>
<H3><A NAME="print-setup"></A>  Print setup </H3>

<P>Set the properties of the printing device. Each device has its
own set of specific options (see 
<A HREF="#device-settings">Device-specific       settings</A>). According to the device, the
output can be sent either directly to a printer or directed to a
file. The global settings available for all devices are the
sizing parameters. The size of the graph is fixed. Changing the 'Page'
settings changes the size of the canvas underneath the graph.
Switching between portrait and landscape rotates the canvas.
Make sure the canvas size is large enough to hold your graph.
Otherwise you get a 'Printout truncated' warning. If your canvas
size cannot easily be changed because, for example, you want to
print on letter size paper, you need to adjust the size of
your graph ('Viewport' in Plot/Graph Appearance).</P>
<H3><A NAME="print"></A>  Print </H3>

<P>Print the project using the current printer settings</P>
<H3><A NAME="exit"></A>  Exit </H3>

<P>Exit from Grace. If some work has been done and not saved, a
warning popup will be displayed to allow the user to cancel the
operation.</P>
<H2><A NAME="edit-menu"></A> <A NAME="ss4.4">4.4</A> <A HREF="#toc4.4"> Edit menu </A>
</H2>

<H3><A NAME="explorer"></A> Explorer</H3>

<P>This is the most complex dialog. It allows to tune presentation
properties of any plot element.</P>
<P>The left pane of the dialog shows the current project's tree
structure. By clicking on a node, a "plugin" dialog corresponding  to
the quark selected appears in the right pane. A few quarks of the
same type can be selected; in this case, changes will be applied to
all of them.</P>
<H3><A NAME="project-properties"></A> Project properties</H3>

<P>The project properties dialog lets you set page dimensions and
the background color.</P>
<H3><A NAME="frame-properties"></A> Frame properties</H3>

<P>The frame properties dialog governs location of the frame
rectangle and legend properties.</P>
<H3><A NAME="graph-properties"></A> Graph properties</H3>

<P>The main tab includes the properties you will need more often, in
particular, properties related to the graph's coordinate frame.
For each axis, you can define the axis range and a scale types:
linear, logarithmic, or reciprocal, and you can invert the axis
(which normally increases from left to right and from bottom to
top).</P>
<P>The "Locator" tab allows you to customize the display of the
locator, mainly its type and the format and precision of the
display.</P>
<H3><A NAME="set-properties"></A> Set properties</H3>

<P>The main tab gathers the properties you will need more often
(line and symbol properties or legend string for example), and
other tabs are used to fine tune some less frequently used
options (drop lines, fill properties, annotated values and error
bars properties for example).</P>
<P>You should note that, despite the legend string (related to
<EM>one</EM> given set) is entered in the set properties popup,
this is not sufficient to display it. Displaying <EM>all</EM>
legends is a frame-level decision, so the toggle is in the main
tab of the 
<A HREF="#frame-properties">frame properties</A>
plugin dialog.</P>
<P>If you need special characters or special formatting in your
legend, you can use Grace escape sequences (the sequence will
appear verbatim in the text field but will be rendered on the
graph), see 
<A HREF="#typesetting">typesetting</A>. If you
don't remember the mapping between alphabetic characters and the
glyph you need in some specific fonts (mainly symbol and
zapfdingbats), you can invoke the font tool from the text field
by hitting CTRL-e. You can change fonts and select characters
from there, they will be copied back in the text field when you
press the "Accept" button.</P>
<H3><A NAME="axis-properties"></A> Axis properties</H3>

<P>The main tab includes the properties you will need more often
(axis label, tick spacing and format for example), and other tabs
are used to fine tune some less frequently used options (fonts,
sizes, colors, placements, stagger, grid lines, special ticks,
...).</P>
<P>If you need special characters or special formatting in your
label, you can use Grace escape sequences (the sequence will
appear verbatim in the text field but will be rendered on the
graph), see 
<A HREF="#typesetting">typesetting</A>. If you
don't remember the mapping between alphabetic characters and the
glyph you need in some specific fonts (mainly symbol and
zapfdingbats), you can invoke the font tool from the text field
by hitting CTRL-e. You can change fonts and select characters
from there, they will be copied back in the text field when you
press the "Accept" button.</P>
<H3><A NAME="atext-properties"></A> Annotated texts</H3>

<P>Not written yet...</P>
<H3><A NAME="dobject-properties"></A> Drawing objects</H3>

<P>Not written yet...</P>
<H3><A NAME="region-properties"></A> Regions</H3>

<P>This dialog is incomplete as of yet.</P>
<H3><A NAME="arrange-frames"></A>  Arrange frames </H3>

<P>This entry fires up a popup to lay out several graph frames in a
regular grid given by <B>M</B> rows and <B>N</B> columns. </P>
<P>The frame selector at the top allows one to select a number of frames
the arrangement will operate on. If the number of selected frames
isn't equal to <B>M</B> times <B>N</B>,  new frames may be created
or extra frames killed if needed. These options are  controlled by the
respective checkboxes below the frame selector.</P>
<P>The order in which the matrix is filled in with the frames can be
selected (first horizontally then vertically or vise versa, with
either of them inverted). </P>
<P>The rest of the controls of the dialog window deal with the matrix
spacing: left/right/top/bottom page offsets (in the viewport
coordinates) and <I>relative</I> inter-cell distances, vertical
and horizontal. Next to each of the vertical/horizontal spacing
spinboxes, a "Pack" checkbox is found. Enabling it effectively sets
the respective inter-cell distance to zero.</P>
<P>If you don't want the regular layout this arrangement gives you,
you can change it afterwards.</P>
<H3><A NAME="autoscale-graphs"></A>  Autoscale graphs</H3>

<P>Using this entry, you can autoscale a graph
according to the specified sets only. This is useful if you need
either to have truly comparable graphs despite every one
contains data of different ranges, or if you want to focus your
attention on one set only while it is displayed with other data
in a complex graph.</P>
<H3><A NAME="preferences"></A>  Preferences </H3>

<P>The preferences popup allows you to set miscellaneous properties
of your Grace session, such as GUI behavior, cursor type, etc.</P>
<H2><A NAME="data-menu"></A> <A NAME="ss4.5">4.5</A> <A HREF="#toc4.5"> Data menu </A>
</H2>

<H3><A NAME="data-set-operations"></A>  Data set operations </H3>

<P>This popup gathers all operations that are related to the
ordering of data points inside a set or between sets. You can
sort according to any coordinate (X, Y, DX, ...)
in ascending or descending order, reverse the order of the
points, join several sets into one, split one set into several
others of equal lengths, or drop a range of points from a
set.</P>
<H3><A NAME="transformations-menu"></A>  Transformations menu </H3>

<P>The transformations sub-menu gives you access to all data-mining
features of Grace.</P>
<H3><A NAME="evaluate-expression"></A>  Evaluate expression </H3>

<P>Using evaluate expression allows you to create a set by
applying an explicit formula to another set, or to parts of
another set if you use regions restrictions.</P>
<P>All the classical mathematical functions are available (cos,
sin, but also lgamma, j1, erf, ...). As usual all
trigonometric functions use radians by default but you can
specify a unit if you prefer to say cos (x rad) or sin (3 * y
deg). For the full list of available numerical functions and
operators, see
<A HREF="#operators-and-functions">Operators and functions</A>.</P>
<P>In the formula, you can use X, Y, Y1, ..., Y4 to denote any
coordinate you like from the source set. An implicit loop
will be used around your formula so if you say:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
         x = x - 4966.5
         
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>you will shift all points of your set 4966.5 units to the left.</P>
<P>You can use more than one set in the same formula, like this:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
         y = y - 0.653 * sin (x deg) + s2.y
         
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>which means you use both X and Y from the source set but also
the Y coordinate of set 2. Beware that the loop is a simple
loop over the indices, all the sets you use in such an hybrid
expression should therefore have the same number of points
and point i of one set should really be related to point i of
the other set. If your sets do not follow these requirements,
you should first homogenize them using
<A HREF="#interpolation">interpolation</A>.</P>
<H3><A NAME="histograms"></A>  Histograms </H3>

<P>The histograms popup allows you to compute either standard
or cumulative histograms from the Y coordinates of
your data. Optionally, the histograms can be normalized to 1 (hence
producing a PDF (Probability Distribution Function).</P>
<P>The bins can be either a linear mesh defined by its min, max, and
length values, or a mesh formed by abscissas of another set (in which
case abscissas of the set must form a strictly monotonic array).</P>
<H3><A NAME="fourier-transforms"></A>  Fourier transforms </H3>

<P>This popup is devoted to direct and inverse Fourier
transforms. The default is to perform a direct transform on
unfiltered data and to produce a set with the index as
abscissa and magnitude as ordinate. You can filter the input
data window through triangular, Hanning, Welch, Hamming,
Blackman and Parzen filters. You can load magnitude, phase or
coefficients and use either index, frequency or period as
abscissas. You can choose between direct and inverse Fourier
transforms. If you specify real input data, X is assumed to
be equally spaced and ignored; if you specify complex input
data X is taken as the real part and Y as the imaginary part.</P>
<P>If Grace was configured with the FFTW library (see 
<A HREF="#configuration">configuration</A>), then you may want to
use FFTW <I>wisdom</I> files. Then, you should set several 
<A HREF="#environment-variables">environment variables</A> to
name them.</P>
<H3><A NAME="running-properties"></A>  Running properties </H3>

<P>The running properties popup allows you to compute some values
on a sliding window over your data. You choose both the value
you need (average, median, minimum, maximum, standard
deviation) and the length of the window and perform the
operation.</P>
<H3><A NAME="differences"></A>  Differences/derivatives </H3>

<P>The differences popup is used to compute approximations of
the first derivative of a function with finite
differences.
a period to data of the preceding period (namely y[i] - y[i +
period]). Beware that the period is entered in terms of index
in the set and not in terms of abscissa!</P>
<H3><A NAME="integration"></A>  Integration </H3>

<P>The integration popup is used to compute the integral of a
set and optionally to load it. The numerical value of the
integral is shown in the text field after
computation. Selecting "cumulative sum" in the choice item
will create and load a new set with the integral and compute
the end value, selecting "sum only" will only compute the end
value.</P>
<H3><A NAME="interpolation"></A>  Interpolation/Splines </H3>

<P>This popup is used to interpolate a set on an array of alternative X
coordinates. This is mainly used before performing some complex
operations between two sets with the 
<A HREF="#evaluate-expression">evaluate          expression</A> popup.</P>
<P>The sampling array can be either a linear mesh defined by its min,
max, and length values, or a mesh formed by abscissas of another set. </P>
<P>Several interpolation methods can be used: linear, spline or Akima
spline.</P>
<P>Note that if the sampling mesh is not entirely within the source set
X bounds, evaluation at the points beyond the bounds will be performed
using interpolation parameters from the first (or the last) segment
of the source set, which can be considered a primitive extrapolation.
This behaviour can be disabled by checking the "Strict" option on the
popup.</P>
<P>The abscissas of the set being interpolated must form a strictly
monotonic array.</P>
<H3><A NAME="non-linear-fit"></A>  Non-linear fit </H3>

<P>The non linear fit popup can be used for functions outside of
the simple regression methods scope. With this popup you
provide the expression yourself using a0, a1, ..., a9 to
denote the fit parameters (as an example you can say y = a0 * cos
(a1 * x + a2)). You specify a tolerance, starting values and
optional bounds and run several steps before loading the
results.</P>
<P>The fit characteristics (number of parameters, formula, ...)
can be saved in a file and retrieved as needed using the file
menu of the popup.</P>
<P>In the "Advanced" tab, you can additionally apply a restriction to
the set(s) to be fitted (thus ignoring points not satisfying the
criteria), use one of preset weighting schemes or define your own
(notice that "dY" in the preset "1/dY^2" one actually refers to the
third column of the data set; use the "Custom" function if this
doesn't make sense for your data set), and choose whether to load
the fitted values, the residuals or the function itself. Choosing
to load fitted values or residuals leads to a set of the same
length and abscissas as the initial set. Choosing to load the
function is almost similar to load the fitted values except that
you choose yourself the boundaries and the number of points. This
can be used for example to draw the curve outside of the data
sample range or to produce an evenly spaced set from an irregular
one.</P>
<H3><A NAME="correlation/covariance"></A>  Correlation/covariance </H3>

<P>This popup can be used to compute autocorrelation
of one set or cross correlation between two sets. You only
select the set (or sets) and specify the maximum lag. A check
box allows one to evaluate covariance instead of correlation.
The result is normalized so that abs(C(0)) = 1.</P>
<H3><A NAME="linear-convolution"></A>  Linear convolution </H3>

<P>The convolution popup is used to ... convolve two sets. You
only select the sets and apply.</P>
<H3><A NAME="sample-points"></A>  Sample points </H3>

<P>This popup provides a way to sample a set by
selecting only the points that satisfy a boolean expression you
specify.</P>
<H3><A NAME="prune-data"></A>  Prune data </H3>

<P>This popup is devoted to reducing huge sets (and then saving
both computation time and disk space).</P>
<P>The interpolation method can be applied only to ordered sets:
it is based on the assumption that if a real point and an
interpolation based on neighboring points are closer than a
specified threshold, then the point is redundant and can be
eliminated.</P>
<P>The geometric methods (circle, ellipse, rectangle) can be
applied to any set, they test each point in turn and keep
only those that are not in the neighborhood of previous
points.</P>
<H3><A NAME="feature-extraction"></A>  Feature extraction </H3>

<P>Given a set of curves in a graph, extract a feature from each
curve and use the values of the feature to provide the Y values
for a new curve.</P>
<H3><A NAME="read-menu"></A>  Import menu </H3>

<H3><A NAME="read-sets"></A>  ASCII </H3>

<P>Read new sets of data in a graph. A 
<A HREF="#graph-selector">graph selector</A> is used to specify the graph where the
data should go (except when reading block data, which are
copied to graphs later on).</P>
<P>Reading as "Single set" means that if the source contains
only one column of numeric data, one set will be created
using the indices (from 1 to the total number of points) as
abscissas and read values as ordinates and that if the source
contains more than one column of data, the first two numeric
columns will be used. Reading as "NXY" means that the first
numeric column will provide the abscissas and all remaining
columns will provide the ordinates of several sets. Reading
as "Block data" means all column will be read and stored and
that another popup will allow to select the abscissas and
ordinates at will. It should be noted that block data are
stored as long as you do not override them by a new read. You
can still retrieve data from a block long after having closed
all popups, using the 
<A HREF="#set-selector">set          selector</A>.</P>
<P>The set type can be one of the predefined set presentation types
(see 
<A HREF="#sets">sets</A>).</P>
<P>The data source can be selected as "Disk" or "Pipe". In the
first case the text in the "Selection" field is considered to
be a file name (it can be automatically set by the file
selector at the top of the popup). In the latter case the
text is considered to be a command which is executed and
should produce the data on its standard output. On systems
that allows is, the command can be a complete sequence of
programs glued together with pipes.</P>
<P>If the source contains date fields, they should be
automatically detected. Several formats are recognized (see
appendix 
<A HREF="#dates">dates in grace</A>). Calendar
dates are converted to numerical dates upon reading.</P>
<P>The "Autoscale on read" menu controls whether, upon reading in new
sets, which axes of the graph should be autoscaled.</P>
<H3><A NAME="read-netCDF"></A>  NetCDF </H3>

<P>This entry exists only if Grace has been compiled with
support for the NetCDF data format (see 
<A HREF="#configuration">configuration</A>).</P>
<H3><A NAME="write-menu"></A>  Export menu </H3>

<H3><A NAME="write-sets"></A>  ASCII </H3>

<P>Save data sets in a file. A 
<A HREF="#set-selector">set          selector</A> is used to specify the set to be saved. The format
to use for saving data points can be specified (the default
value is "%16.8g"). A warning is displayed if a file with the
same name already exists.</P>
<H2><A NAME="view-menu"></A> <A NAME="ss4.6">4.6</A> <A HREF="#toc4.6">View menu</A>
</H2>

<H3><A NAME="show-hide"></A> Show/hide</H3>

<H3><A NAME="show-locator-bar"></A> Locator bar</H3>

<P>This toggle item shows or hides the locator below the menu bar.</P>
<H3><A NAME="show-status-bar"></A> Status bar</H3>

<P>This toggle item shows or hides the status string below the
canvas.</P>
<H3><A NAME="show-tool-bar"></A> Tool bar</H3>

<P>This toggle item shows or hides the tool bar at the left of the
canvas.</P>
<H3><A NAME="page-zoom"></A> Page zoom</H3>

<H3>Smaller</H3>

<P>Zoom out page.</P>
<H3>Larger</H3>

<P>Zoom in page.</P>
<H3>Original size</H3>

<P>Reset page zoom.</P>
<H3><A NAME="page-rendering"></A> Page rendering</H3>

<P>Set the rendering properties of the display device (font
anti-aliasing and color transformations).</P>
<H3><A NAME="redraw"></A> Redraw</H3>

<P>This menu item triggers a redrawing of the canvas.</P>
<H3><A NAME="update-all"></A> Update all</H3>

<P>This menu item causes an update of all GUI controls. Usually,
everything is updated automatically, unless one makes modifications
by entering commands in the 
<A HREF="#console">Console</A> tool.</P>
<H2><A NAME="tools-menu"></A> <A NAME="ss4.7">4.7</A> <A HREF="#toc4.7">Tools menu</A>
</H2>

<H3><A NAME="font-tool"></A> Font tool</H3>

<P>Not written yet...</P>
<H3><A NAME="console"></A> Console</H3>

<P>The console window displays errors and results of some numerical
operations, e.g. nonlinear fit (see 
<A HREF="#non-linear-fit">Non-linear fit</A>). The window is popped up automatically
whenever an error occurs or new result messages appear. This can
be altered by checking the "Options/Popup only on errors" option.</P>
<P>The dialog also provides an interface to the command driven version
of Grace. Here, commands
can be typed in the "Command:" text item and executed when
&lt;Return&gt; is pressed. The command will be parsed and executed,
and the command line is placed in the history list. Items in the
history list can be recalled by using the keyboard arrow buttons.
Depending on the state of the "Options/Auto redraw" and
"Options/Auto update" checkboxes, each command entered will cause
an immediate resync of the canvas and/or the GUI, respectively.
For a reference on the Grace command interpreter,
see 
<A HREF="#command-interpreter">Command interpreter</A>.</P>
<H3><A NAME="dataset-statistics"></A> Dataset statistics</H3>

<P>Using the dataset statistics popup, you can view statistical
properties of datasets (min, max, mean, standard deviation). A
horizontal scrollbar at the bottom allows to get the two last
properties, they are not displayed by default. Also note that if you
find some columns are too narrow to show all significant digits, you
can drag the vertical rules using Shift+Button 2.</P>
<H2><A NAME="help-menu"></A> <A NAME="ss4.8">4.8</A> <A HREF="#toc4.8">Help menu</A>
</H2>

<H3><A NAME="on-context"></A> On context</H3>

<P>Click on any element of the interface to get context-sensitive help
on it. Only partially implemented at the moment.</P>
<H3><A NAME="users-guide"></A> User's guide</H3>

<P>Browse the Grace user's guide.</P>
<H3><A NAME="faq"></A> FAQ</H3>

<P>Frequently Asked Questions with answers.</P>
<H3><A NAME="changes"></A> Changes</H3>

<P>The list of changes during the Grace development.</P>
<H3><A NAME="examples"></A>  Examples </H3>

<P>The whole tree of submenus each loading a sample plot.</P>
<H3> Web support</H3>

<H3> Home page</H3>

<P>Open the official Grace home page.</P>
<H3> Forums</H3>

<P>Go to Grace forums, where you can participate in discussions.</P>
<H3> Report an issue</H3>

<P>Use this to send your suggestions or bug reports.</P>
<H3><A NAME="license-terms"></A>  License terms </H3>

<P>Grace licensing terms will be displayed (GPL version 2).</P>
<H3><A NAME="about"></A>  About </H3>

<P>A popup with basic info on the software, including some
configuration details. More details can be found when running Grace
with the "-version" command line flag.</P>
<H2><A NAME="command-interpreter"></A> <A NAME="s5">5.</A> <A HREF="#toc5">Command interpreter </A></H2>

<H2><A NAME="ss5.1">5.1</A> <A HREF="#toc5.1">General notes</A>
</H2>

<P>The interpreter parses its input in a line-by-line manner. There may
be several statements per line, separated by semicolon (<CODE>;</CODE>).
The maximal line length is 4 kbytes (hardcoded). The parser is
case-insensitive and ignores lines beginning with the "<CODE>#</CODE>" sign.</P>
<H2><A NAME="ss5.2">5.2</A> <A HREF="#toc5.2">Definitions</A>
</H2>

<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Name </TD><TD> Description </TD><TD> Examples </TD></TR><TR><TD>
expr </TD><TD>Any numeric expression </TD><TD>1.5 + sin(2) </TD></TR><TR><TD>
iexpr </TD><TD>Any expression that evaluates to an integer </TD><TD>25, 0.1 + 1.9, PI/asin(1) </TD></TR><TR><TD>
nexpr </TD><TD>Non-negative iexpr </TD><TD>2 - 1 </TD></TR><TR><TD>
indx </TD><TD>Non-negative iexpr </TD><TD>&nbsp; </TD></TR><TR><TD>
qstr </TD><TD>Quoted string </TD><TD>"a string" </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>        
<A NAME="types"></A> 
        Basic types
      </CAPTION>
</CENTER><BR>
</P>
<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Expression </TD><TD> Description </TD><TD> Types </TD><TD> Example </TD></TR><TR><TD>
X </TD><TD>the first column </TD><TD>- </TD><TD>X </TD></TR><TR><TD>
Y </TD><TD>the second column </TD><TD>- </TD><TD>Y </TD></TR><TR><TD>
Y<I>n</I> </TD><TD>(<I>n</I> + 2)-th column </TD><TD><I>n</I> = 0 - 4 </TD><TD>Y3 </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>        
<A NAME="datacol-sel"></A> 
        Data column selections
      </CAPTION>
</CENTER><BR>
</P>
<P>Not finished yet...</P>
<H2><A NAME="ss5.3">5.3</A> <A HREF="#toc5.3">Variables</A>
</H2>


<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Variable </TD><TD> Description </TD></TR><TR><TD>
datacolumn </TD><TD> data column of current set </TD></TR><TR><TD>
set.datacolumn </TD><TD> data column of set </TD></TR><TR><TD>
vvar </TD><TD> user-defined array </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>        
<A NAME="vvariables"></A> 
        Vector variables
      </CAPTION>
</CENTER><BR>
</P>
<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Variable </TD><TD> Description </TD></TR><TR><TD>
vvariable[i] </TD><TD> i-th element of a vector variable </TD></TR><TR><TD>
var </TD><TD> user-defined variable </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>        
<A NAME="svariables"></A> 
        Scalar variables
      </CAPTION>
</CENTER><BR>
</P>
<H2><A NAME="operators-and-functions"></A> <A NAME="ss5.4">5.4</A> <A HREF="#toc5.4">Numerical operators and functions</A>
</H2>

<P>In numerical expressions, the infix format is used. Arguments of
both operators and functions can be either scalars or vector arrays.</P>

<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Operator </TD><TD> Description </TD></TR><TR><TD>
+ </TD><TD> addition </TD></TR><TR><TD>
- </TD><TD> substraction </TD></TR><TR><TD>
* </TD><TD> multiplication </TD></TR><TR><TD>
/ </TD><TD> division </TD></TR><TR><TD>
% </TD><TD> modulus </TD></TR><TR><TD>
^ </TD><TD> raising to power </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>        
<A NAME="arithmetic-operators"></A> 
        Arithmetic operators
      </CAPTION>
</CENTER><BR>
</P>


<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Operator </TD><TD> Description </TD></TR><TR><TD>
AND or &amp;&amp; </TD><TD> logical AND </TD></TR><TR><TD>
OR or || </TD><TD> logical OR </TD></TR><TR><TD>
NOT or ! </TD><TD> logical NOT </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>        
<A NAME="logical-operators"></A> 
        Logical operators
      </CAPTION>
</CENTER><BR>
</P>


<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Operator </TD><TD> Description </TD></TR><TR><TD>
EQ or == </TD><TD> equal </TD></TR><TR><TD>
NE or != </TD><TD> not equal </TD></TR><TR><TD>
LT or &lt; </TD><TD> less than </TD></TR><TR><TD>
LE or &lt;= </TD><TD> less than or equal </TD></TR><TR><TD>
GT or &gt; </TD><TD> greater than </TD></TR><TR><TD>
GE or &gt;= </TD><TD> greater than or equal </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>        
<A NAME="comparison-operators"></A> 
        Comparison operators
      </CAPTION>
</CENTER><BR>
</P>


<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Function </TD><TD> Description </TD></TR><TR><TD>
abs(x) </TD><TD> absolute value </TD></TR><TR><TD>
acos(x) </TD><TD> arccosine </TD></TR><TR><TD>
acosh(x) </TD><TD> hyperbolic arccosine </TD></TR><TR><TD>
asin(x) </TD><TD> arcsine </TD></TR><TR><TD>
asinh(x) </TD><TD> hyperbolic arcsine </TD></TR><TR><TD>
atan(x) </TD><TD> arctangent </TD></TR><TR><TD>
atan2(y,x) </TD><TD> arc tangent of two variables </TD></TR><TR><TD>
atanh(x) </TD><TD> hyperbolic arctangent </TD></TR><TR><TD>
ceil(x) </TD><TD> greatest integer function </TD></TR><TR><TD>
cos(x) </TD><TD> cosine </TD></TR><TR><TD>
cosh(x) </TD><TD> hyperbolic cosine </TD></TR><TR><TD>
exp(x) </TD><TD> e^x </TD></TR><TR><TD>
fac(n) </TD><TD> factorial function, n! </TD></TR><TR><TD>
floor(x) </TD><TD> least integer function </TD></TR><TR><TD>
irand(n) </TD><TD> random integer less than n </TD></TR><TR><TD>
ln(x) </TD><TD> natural log </TD></TR><TR><TD>
log10(x) </TD><TD> log base 10 </TD></TR><TR><TD>
log2(x) </TD><TD> base 2 logarithm of x </TD></TR><TR><TD>
maxof(x,y) </TD><TD> returns greater of x and y </TD></TR><TR><TD>
mesh(n) </TD><TD> mesh array (0 ... n - 1) </TD></TR><TR><TD>
mesh(x1, x2, n) </TD><TD> mesh array of n equally spaced points between x1 and x2 inclusive </TD></TR><TR><TD>
minof(x,y) </TD><TD> returns lesser of x and y </TD></TR><TR><TD>
mod(x,y) </TD><TD> mod function (also x % y) </TD></TR><TR><TD>
pi </TD><TD> the PI constant </TD></TR><TR><TD>
rand </TD><TD> pseudo random number distributed uniformly on (0.0,1.0) </TD></TR><TR><TD>
rand(n) </TD><TD> array of n random numbers </TD></TR><TR><TD>
rint(x) </TD><TD> round to closest integer </TD></TR><TR><TD>
sin(x) </TD><TD> sine function </TD></TR><TR><TD>
sinh(x) </TD><TD> hyperbolic sine </TD></TR><TR><TD>
sqr(x) </TD><TD> x^2 </TD></TR><TR><TD>
sqrt(x) </TD><TD> x^0.5 </TD></TR><TR><TD>
tan(x) </TD><TD> tangent function </TD></TR><TR><TD>
tanh(x) </TD><TD> hyperbolic tangent </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>        
<A NAME="functions"></A> 
        Functions
      </CAPTION>
</CENTER><BR>
</P>

<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Function </TD><TD> Description </TD></TR><TR><TD>
chdtr(df, x) </TD><TD> chi-square distribution </TD></TR><TR><TD>
chdtrc(v, x) </TD><TD> complemented Chi-square distribution </TD></TR><TR><TD>
chdtri(df, y) </TD><TD> inverse of complemented Chi-square distribution </TD></TR><TR><TD>
erf(x) </TD><TD> error function </TD></TR><TR><TD>
erfc(x) </TD><TD> complement of error function </TD></TR><TR><TD>
fdtr(df1, df2, x) </TD><TD> F distribution function </TD></TR><TR><TD>
fdtrc(x) </TD><TD> complemented F distribution </TD></TR><TR><TD>
fdtri(x) </TD><TD> inverse of complemented F distribution </TD></TR><TR><TD>
gdtr(a, b, x) </TD><TD> gamma distribution function </TD></TR><TR><TD>
gdtrc(a, b, x) </TD><TD> complemented gamma distribution function </TD></TR><TR><TD>
ndtr(x) </TD><TD> Normal distribution function </TD></TR><TR><TD>
ndtri(x) </TD><TD> inverse of Normal distribution function </TD></TR><TR><TD>
norm(x) </TD><TD> gaussian density function </TD></TR><TR><TD>
pdtr(k, m) </TD><TD> Poisson distribution </TD></TR><TR><TD>
pdtrc(k, m) </TD><TD> complemented Poisson distribution </TD></TR><TR><TD>
pdtri(k, y) </TD><TD> inverse Poisson distribution </TD></TR><TR><TD>
rnorm(xbar,s) </TD><TD> pseudo random number distributed N(xbar,s) </TD></TR><TR><TD>
stdtr(k, t) </TD><TD> Student's t distribution </TD></TR><TR><TD>
stdtri(k, p) </TD><TD> functional inverse of Student's t distribution </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>        
<A NAME="stat-functions"></A> 
        Statistical functions
      </CAPTION>
</CENTER><BR>
</P>


<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Function </TD><TD> Description </TD></TR><TR><TD>
ai(x), bi(x) </TD><TD> Airy functions (two independent solutions of the differential equation <CODE>y''(x) = xy</CODE>) </TD></TR><TR><TD>
beta(x) </TD><TD> beta function </TD></TR><TR><TD>
chi(x) </TD><TD> hyperbolic cosine integral </TD></TR><TR><TD>
ci(x) </TD><TD> cosine integral </TD></TR><TR><TD>
dawsn(x) </TD><TD> Dawson's integral </TD></TR><TR><TD>
ellie(phi, m) </TD><TD> incomplete elliptic integral of the second kind </TD></TR><TR><TD>
ellik(phi, m) </TD><TD> incomplete elliptic integral of the first kind </TD></TR><TR><TD>
ellpe(m) </TD><TD> complete elliptic integral of the second kind </TD></TR><TR><TD>
ellpk(m) </TD><TD> complete elliptic integral of the first kind </TD></TR><TR><TD>
expn(n, x) </TD><TD> exponential integral </TD></TR><TR><TD>
fresnlc(x) </TD><TD> cosine Fresnel integral </TD></TR><TR><TD>
fresnls(x) </TD><TD> sine Fresnel integral </TD></TR><TR><TD>
gamma(x) </TD><TD> gamma function </TD></TR><TR><TD>
hyp2f1(a, b, c, x) </TD><TD> Gauss hyper-geometric function </TD></TR><TR><TD>
hyperg(a, b, x) </TD><TD> confluent hyper-geometric function </TD></TR><TR><TD>
i0e(x) </TD><TD> modified Bessel function of order zero, exponentially scaled </TD></TR><TR><TD>
i1e(x) </TD><TD> modified Bessel function of order one, exponentially scaled </TD></TR><TR><TD>
igam(a, x) </TD><TD> incomplete gamma integral </TD></TR><TR><TD>
igamc(a, x) </TD><TD> complemented incomplete gamma integral </TD></TR><TR><TD>
igami(a, p) </TD><TD> inverse of complemented incomplete gamma integral </TD></TR><TR><TD>
incbet(a, b, x) </TD><TD> incomplete beta integral </TD></TR><TR><TD>
incbi(a, b, y) </TD><TD> Inverse of incomplete beta integral </TD></TR><TR><TD>
iv(v, x) </TD><TD> modified Bessel function of order v </TD></TR><TR><TD>
jv(v, x) </TD><TD> Bessel function of order v </TD></TR><TR><TD>
k0e(x) </TD><TD> modified Bessel function, third kind, order zero, exponentially scaled </TD></TR><TR><TD>
k1e(x) </TD><TD> modified Bessel function, third kind, order one, exponentially scaled </TD></TR><TR><TD>
kn(n, x) </TD><TD> modified Bessel function, third kind, integer order </TD></TR><TR><TD>
lbeta(x) </TD><TD> natural log of |beta(x)| </TD></TR><TR><TD>
lgamma(x) </TD><TD> log of gamma function </TD></TR><TR><TD>
psi(x) </TD><TD> psi (digamma) function </TD></TR><TR><TD>
rgamma(x) </TD><TD> reciprocal gamma function </TD></TR><TR><TD>
shi(x) </TD><TD> hyperbolic sine integral </TD></TR><TR><TD>
si(x) </TD><TD> sine integral </TD></TR><TR><TD>
spence(x) </TD><TD> dilogarithm </TD></TR><TR><TD>
struve(v, x) </TD><TD> Struve function </TD></TR><TR><TD>
yv(v, x) </TD><TD> Bessel function of order v </TD></TR><TR><TD>
zeta(x, q) </TD><TD> Riemann zeta function of two arguments </TD></TR><TR><TD>
zetac(x) </TD><TD> Riemann zeta function </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>        
<A NAME="spec-functions"></A> 
        Special math functions
      </CAPTION>
</CENTER><BR>
</P>
<H2><A NAME="s6">6.</A> <A HREF="#toc6">Advanced topics</A></H2>

<H2><A NAME="fonts"></A> <A NAME="ss6.1">6.1</A> <A HREF="#toc6.1">Fonts</A>
</H2>

<P>For all devices, Grace uses Type1 fonts. Both PFA (ASCII) and PFB
(binary) formats can be used.</P>
<H3>Font configuration</H3>

<P>The file responsible for the font configurations of Grace is
<CODE>fonts/FontDataBase</CODE>. The first line contains a positive integer
specifying the number of fonts declared in that file. All remaining lines
contain declarations of one font each, composed out of three fields:
<OL>
<LI> Font name. The name will appear in the font selector controls.
Also, backend devices that has built-in fonts, will be given the
name as a font identifier.</LI>
<LI> Font fall-back. Grace will try to use this in case the real
font is not found.</LI>
<LI> Font filename. The file with the font outline data.</LI>
</OL>
</P>
<P>Here is the default <CODE>FontDataBase</CODE> file:
<BLOCKQUOTE><CODE>
<HR>
<PRE>
14
Times-Roman             Times-Roman             n021003l.pfb
Times-Italic            Times-Italic            n021023l.pfb
Times-Bold              Times-Bold              n021004l.pfb
Times-BoldItalic        Times-BoldItalic        n021024l.pfb
Helvetica               Helvetica               n019003l.pfb
Helvetica-Oblique       Helvetica-Oblique       n019023l.pfb
Helvetica-Bold          Helvetica-Bold          n019004l.pfb
Helvetica-BoldOblique   Helvetica-BoldOblique   n019024l.pfb
Courier                 Courier                 n022003l.pfb
Courier-Oblique         Courier-Oblique         n022023l.pfb
Courier-Bold            Courier-Bold            n022004l.pfb
Courier-BoldOblique     Courier-BoldOblique     n022024l.pfb
Symbol                  Symbol                  s050000l.pfb
ZapfDingbats            ZapfDingbats            d050000l.pfb
      
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<H3>Font data files</H3>

<P>For text rastering, three types of files are used.
<OL>
<LI> <CODE>.pfa</CODE>-/<CODE>.pfb</CODE>-files: These contain the character
outline descriptions. The files are assumed to be in the
<CODE>fonts/type1</CODE> directory; these are the filenames
specified in the <CODE>FontDataBase</CODE> configuration file.</LI>
<LI> <CODE>.afm</CODE>-files: These contain high-precision font metric
descriptions as well as some extra information, such as kerning
and ligature information for a particular font. It is assumed
that the filename of a font metric file has same basename as the
respective font outline file, but with the <CODE>.afm</CODE>
extension; the metric files are expected to be found in the
<CODE>fonts/type1</CODE> directory, too.</LI>
<LI> <CODE>.enc</CODE>-files: These contain encoding arrays in a special
but simple form. They are only needed if someone wants to load
a special encoding to re-encode a font. Their place is
<CODE>fonts/enc</CODE></LI>
</OL>
</P>
<H3>Custom fonts</H3>

<P>It is possible to use custom fonts with Grace. One mostly needs to use
extra fonts for the purpose of localization. For many European
languages, the standard fonts supplied with Grace should contain all the
characters needed, but encoding may have to be adjusted. This is done by
putting a <CODE>Default.enc</CODE> file with proper encoding scheme into the
<CODE>fonts/enc</CODE> directory. Grace comes with a few encoding files in
the directory; more can be easily found on the Internet. (If the
<CODE>Default.enc</CODE> file doesn't exist, the IsoLatin1 encoding will be
used). Notice that for fonts having an encoding scheme in themselves
(such as the Symbol font, and many nationalized fonts) the default
encoding is ignored.</P>
<P>If you do need to use extra fonts, you should modify the
<CODE>FontDataBase</CODE> file accordingly, obeying its format. However,
if you are going to exchange Grace project files with other people who
do not have the extra fonts configured, an important thing is to define
reasonable fall-back font names.</P>
<P>For example, let us assume I use Hebrew fonts, and the configuration file
has lines like these:
<BLOCKQUOTE><CODE>
<HR>
<PRE>
    ...
Courier-Hebrew              Courier                 courh___.pfa
Courier-Hebrew-Oblique      Courier-Oblique         courho__.pfa
    ...
      
</PRE>
<HR>
</CODE></BLOCKQUOTE>

My colleague, who lives in Russia, uses Cyrillic fonts with Grace
configured like this:
<BLOCKQUOTE><CODE>
<HR>
<PRE>
    ...
Cronix-Courier              Courier                 croxc.pfb
Cronix-Courier-Oblique      Courier-Oblique         croxco.pfb
    ...
      
</PRE>
<HR>
</CODE></BLOCKQUOTE>

The font mapping information (Font name &lt;-&gt; Font fall-back) is
stored in the Grace project files. Provided that all the localized fonts
have English characters in the lower part of the ASCII table unmodified,
I can send my friend files (with no Hebrew characters, of course) and be
sure they render correctly on his computer.</P>
<P>Thus, with properly configured national fonts, you can make localized
annotations for plots intended for internal use of your institution,
while being able to exchange files with colleagues from abroad. People
who ever tried to do this with MS Office applications should appreciate
the flexibility :-).</P>
<H2><A NAME="ss6.2">6.2</A> <A HREF="#toc6.2">Interaction with other applications</A>
</H2>

<H3>Using pipes</H3>

<H2><A NAME="fftw-tuning"></A> <A NAME="ss6.3">6.3</A> <A HREF="#toc6.3">FFTW tuning</A>
</H2>

<P>When the FFTW capabilities are compiled in, Grace looks at two environment
variables to decide what to do with the FFTW 'wisdom' capabilities. 
First, a quick summary of what this is. The FFTW package is capable of
adaptively determining the most efficient factorization of a set to give
the fastest computation.  It can store these factorizations as 'wisdom',
so that if a transform of a given size is to be repeated, it is does not
have to re-adapt.  The good news is that this seems to work very well. 
The bad news is that, the first time a transform of a given size is
computed, if it is not a sub-multiple of one already known, it takes a LONG
time (seconds to minutes).</P>
<P>The first environment variable is GRACE_FFTW_WISDOM_FILE. If this is set
to the name of a file which can be read and written (e.g.,
$HOME/.grace_fftw_wisdom) then Grace will automatically create this file
(if needed) and maintain it. If the file is read-only, it will be read,
but not updated with new wisdom. If the symbol GRACE_FFTW_WISDOM_FILE
either doesn't exist, or evaluates to an empty string, Grace will drop the
use of wisdom, and will use the fftw estimator (FFTW_ESTIMATE flag sent to
the planner) to guess a good factorization, instead of adaptively
determining it.</P>
<P>The second variable is GRACE_FFTW_RAM_WISDOM. If this variable is defined
to be non-zero, and GRACE_FFTW_WISDOM_FILE variable is not defined (or is
an empty string), Grace will use wisdom internally, but maintain no
persistent cache of it. This will result in very slow execution times the
first time a transform is executed after Grace is started, but very fast
repeats. I am not sure why anyone would want to use wisdom without
writing it to disk, but if you do, you can use this flag to enable it.</P>
<H2><A NAME="dl-modules"></A> <A NAME="ss6.4">6.4</A> <A HREF="#toc6.4">DL modules </A>
</H2>

<P>Grace can access external functions present
in either system or third-party shared libraries or modules
specially compiled for use with Grace.</P>
<H3>Function types</H3>

<P>One must make sure, however, that the external function is of one
of supported by Grace types:
<BR><CENTER>
<TABLE BORDER><TR><TD>
Grace type </TD><TD> Description </TD></TR><TR><TD>
f_of_i </TD><TD> a function of 1 <CODE>int</CODE> variable </TD></TR><TR><TD>
f_of_d </TD><TD> a function of 1 <CODE>double</CODE> variable </TD></TR><TR><TD>
f_of_nn </TD><TD> a function of 2 <CODE>int</CODE> parameters </TD></TR><TR><TD>
f_of_nd </TD><TD> a function of 1 <CODE>int</CODE> parameter and 1 <CODE>double</CODE> variable </TD></TR><TR><TD>
f_of_dd </TD><TD> a function of 2 <CODE>double</CODE> variables </TD></TR><TR><TD>
f_of_nnd </TD><TD> a function of 2 <CODE>int</CODE> parameters and 1 <CODE>double</CODE> variable </TD></TR><TR><TD>
f_of_ppd </TD><TD> a function of 2 <CODE>double</CODE> parameters and 1 <CODE>double</CODE> variable </TD></TR><TR><TD>
f_of_pppd </TD><TD> a function of 3 <CODE>double</CODE> parameters and 1 <CODE>double</CODE> variable </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>              
<A NAME="grace-types"></A> 
              Grace types for external functions
      </CAPTION>
</CENTER><BR>
</P>
<P>The return values of functions are assumed to be of the
<CODE>double</CODE> type.</P>
<P>Note, that there is no difference from the point of view of
function prototype between parameters and variables; the
difference is in the way Grace treats them - an attempt to use
a vector expression as a parameter argument will result in a
parse error.</P>
<P>Let us consider few examples.</P>
<H3>Examples</H3>

<P>Caution: the examples provided below (paths and compiler flags)
are valid for Linux/ELF with gcc. On other operating systems,
you may need to refer to compiler/linker manuals or ask a guru.</P>
<H3>Example 1</H3>

<P>Suppose I want to use function <CODE>pow(x,y)</CODE> from the Un*x math
library (libm). Of course, you can use the "^" operator defined
in the Grace language, but here, for the sake of example, we
want to access the function directly.</P>
<P>The command to make it accessible by Grace is
<BLOCKQUOTE><CODE>
USE "pow" TYPE f_of_dd FROM "/usr/lib/libm.so"
</CODE></BLOCKQUOTE>
</P>
<P>Try to plot y = pow(x,2) and y = x^2 graphs (using, for
example, "create new -&gt; Formula" from any 
<A HREF="#set-selector">set        selector</A>) and compare.</P>
<H3>Example 2</H3>

<P>Now, let us try to write a function ourselves. We will define
function <CODE>my_function</CODE> which simply returns its (second)
argument multiplied by integer parameter transferred as the
first argument.</P>
<P>In a text editor, type in the following C code and save it as
"my_func.c":</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
       double my_function (int n, double x)
       {
           double retval;
           retval = (double) n * x;
           return (retval);
       }
       
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>OK, now compile it:</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
       $gcc -c -fPIC my_func.c
       $gcc -shared my_func.o -o /tmp/my_func.so
       
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>(You may strip it to save some disk space):</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
       $strip /tmp/my_func.so
       
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>That's all! Ready to make it visible to Grace as "myf" - we are
too lazy to type the very long string "my_function" many times.</P>
<P>
<BLOCKQUOTE><CODE>
USE "my_function" TYPE f_of_nd FROM "/tmp/my_func.so" ALIAS "myf"
</CODE></BLOCKQUOTE>
</P>
<H3>Example 3</H3>

<P>A more serious example. There is a special third-party library
available on your system which includes a very important for
you yet very difficult-to-program from the scratch function
that you want to use with Grace.  But, the function prototype
is NOT one of any predefined 
<A HREF="#grace-types">types</A>.  The solution is to write a simple function
wrapper. Here is how:</P>
<P>Suppose, the name of the library is "special_lib" and the
function you are interested in is called "special_func" and
according to the library manual, should be accessed as <CODE>void
special_func(double *input, double *output, int parameter)</CODE>.
The wrapper would look like this:</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
       double my_wrapper(int n, double x)
       {
           extern void special_func(double *x, double *y, int n);
           double retval;
           (void) special_func(&amp;x, &amp;retval, n);
           return (retval);
       }
       
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>Compile it:</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
       $gcc -c -fPIC my_wrap.c
       $gcc -shared my_wrap.o -o /tmp/my_wrap.so -lspecial_lib -lblas
       $strip /tmp/my_wrap.so
       
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>Note that I added <CODE>-lblas</CODE> assuming that the special_lib
library uses some functions from the BLAS. Generally, you have
to add <I>all</I> libraries which your module depends on (and
all libraries those libraries rely upon etc.), as if you wanted
to compile a plain executable.</P>
<P>Fine, make Grace aware of the new function</P>
<P>
<BLOCKQUOTE><CODE>
USE "my_wrapper" TYPE f_of_nd FROM "/tmp/my_wrap.so" ALIAS "special_func"
</CODE></BLOCKQUOTE>
</P>
<P>so we can use it with its original name.</P>
<H3>Example 4</H3>

<P>An example of using Fortran modules.</P>
<P>Here we will try to achieve the same functionality as in
Example 2, but with the help of F77.</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
       DOUBLE PRECISION FUNCTION MYFUNC (N, X)
       IMPLICIT NONE
       INTEGER N
       DOUBLE PRECISION X
C
       MYFUNC = N * X
C
       RETURN
       END
       
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>As opposite to C, there is no way to call such a function from
Grace directly - the problem is that in Fortran all arguments
to a function (or subroutine) are passed by reference. So, we
need a wrapper:</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
       double myfunc_wrapper(int n, double x)
       {
           extern double myfunc_(int *, double *);
           double retval;
           retval = myfunc_(&amp;n, &amp;x);
           return (retval);
       }
       
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>Note that most of f77 compilers by default add underscore to
the function names and convert all names to the lower case,
hence I refer to the Fortran function <CODE>MYFUNC</CODE> from my C
wrapper as <CODE>myfunc_</CODE>, but in your case it can be different!</P>
<P>Let us compile the whole stuff:</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
       $g77 -c -fPIC myfunc.f
       $gcc -c -fPIC myfunc_wrap.c
       $gcc -shared myfunc.o myfunc_wrap.o -o /tmp/myfunc.so -lf2c -lm
       $strip /tmp/myfunc.so
       
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>And finally, inform Grace about this new function:</P>
<P>
<BLOCKQUOTE><CODE>
USE "myfunc_wrapper" TYPE f_of_nd FROM "/tmp/myfunc.so" ALIAS "myfunc"
</CODE></BLOCKQUOTE>
</P>
<H3>Operating system issues</H3>

<H3>OS/2</H3>

<P>In general the method outlined in the examples above can be
used on OS/2, too. However you have to create a DLL (Dynamic Link Library)
which is a bit more tricky on OS/2 than on most Un*x systems.
Since Grace was ported by using EMX we also use it to create
the examples; however other development environments should work
as well (ensure to use the _System calling convention!).
We refer to Example 2 only. Example 1 might demonstrate
that DLLs can have their entry points (i.e. exported functions)
callable via ordinals only, so you might not know how to access a
specific function without some research.
First compile the source from Example 2 to "my_func.obj"</P>
<P>
<BLOCKQUOTE><CODE>
gcc -Zomf -Zmt -c my_func.c -o my_func.obj
</CODE></BLOCKQUOTE>
</P>
<P>Then you need to create a linker definition file "my_func.def"
which contains some basic info about the DLL and declares
the exported functions.</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
         LIBRARY my_func INITINSTANCE TERMINSTANCE
         CODE LOADONCALL
         DATA LOADONCALL MULTIPLE NONSHARED
         DESCRIPTION 'This is a test DLL: my_func.dll'
         EXPORTS
         my_function
         
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>(don't forget about the 8 characters limit on the DLL name!).
Finally link the DLL:</P>
<P>
<BLOCKQUOTE><CODE>
gcc my_func.obj my_func.def -o my_func.dll -Zdll -Zno-rte -Zmt -Zomf
</CODE></BLOCKQUOTE>
</P>
<P>(check out the EMX documentation about the compiler/linker flags
used here!)
To use this new library function within Grace you may either
put the DLL in the LIBPATH and use the short form:</P>
<P>
<BLOCKQUOTE><CODE>
USE "my_function" TYPE f_of_nd FROM "my_func" ALIAS "myf"
</CODE></BLOCKQUOTE>
</P>
<P>or put it in an arbitrary path which you need to specify explicitly
then:</P>
<P>
<BLOCKQUOTE><CODE>
USE "my_function" TYPE f_of_nd FROM "e:/foo/my_func.dll" ALIAS "myf"
</CODE></BLOCKQUOTE>
</P>
<P>(as for most system-APIs you may use the Un*x-like forward
slashs within the path!)</P>
<H2><A NAME="s7">7.</A> <A HREF="#toc7"> References</A></H2>

<H2><A NAME="typesetting"></A> <A NAME="ss7.1">7.1</A> <A HREF="#toc7.1">Typesetting</A>
</H2>

<P>Grace permits quite complex typesetting on a per string basis.
Any string displayed (titles, legends, tick marks,...) may contain
special control codes to display subscripts, change fonts within the
string etc.</P>

<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Control code </TD><TD> Description </TD></TR><TR><TD>
\f{x} </TD><TD> switch to font named "x" </TD></TR><TR><TD>
\f{n} </TD><TD> switch to font number n </TD></TR><TR><TD>
\f{} </TD><TD> return to original font </TD></TR><TR><TD>
\R{x} </TD><TD> switch to color named "x" </TD></TR><TR><TD>
\R{n} </TD><TD> switch to color number n </TD></TR><TR><TD>
\R{} </TD><TD> return to original color </TD></TR><TR><TD>
\#{x} </TD><TD> treat "x" (must be of even length) as list of hexadecimal char codes </TD></TR><TR><TD>
\t{xx xy yx yy} </TD><TD> apply transformation matrix </TD></TR><TR><TD>
\t{} </TD><TD> reset transformation matrix </TD></TR><TR><TD>
\z{x} </TD><TD> zoom x times </TD></TR><TR><TD>
\z{} </TD><TD> return to original zoom </TD></TR><TR><TD>
\r{x} </TD><TD> rotate by x degrees </TD></TR><TR><TD>
\l{x} </TD><TD> slant by factor x </TD></TR><TR><TD>
\v{x} </TD><TD> shift vertically by x </TD></TR><TR><TD>
\v{} </TD><TD> return to unshifted baseline </TD></TR><TR><TD>
\V{x} </TD><TD> shift baseline by x </TD></TR><TR><TD>
\V{} </TD><TD> reset baseline </TD></TR><TR><TD>
\h{x} </TD><TD> horizontal shift by x </TD></TR><TR><TD>
\n </TD><TD> new line </TD></TR><TR><TD>
\u </TD><TD> begin underline </TD></TR><TR><TD>
\U </TD><TD> stop underline </TD></TR><TR><TD>
\o </TD><TD> begin overline </TD></TR><TR><TD>
\O </TD><TD> stop overline </TD></TR><TR><TD>
\Fk </TD><TD> enable kerning </TD></TR><TR><TD>
\FK </TD><TD> disable kerning </TD></TR><TR><TD>
\Fl </TD><TD> enable ligatures </TD></TR><TR><TD>
\FL </TD><TD> disable ligatures </TD></TR><TR><TD>
\m{n} </TD><TD> mark current position as n </TD></TR><TR><TD>
\M{n} </TD><TD> return to saved position n </TD></TR><TR><TD>
\dl </TD><TD> LtoR substring direction </TD></TR><TR><TD>
\dr </TD><TD> RtoL substring direction </TD></TR><TR><TD>
\dL </TD><TD> LtoR text advancing </TD></TR><TR><TD>
\dR </TD><TD> RtoL text advancing </TD></TR><TR><TD>
\${x} </TD><TD> macro x </TD></TR><TR><TD>
\x </TD><TD> switch to Symbol font (same as \f{Symbol}) </TD></TR><TR><TD>
\+ </TD><TD> increase size (same as \z{1.19} ; 1.19 = sqrt(sqrt(2))) </TD></TR><TR><TD>
\- </TD><TD> decrease size (same as \z{0.84} ; 0.84 = 1/sqrt(sqrt(2))) </TD></TR><TR><TD>
\s </TD><TD> begin subscripting (same as \v{-0.4}\z{0.71}) </TD></TR><TR><TD>
\S </TD><TD> begin superscripting (same as \v{0.6}\z{0.71}) </TD></TR><TR><TD>
\T{xx xy yx yy} </TD><TD> same as \t{}\t{xx xy yx yy} </TD></TR><TR><TD>
\Z{x} </TD><TD> absolute zoom x times (same as \z{}\z{x}) </TD></TR><TR><TD>
\q </TD><TD> make font oblique (same as \l{0.25}) </TD></TR><TR><TD>
\Q </TD><TD> undo oblique (same as \l{-0.25}) </TD></TR><TR><TD>
\N </TD><TD> return to normal style (same as \v{}\t{}) </TD></TR><TR><TD>
\\ </TD><TD> print \ </TD></TR><TR><TD>
\n </TD><TD> switch to font number n (0-9) (deprecated) </TD></TR><TR><TD>
\c </TD><TD> begin using upper 128 characters of set (deprecated) </TD></TR><TR><TD>
\C </TD><TD> stop using upper 128 characters of set (deprecated) </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>              
<A NAME="control-codes"></A> 
              Control codes.
      </CAPTION>
</CENTER><BR>
</P>
<P>Example:</P>
<P>F\sX\N(\xe\f{}) =
sin(\xe\f{})\#{b7}e\S-X\N\#{b7}cos(\xe\f{}) </P>
<P>prints roughly
<BLOCKQUOTE><CODE>
<PRE>
                       -x
       F (e) = sin(e)&middot;e  &middot;cos(e)
        x
       
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>using string's initial font and e prints as epsilon from the Symbol font.</P>
<P>NOTE:
Characters from the upper half of the char table can be entered directly
from the keyboard, using appropriate <CODE>xmodmap/xkb</CODE> settings, or
with the help of the font tool ("Tools/Font tool").</P>
<H2><A NAME="device-limitations"></A> <A NAME="ss7.2">7.2</A> <A HREF="#toc7.2">Device-specific limitations</A>
</H2>


<P>Grace can output plots using several device backends. The list of
available devices can be seen (among other stuff) by specifying the
"-version" command line switch.
<UL>
<LI> X11, PostScript, EPS and all raster drivers (PNM/JPEG/PNG)
are full-featured devices</LI>
<LI> PDF driver:
<UL>
<LI> bitmapped text strings are not transparent </LI>
<LI> kerning is not implemented </LI>
</UL>
</LI>
<LI> MIF driver:
the driver is a brand new one and still in beta test
<UL>
<LI> some of patterned fills not implemented </LI>
<LI> bitmapped text strings not implemented </LI>
<LI> kerning is not implemented </LI>
</UL>
</LI>
<LI> SVG driver:
the driver is a brand new one and still in beta test 
<UL>
<LI> patterned fills not implemented </LI>
<LI> bitmapped text strings not implemented </LI>
<LI> kerning is not implemented </LI>
</UL>
</LI>
</UL>
</P>

<H2><A NAME="device-settings"></A> <A NAME="ss7.3">7.3</A> <A HREF="#toc7.3">Device-specific settings</A>
</H2>

<P>Some of the output devices accept several configuration options.
A few options can be passed in one command, separated by commas.</P>

<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Command </TD><TD> Description </TD></TR><TR><TD>
level1 </TD><TD> use only PS Level 1 subset of commands </TD></TR><TR><TD>
level2 </TD><TD> use also PS Level 2 commands if needed </TD></TR><TR><TD>
colorspace:grayscale </TD><TD> set grayscale colorspace </TD></TR><TR><TD>
colorspace:rgb </TD><TD> set RGB colorspace </TD></TR><TR><TD>
colorspace:cmyk </TD><TD> set CMYK colorspace (PS Level2 only) </TD></TR><TR><TD>
docdata:7bit </TD><TD> the document data is 7bit clean </TD></TR><TR><TD>
docdata:8bit </TD><TD> the document data is 8bit clean </TD></TR><TR><TD>
docdata:binary </TD><TD> the document data may be binary </TD></TR><TR><TD>
embedfonts:none </TD><TD> don't embed fonts </TD></TR><TR><TD>
embedfonts:but13 </TD><TD> embed all but the 13 standard fonts </TD></TR><TR><TD>
embedfonts:but35 </TD><TD> embed all but the 35 standard fonts </TD></TR><TR><TD>
embedfonts:all </TD><TD> embed all fonts </TD></TR><TR><TD>
xoffset:<I>x</I> </TD><TD> set page offset in X direction <I>x</I> pp </TD></TR><TR><TD>
yoffset:<I>y</I> </TD><TD> set page offset in Y direction <I>y</I> pp </TD></TR><TR><TD>
mediafeed:auto </TD><TD> default input tray </TD></TR><TR><TD>
mediafeed:match </TD><TD> select input with media matching page dimensions </TD></TR><TR><TD>
mediafeed:manual </TD><TD> manual media feed </TD></TR><TR><TD>
hwresolution:on </TD><TD> set hardware resolution </TD></TR><TR><TD>
hwresolution:off </TD><TD> do not set hardware resolution </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>          PostScript driver options
      </CAPTION>
</CENTER><BR>
</P>

<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Command </TD><TD> Description </TD></TR><TR><TD>
level1 </TD><TD> use only PS Level 1 subset of commands </TD></TR><TR><TD>
level2 </TD><TD> use also PS Level 2 commands if needed </TD></TR><TR><TD>
colorspace:grayscale </TD><TD> set grayscale colorspace </TD></TR><TR><TD>
colorspace:rgb </TD><TD> set RGB colorspace </TD></TR><TR><TD>
colorspace:cmyk </TD><TD> set CMYK colorspace (PS Level2 only) </TD></TR><TR><TD>
docdata:7bit </TD><TD> the document data is 7bit clean </TD></TR><TR><TD>
docdata:8bit </TD><TD> the document data is 8bit clean </TD></TR><TR><TD>
docdata:binary </TD><TD> the document data may be binary </TD></TR><TR><TD>
embedfonts:none </TD><TD> don't embed fonts </TD></TR><TR><TD>
embedfonts:but13 </TD><TD> embed all but the 13 standard fonts </TD></TR><TR><TD>
embedfonts:but35 </TD><TD> embed all but the 35 standard fonts </TD></TR><TR><TD>
embedfonts:all </TD><TD> embed all fonts </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>          EPS driver options
      </CAPTION>
</CENTER><BR>
</P>

<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Command </TD><TD> Description </TD></TR><TR><TD>
compatibility:PDF-1.3 </TD><TD> set compatibility mode to PDF-1.3 (Acrobat4) </TD></TR><TR><TD>
compatibility:PDF-1.4 </TD><TD> set compatibility mode to PDF-1.4 (Acrobat5) </TD></TR><TR><TD>
compatibility:PDF-1.5 </TD><TD> set compatibility mode to PDF-1.5 (Acrobat6) </TD></TR><TR><TD>
compression:value </TD><TD> set compression level (0 - 9) </TD></TR><TR><TD>
fpprecision:value </TD><TD> set floating point precision (4 - 6) </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>          PDF driver options
      </CAPTION>
</CENTER><BR>
</P>

<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Command </TD><TD> Description </TD></TR><TR><TD>
format:pbm </TD><TD> output in PBM format </TD></TR><TR><TD>
format:pgm </TD><TD> output in PGM format </TD></TR><TR><TD>
format:ppm </TD><TD> output in PPM format </TD></TR><TR><TD>
rawbits:on </TD><TD> "rawbits" (binary) output </TD></TR><TR><TD>
rawbits:off </TD><TD> ASCII output </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>          PNM driver options
      </CAPTION>
</CENTER><BR>
</P>

<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Command </TD><TD> Description </TD></TR><TR><TD>
grayscale </TD><TD> set grayscale output </TD></TR><TR><TD>
color </TD><TD> set color output </TD></TR><TR><TD>
optimize:on/off </TD><TD> enable/disable optimization </TD></TR><TR><TD>
quality:value </TD><TD> set compression quality (0 - 100) </TD></TR><TR><TD>
smoothing:value </TD><TD> set smoothing (0 - 100) </TD></TR><TR><TD>
baseline:on/off </TD><TD> do/don't force baseline output </TD></TR><TR><TD>
progressive:on/off </TD><TD> do/don't output in progressive format </TD></TR><TR><TD>
dct:ifast </TD><TD> use fast integer DCT method </TD></TR><TR><TD>
dct:islow </TD><TD> use slow integer DCT method </TD></TR><TR><TD>
dct:float </TD><TD> use floating-point DCT method </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>          JPEG driver options
      </CAPTION>
</CENTER><BR>
</P>

<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
Command </TD><TD> Description </TD></TR><TR><TD>
interlaced:on </TD><TD> make interlaced image </TD></TR><TR><TD>
interlaced:off </TD><TD> don't make interlaced image </TD></TR><TR><TD>
transparent:on </TD><TD> produce transparent image </TD></TR><TR><TD>
transparent:off </TD><TD> don't produce transparent image </TD></TR><TR><TD>
compression:value </TD><TD> set compression level (0 - 9) </TD></TR><TR><TD>
</TD></TR></TABLE>
<CAPTION>          PNG driver options
      </CAPTION>
</CENTER><BR>
</P>
<H2><A NAME="dates"></A> <A NAME="ss7.4">7.4</A> <A HREF="#toc7.4">Dates in Grace </A>
</H2>

<P>We use two calendars in Grace: the one that was established in
532 by Denys and lasted until 1582, and the one that was created
by Luigi Lilio (Alyosius Lilius) and Christoph Klau
(Christophorus Clavius) for pope Gregorius XIII. Both use the
same months (they were introduced under emperor Augustus, a few
years after Julian calendar introduction, both Julius and
Augustus were honored by a month being named after each one).</P>
<P>The leap years occurred regularly in Denys's calendar: once
every four years, there is no year 0 in this calendar (the leap
year -1 was just before year 1). This calendar was not compliant
with earth motion and the dates were slowly shifting with regard
to astronomical events.</P>
<P>This was corrected in 1582 by introducing Gregorian
calendar. First a ten days shift was introduced to reset correct
dates (Thursday October the 4th was followed by Friday October
the 15th). The rules for leap years were also changed: three
leap years are removed every four centuries. These years are
those that are multiple of 100 but not multiple of 400: 1700,
1800, and 1900 were not leap years, but 1600 and 2000 were leap
years.</P>
<P>We still use Gregorian calendar today, but we now have several
time scales for increased accuracy. The International Atomic
Time (TAI) is a linear scale: the best scale to use for
scientific reference. The Coordinated Universal Time (UTC, often
confused with Greenwich Mean Time) is a legal time that is
almost synchronized with earth motion. However, since the earth
is slightly slowing down, leap seconds are introduced from time
to time in UTC (about one second every 18 months). UTC is not a
continuous scale ! When a leap second is introduced by
International Earth Rotation Service, this is published in
advance and the legal time sequence is as follows: 23:59:59
followed one second later by 23:59:60 followed one second later
by 00:00:00. At the time of this writing (1999-01-05) the
difference between TAI and UTC was 32 seconds, and the last leap
second was introduced in 1998-12-31.</P>
<P>These calendars allow to represent any date from the mist of the
past to the fog of the future, but they are not convenient for
computation. Another time scale is possible: counting only the
days from a reference. Such a time scale was introduced by
Joseph-Juste Scaliger (Josephus Justus Scaliger) in 1583. He
decided to use "-4713-01-01T12:00:00" as a reference date
because it was at the same time a Monday, first of January of a
leap year, there was an exact number of 19 years Meton cycle
between this date and year 1 (for Easter computation), and it
was at the beginning of a 15 years <I>Roman indiction</I>
cycle. The day number counted from this reference is
traditionally called <I>Julian day</I>, but it has really
nothing to do with the Julian calendar.</P>
<P>Grace stores dates internally as reals numbers counted from a
reference date. The default reference date is the one chosen by
Scaliger, it is a classical reference for astronomical
events. It can modified for a single session using the 
<A HREF="#preferences">Edit-&gt;Preferences</A> popup of the GUI. If
you often work with a specific reference date you can set it for
every sessions with a REFERENCE DATE command in your
configuration file (see 
<A HREF="#default-template">Default template</A>).</P>
<P>The following date formats are supported (hour, minutes and
seconds are always optional):</P>
<P>
<OL>
<LI>iso8601  : 1999-12-31T23:59:59.999</LI>
<LI>european : 31/12/1999 23:59:59.999 or 31/12/99 23:59:59.999</LI>
<LI>us       : 12/31/1999 23:59:59.999 or 12/31/99 23:59:59.999</LI>
<LI>Julian   : 123456.789</LI>
</OL>
</P>
<P>One should be aware that Grace does not allow to put a space in
one data column as spaces are used to separate fields. You
should always use another separator (:/.- or better T) between
date and time in data files. The GUI, the batch language and the
command line flags do not have this limitation, you can use
spaces there without any problem. The T separator comes from the
ISO8601 standard. Grace support its use also in european and us
formats.</P>
<P>You can also provide a hint about the format ("ISO8601",
"european", "us") using the -datehint command line flag or the
<A HREF="#preferences">Edit->Preferences</A> popup of the GUI.
The formats are tried in the following order: first the hint
given by the user, then iso, european and us (there is no
ambiguity between calendar formats and numerical formats and
therefore no order is specified for them). The separators
between various fields can be any characters in the set: " :/.-T"
(one or more spaces act as one separator, other characters can
not be repeated, the T separator is allowed only between date and time,
mainly for iso8601), so the string "1999-12 31:23/59" is allowed
(but not recommended).  The '-' character is used both as a
separator (it is traditionally used in iso8601 format) and as
the unary minus (for dates in the far past or for numerical
dates). By default years are left untouched, so 99 is a date far
away in the past. This behavior can be changed with the 
<A HREF="#preferences">Edit->preferences</A> popup, or with the
<CODE>DATE WRAP on</CODE> and <CODE>DATE WRAP YEAR year</CODE>
commands. Suppose for example that the wrap year is chosen as
1950, if the year is between 0 and 99 and is written with two or
less digits, it is mapped to the present era as follows:</P>
<P>range [00 ; 49] is mapped to [2000 ; 2049]</P>
<P>range [50 ; 99] is mapped to [1950 ; 1999]</P>
<P>with a wrap year set to 1970, the mapping would have been:</P>
<P>range [00 ; 69] is mapped to [2000 ; 2069]</P>
<P>range [70 ; 99] is mapped to [1970 ; 1999]</P>
<P>this is reasonably Y2K compliant and is consistent with current
use.  Specifying year 1 is still possible using more than two
digits as follows: "0001-03-04" is unambiguously March the 4th,
year 1. The inverse transform is applied for dates written by
Grace, for example as tick labels. Using two digits only for
years is not recommended, we introduce a <I>wrap year +
100</I> bug here so this feature should be removed at some
point in the future ...</P>
<P>The date scanner can be used either for Denys's and Gregorian
calendars. Inexistent dates are detected, they include year 0,
dates between 1582-10-05 and 1582-10-14, February 29th of non
leap years, months below 1 or above 12, ...  the scanner does
not take into account leap seconds: you can think it works only
in International Atomic Time (TAI) and not in Coordinated
Unified Time (UTC). If you find yourself in a situation were you
need UTC, a very precise scale, and should take into account
leap seconds ... you should convert your data yourself (for
example using International Atomic Time). But if you bother with
that you probably already know what to do.</P>
<H2><A NAME="ss7.5">7.5</A> <A HREF="#toc7.5">Xmgr to Grace migration guide</A>
</H2>


<P>This is a very brief guide describing problems and workarounds for
reading in project files saved with Xmgr. You should read the docs or
just play with Grace to test new features and controls.</P>
<P>
<OL>
<LI> Grace must be explicitly told the version number of the software
used to create a file. You can manually put "@version VERSIONID"
string at the beginning of the file. The VERSIONID is built as
MAJOR_REV*10000 + MINOR_REV*100 + PATCHLEVEL; so 40101 corresponds
to Xmgr-4.1.1. Projects saved with Xmgr-4.1.2 do NOT need the above,
since they already have the version string in them. If you have no
idea what version of Xmgr your file was created with, try some.
In most cases, 40102 would do the trick.</LI>
<LI> The above relates to the ASCII projects only. The old binary
projects (saved with xmgr-4.0.*) are not automatically converted
anymore. You can use the "grconvert" utility that comes with
Grace to convert such files to Xmgr-4.1.2-style projects. </LI>
<LI> Grace is WYSIWYG. Xmgr was not. Many changes required to achieve the
WYSIWYG'ness led to the situation when graphs with objects carefully
aligned under Xmgr may not look so under Grace. Grace tries its best
to compensate for the differences, but sometimes you may have to
adjust such graphs manually.</LI>
<LI> A lot of symbol types (all except *real* symbols) are removed.
"Location *" types can be replaced (with much higher comfort) by
A(nnotating)values. "Impulse *", "Histogram *" and "Stair steps *"
effects can be achieved using the connecting line parameters (Type,
Drop lines). "Dot" symbol is removed as well; use the filled circle
symbol of the zero size with no outline to get the same effect.</LI>
<LI> Default page layout switched from free (allowing to resize canvas
with mouse) to fixed. For the old behavior, put "PAGE LAYOUT FREE"
in the Grace resource file or use the "-free" command line switch.
<B>The use of the "free" page layout is in general deprecated,
though.</B></LI>
<LI> System (shell) variables GR_* renamed to GRACE_*</LI>
<LI> Smith plots don't work now. They'll be put back soon.</LI>
</OL>
</P>
</BODY>
</HTML>