Grace is a tool to make two-dimensional plots of scientific data. It runs under various (if not all) flavours of UNIX with X11 and Motif. 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.
Grace is derived from Xmgr (a.k.a. ACE/gr), originally written by Paul Turner.
From version number 4.00, the development was taken over by a team of volunteers under the coordination of Evgeny Stambulchik.
See question Mailing Lists on how to contact the developers.
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.
You can get the newest information about Grace and download the latest version at the Grace home page.
You can fetch it from a mirror site as well. The list of mirror sites can be found at ftp://plasma-gate.weizmann.ac.il/pub/grace/MIRRORS.
Grace is still in the "beta" phase. The current official release is 5.0.2 from March, 1999.
Please refer to the official Grace Home Page. There you can also find the latest version of this FAQ, links to the latest release and to mirror sites closer to you.
Apart from the licensing, the main difference is that Grace is WYSIWYG (What You See Is What You Get). This was achieved through a major rewrite of all the mid-level drawing routines and the use of the device-independent Type 1 font rendering library T1lib written by Rainer Menzner. See question T1lib for more information about T1lib.
For help with changing from Xmgr to Grace see section
Xmgr to Grace migration guide in the
User's Guide (question
User's Guide.
As Grace is still under development, there are currently several features of Xmgr which are not yet implemented in Grace. A full compatibility is desirable except for ``bad'' features of Xmgr.
Among the Xmgr features not (yet) implemented in Grace are:
When the licensing was changed to GPL, Paul wanted to keep the name for his non-public version of Xmgr, so we chose a new name.
Yes. Grace is free in terms of the GNU General Public
License (GPL) (see the file LICENSE which comes with
Grace or the
GNU Home Page for details).
The sources of Grace still contain lots of code from Xmgr by
Paul Turner. For a list of those who contributed to Grace
since then, see the file CHANGES in the Grace
distribution.
Yes. It is written in SGML which means that all the above
versions can easily be created using sgml-tools (see
their
home page). At the Grace home page
(see question
Home Page), all
these versions are available.
Until recently, the FAQ had been maintained by Heiko Selber. There is no "official" maintainer right now. If you'd like to take the job, please let us know.
As of now, Grace is a purely virtual creature living in the net, i.e. there is no printed literature. All relevant literature is currently bundled with Grace. See questions Home Page and User's Guide for details. You can print your own copy of the FAQ, the User's Guide and the Tutorial by converting the DVI files to postscript output.
Yes. It is part of the Grace distribution and usually is
located in $GRACE_HOME/doc/. There are several
versions: the SGML source and HTML, LaTeX, DVI and PS
derived from it. You can read the HTML version from a
running Grace session by clicking on "Help/User
Guide". You need a web browser to read the HTML version
(see also question
Environment Variables). You can always download the newest version
from the Grace homepage (see question
Home Page).
The User's Guide is currently quite incomplete, though.
Yes. There are several tutorials which give detailed
step-by-step information how to achieve various tasks. They
are also part of the Grace distribution. You can find them
in $GRACE_HOME/doc/.
There are tutorials about creating a simple plot, batch plotting, fitting curves, transformations (graphical - simple ones, interpolation, feature extraction, using the command line), using pipes, overlaying graphs, hot links.
You have the following options:
$GRACE_HOME/doc/ along with other files which
may contain useful help for your problem. If you
downloaded the sources, there are even more files in
the main directory of the source tree.
No, there isn't. We feel that a mailing list (see question Mailing Lists) is more appropriate to discuss the topics related to Grace as long the volume of the lists stays low enough.
Yes. Grace has three mailing lists: grace,
grace-announce and grace-dev.
See question Subscription for details on how to subscribe.
The first one, unmoderated, serves for general discussions about Grace. This is the list your message should go to if you have a question about Grace. Currently, the volume of this list is about a dozen messages per week.
If you want to write an email to the list, use the address grace@plasma-gate.weizmann.ac.il. This address is not for subscription or unsubscription.
Virtually all developers and most users of Grace have subscribed to this list. So you can be pretty sure that there will be at least one who can help you.
But: no one likes to read the same questions over and over again. So, please refer to other sources of help (see question Support) before asking something that can be found in the documentation.
Instead of subscribing to the list itself you may wish to subscribe to the digest of the list. The digest is sent once in three days or when its size exceeds 32K.
The moderated grace-announce list is for new version or serious bug fix announcements only (which are automatically relayed to the first mailing list, too). The volume of this list is very low, like once a month or less.
The grace-dev mailing list is for developers. It serves for discussions about the future development or details which are usually not interesting to mere users.
There are mailing list archives available for browsing.
You can subscribe to any of the Grace mailing lists by
sending an email to
<LISTNAME>-request@plasma-gate.weizmann.ac.il with
no subject line and the only word `Subscribe' (without
quotes, of course) in the body of the message.
<LISTNAME> stands for the name of the list you wish
to subscribe to, i.e. grace, grace-digest,
grace-announce or grace-devel
So the respective addresses are:
grace-request@plasma-gate.weizmann.ac.il
grace-digest-request@plasma-gate.weizmann.ac.il
grace-announce-request@plasma-gate.weizmann.ac.il
grace-dev-request@plasma-gate.weizmann.ac.il
To unsubscribe from a list, same instructions apply, with
`Subscribe' being replaced by `Unsubscribe'.
Make sure that what you found really is a bug.
Try to make sure that it is a bug in Grace, and that the failure is not caused by another piece of software.
Consider upgrading to the newest release of Grace (see question Current Release). The development of Grace is currently rather fast, so your bug might already be fixed.
Try to find out if the bug is already known (see question Known Bugs).
OK: You have found a new bug. Use w3todo (question Known Bugs) to report it. Follow the instructions on the page and try to be as precise as possible. It won't be much help if you write ``The program crashes.'' Try to find a simple reproducible case. Mention the version of Grace and the operating system you use. Once you submit the bug report, it will be automatically sent to the mailing list. You will usually be notified when the bug is fixed or if we need more information, so don't forget to give your correct e-mail address.
Yes. You can search and browse the database of known bugs in
Xmgr and Grace at the bug report facility
w3todo
or using the "Help/Comments" menu from within
Grace. The database also keeps track of the status of the
bug (Confirmed, Working on, Testing, Fixed, Closed,
etc.). This is also the place to submit bug reports and
wishes.
You can submit wishes and suggestions just the way you would submit bug reports (see question Known Bugs). Suggestions for improvement are generally very welcome. It may be possible, however, that the developers are busy or that your wish is rejected for some good reason, so it may be necessary to persuade (better convince) them to get at it.
Fine! There are always things to do.
If you are a c programmer, you can almost certainly find something useful to do. Just ask the mailing list. The same applies if you are a technical writer. The documentation will certainly need to be updated, corrected or completed.
Make Grace known to your friends and colleagues. The more users Grace has, the faster it will be improved.
No need to (yet). But if you feel like making a donation, choose any charity organization you like. You wanted to give them some money, anyway, right?
You have the choice: either you compile the sources yourself or you download precompiled binaries. You can get both from the Grace Home Page. Whether binaries for your platforms are available (see question Binaries) depends on whether one of the developers has access to the respective platform and has had time to do it.
It is always a good idea to read the INSTALL file and
the READMEs which come with Grace.
Grace usually compiles out of the box on a regular UNIX machine. You need an ANSI C compiler (gcc is just fine), the X11 libraries, and Motif-1.2 or above (see question Motif).
You also need certain libraries if you want to export special file formats (see question Output Devices).
In order to read/write sets in the netCDF data format, you will also need the NetCDF libraries.
Furthermore, you might use the XPM libraries for the Grace icon from the XPM home page and the FFTW libraries for fast Fourier transformations from the FFTW home page.
If you want to compile your own changes to certain parts
of Grace, you will need a parser generator (yacc or
bison).
Most of these (except Motif and probably T1lib and FFTW) are usually part of a regular Linux distribution but probably not of other UNIXes.
After getting the sources (question
Installation) and ungzipping and untaring
them (use e.g. gzip -dc grace-5.0.1.tar.gz | tar xvf -),
change to the Grace directory and have a look at the files
INSTALL and README.configure.
Type ./configure. This checks for the
availability of libraries and other stuff on your
system. If all went well, two new files, Make.conf
and config.h, are created. In very rare cases you may
want to manually edit them.
Type make. When the compilation is finished, you can
test Grace using make tests. This will give you a
slide show demonstrating some nice features of Grace. Then
install it to the directory $GRACE_HOME/ (see
question
Environment Variables) using make install (probably as root).
Check whether Motif (question Motif) is installed on your system. If it is, look at the file config.log: there is a line like this:
configure:5569: checking for main in -lXm
What comes directly after it? Could be a hint.
Use configure with the special
--with-motif-includes=DIR and
--with-motif-libraries=DIR options.
Motif is a toolkit library for X11. It provides widgets (buttons, boxes, etc) to be used in graphical user interfaces. Graces makes heavy use of Motif. The original OSF Motif (see http://www.osf.org) is not free. You can buy it from several vendors (at approx. $100 for Linux).
There is, however, a free replacement for Motif called LessTif (see http://www.lesstif.org). LessTif is intended to be a 100% compatible replacement for Motif, but is still under development, so don't expect everything to work exactly as it should. For the purposes of Grace, try using the latest version of LessTif (or at least 0.86.9 and above) - if you don't mind that it's a bit slower than commercial versions of Motif and graphical details may be different. Be aware, however, that occasional crashes might occur under certain circumstances. The LessTif people usually receive many bug reports from the Grace developers, so you can expect bugs in LessTif to be fixed rather quickly.
The answer to this question varies:
You will find binaries for several flavours of UNIX and probably a Win32 package at ftp://plasma-gate.weizmann.ac.il/pub/grace/bin/.
Yes, Grace runs on VMS. Just compile it there.
As for Win32 (Windows 95/98/NT) and OS/2, there are ports for these platforms, though they are not "native", i.e. in order to run them, one needs an X server for respective platform.
Both OS/2 and Win32 ports lack some of the functionality (notably, direct printing). A Win32 package should be available at ftp://plasma-gate.weizmann.ac.il/pub/grace/bin/win32/.
A port to OS/2 made by Alexander Mai can be found at http://www.os-2.de/~mai.
There are two ways to invoke Grace. The full-featured
GUI-based version is called xmgrace. A batch-printing
version is called gracebat (see question
Gracebat).
Both are usually located in $GRACE_HOME/bin/.
No. Sorry. Although it would be nice to have such a
function, it is very hard to implement. We can only ask you
to be careful with certain actions and remember to save
often and early (TM).
There are several ways:
Grace reads several X Resources on startup. These resources affect only the appearance of the GUI, not the printed graphs. Please refer to the User's Guide (question User Guide) for details.
This file is in fact a Grace parameter file (question Parameter File) which is read when Grace starts. It can contain anything a parameter file may contain. You can write this file by creating a graph which looks the way you want and then save it to ~/.gracerc. Be aware that this defines the default for one graph only. If you want to set the defaults for more than one graph, you have to define each of them explicitely, even if you want them to look the same.
In the future, there will be still another way to define defaults.
Specifies the directory where the Grace
docs and libs are stored. Default is
/usr/local/grace.
Specifies the browser which is
used to display the Grace HTML help pages. Default is
netscape.
Specifies the editor which is used to
edit sets. Default is vi in an xterm.
The print command.
A flag (0 or 1) and a file name which determine whether a FFT should use ``wisdom'' when using the FFTW libraries.
You can set environment variables using (e.g.):
export GRACE_HOME="/usr/local/grace"
in bash and sh or
setenv GRACE_HOME "/usr/local/grace"
in tcsh and csh.
Quite a few. You can display them with xmgrace -help.
Use two overlaying graphs, one with a scale on the left(bottom), the other one on the right (top). Thus you can achieve the desired effect, but you'll need to pay close attention to which graph is the 'current' graph. This is also how to display a second scale on the top (right) side of the graph.
The support for polar plots is currently being
implemented, so you can expect polar plots to work
soon. The polar coordinates can be selected from the
"Plot/Graph Appearance" menu. Please refer to
the User's Guide (question
User Guide) for details.
Yes, Grace has all these features. Wherever you can type a
text in Grace, e.g. Axis labels, graph title, text from
Plot->Drawing objects, etc., you can use all those
features within the same text. Please refer to the User
Guide (question
User's Guide) for
details.
T1lib is a font rasterer library which permits to use nice Type1 fonts within Grace on all output media. Usually, the newest version of T1lib comes bundled with Grace, so you don't need to take care of it. If you're interested: the author is Rainer Menzner and you can get more info on t1lib at http://www.neuroinformatik.ruhr-uni-bochum.de/ini/PEOPLE/rmz/t1lib.html.
If you asked this question, then you are probably familiar with
the issue of keymap modifying in X. Once you configured the key
mapping (with the use of xmodmap), you can enter the extended
characters from the keyboard in any text input field. If,
in addition, the appropriate for your language font encoding is
anything but ISO Latin1 (used in most Western Europe countries),
you'll have to tell Grace so. See the
next question.
Yes. Starting with version 5.0.1, you can use your own fonts, in addition to the standard 14 fonts which include Times-Roman, Helvetica, Courier, Symbols and Zapf Dingbats and come with Grace, and as a replacement for the default fonts (for the purporse of localization). As well, an alternative encoding scheme can be specified.
Please refer to the User's Guide (question User's Guide) for details.
By default, numbers are saved with eight valid digits. To set your own precision, use the command
DEFAULT SFORMAT formatstring
(e.g. in your .gracerc, see question
Customization) with formatstring being in the
printf(3) format.
Set the GRACE_HOME environment variable to your Grace
directory. The help files are in
$GRACE_HOME/doc. See question
Environment Variables on how to
set environment variables.
From Xmgr-4.1.2 on, each project file starts with a string
giving the version number by which is was saved. These
files should cause no problems. You can modify older files
by inserting a version line at the beginning. For example,
@VERSION 40102 stands for version 4.1.2.
In Xmgr-4.1.0, support for the binary file format (the
former default one) was dropped. You must use the
grconvert utility supplied with the Grace
distribution in order to convert the files. This can
easily be achieved defining an input filter like in the
gracerc sample file which comes with Grace.
Yes. You can use your favorite compression program (e.g. `gzip') as input or output filter so that files on disk are automagically (de)compressed. Just add the lines
DEFINE IFILTER "gzip -dc %s" PATTERN "*.gz"
and
DEFINE OFILTER "gzip - > %s" PATTERN "*.gz"
into your personal grace init file. Then, everytime you
specify a file name that ends with .gz, gzip is used
as input and output filters. You can use this mechanism to
do other things, e.g. reading and storing files into a
database.
Well, not yet. The import of GIF files will be implemented in a future release.
Postscript (for printing) and EPS (encapsulated postscript; for the inclusion of graphics into e.g. LaTeX documents) are implemented by default.
In order to produce GIF (and GD) output you need the
GD-1.3 library of Thomas Boutell. It is available at
the GD home page. Read the file
README.GIF for details
The support for the PNM (PBM/PGM/PPM) format (both ASCII and rawbits) depends on GD, too.
For PDF output, you need pdflib-0.6. The PDFlib
distribution is available at
the PDFlib home page. Read the
file README.PDF before trying to compile pdflib.
You can get various other formats using netpbm and pstoedit.
One can use pstoedit (available at several places,
e.g.
ftp://ftp.x.org/contrib/applications/pstoedit/) to
convert PS to a lot of other vector formats: MIF, CGM,
xfig's, tgif's, Windoze and OS/2 metafiles,... even Java
applets!
Bitmaps: Using PNM device + the netpbm utils
(available at e.g.
ftp://ftp.x.org/contrib/utilities/ one can get
JPEG, TIFF, G3, BMP, PCX,... (conversion can be done on
the fly with appropriate filter definitions).
Make sure you added a valid @VERSION versionid line to the
beginning of the file.
This can be done using the "Plot/Plot appearance" popup.
This changes the background of the entire canvas, not only the background of graphs.
A set is a collection of points with x and y coordinates and optional dx, dy (error bars) or other parameters, e.g. a comment.
A graph consists of a graph frame, axes, a title, a number of sets and additional objects like strings, lines, boxes and ellipses.
A project is a file which contains all information necessary to restore a Graph created by Grace.
A parameter file contains informations about settings. Every
batch command of Grace is a valid line in a parameter
file. A parameter file is essentially a project file without
sets in a slightly different format (i.e. without leading
@s).
You can read in several kinds of files where data is arranged in columns separated by spaces or tabs.
Files which are not in simple x y format must have a line
@TYPE xytype before the actual data, where xytype
stands for the set type. Refer to the User's Guide (question
User's Guide) for details.
Alternatively, the file format can be set with a command
line switch.
For example, if you have several sets with the same x values and different y values, you can read them in using:
@TYPE NXY
# then data in the form:
X Y1 Y2 Y3 Y4 ...
The option Read Block Data can be used to read in files
where the values are organized in columns (up to 30). You
can interactively select the type of set to be created and
which columns should be used. Refer to the User's Guide
(question
User's Guide) for details.
A named pipe is a pseudo file to which one application writes data which another one reads from it.
Applications like measurement programs can write data to a pipe and make it thus available to Grace which reads from the pipe. So Grace can serve as data displayer for otherwise non-graphical programs.
Refer to the User's Guide (question User's Guide) or the tutorials (question Tutorials) for further information.
One example for using pipes is included in the `make
tests' slide show.
gracebat is simply a copy of Grace named gracebat
or a symbolic link from gracebat to Grace. In the case
of the symbolic link:
ln -s xmgrace gracebat
done wherever the Grace binary is located will do the trick
(rehash or logout and login to make sure that gracebat
shows up in your path). Executing gracebat with no
command line parameters or data files will produce a
hardcopy on the default printer.
Currently, you can't.
The ISO8601 date format is currently being implemented into Grace and should appear soon.
Please use an external program to convert the data into the Julian Date format.
The Julian Date, not to be confused with the Julian calendar, is a format to represent the time in a single number. Julian Date 0 is a day way in the past, namely the 1st January 4713 before Christ (don't ask me why). The following days are numbered sequentially, each day starting at noon.
This numbering scheme is in wide use, especially in astronomy, and is used for the internal representation of dates in Grace.
Look at the files jul2greg.c and greg2jul.c in
$GRACE_HOME/auxiliary/.
It is the Levenberg-Marquardt algorithm, based on LMDIF from MINPACK, with some modifications.
Yes. No warranty, of course. But as far as the treatment of dates as data is concerned, years always have 4 digits. So `98' is the year Trajan became Emperor of Rome, not 1998.
Concerning an overflow of the system clock: being UNIX
software, Grace uses a variable type called time_t
(count of seconds since New Year's Day 1970) to represent
time internally. On a 32-bit OS, this counter will overflow in early
2038, or (depending on implementation) in the next century, and not
2000. By that time, for sure, everyone will be running a 64- or
higher- bit operating system, which would overflow in so distant
future, that only cosmologists dare to think of it.
See also http://plasma-gate.weizmann.ac.il/Grace/y2k.html.
No. Not yet, I should say. Be patient. It may take quite a while to implement it, though.
Among the many features planned to be introduced in the future are 3D plots, a spreadsheet-like frontend for set operations, contour plots and XPM/GIF/JPEG image import and manipulations.
Probably. If you have an idea for improvement, send mail to the mailing list (question Mailing Lists) or post it as a wish to the w3todo web page (see question Known Bugs).
Plotz is a neat web interface to Grace created by Susan Chacko and can be found at http://helix.nih.gov/plotz.html
Use the -maxboxes/-maxellipses/-maxlines/-maxstr command
line options.
The standard set is the regular (x,y) set, but there are others including error bars or descriptive strings. See the User's Guide (question User's Guide) for details.
Select the correct paper size in the Device setup
popup.
You can also try the command psresize from the psutils package in order to resize a postscript file generated by Grace.
By default, the PS driver uses Level 2 features, while your printer may not be PostScript Level 2 compliant. You can force the use of PS Level 1 only features in the PostScript device setup, though output may be not exactly as expected (there will be no pattern fills, for example).
For certain tasks, Grace needs external libraries which are neither provided by Grace nor the operating system. You will need to install these libraries yourself. This applies to Motif (see question Motif), PDF and GIF (see question Output Devices) and probably other libraries.
If this message occurs, then you don't have Motif (the Xm
libraries, see question
Motif)
installed (see the question above), or the linker doesn't
know where it is. In the first case, try downloading
Lesstif. In the second case, you have to tell your linker
where it is. Look at the file /etc/ld.so.conf. It
contains pathnames of the directories where dynamic
libraries are stored. Add (as root) your directory to this
file and run ldconfig -v. Now the libraries
should be in the list.
For some versions of Motif, the ``soname'' (which identifies the version of the library and is stored somewhere in the library) on your computer doesn't match the soname of the library on the computer where your copy of Grace was compiled on. Then you should use a (semi)statically linked version or compile Grace on your computer.
This means that Grace made an incorrect access to an X library. This is most probably not Grace's fault. Probably a not-yet-correctly-implemented LessTif function (see question Motif) caused this behaviour. If you use LessTif, try to get the latest version (see question Motif). If this error persists, report it as a bug (question Bug Reports).
Get the XKeySymDB file from the X11R6 distribution. Put it
somewhere where you can access it and set the XKEYSYMDB
environment variable to
"/place/where/you/put/XKeysymDB". See question
Environment Variables on how
to set environment variables.
This is a known bug of Motif implementation on Solaris 2.5.1 (both Sparc and Intel hardware). Ask your vendor for a patch.
You have probably tried to run Grace without installing it, just after compilation. You got the following message :
scanFontDBase(): Font Database
File not found T1_InitLib(): Fatal error scanning Font
Database File Initialization of t1-library failed!
Grace uses either the GRACE_HOME environment variable
or a compiled in default path to find the font database. If
the variable is not set and you have not installed the
database with make install it cannot find it. If you
want to test Grace before installing it, you should set the
environment variable to the distribution directory (the one
where the file configure lies), this is what the
dotest script does when you run make check. The
easiest thing to do however is to install everything with
make install. See question
Environment Variables on how to set environment
variables.
Lots. Almost every mouseclick in the GUI has an equivalent in the batch language. See the User's Guide (question User's Guide) for details.
Currently not at all. This will be implemented in a later release.
Make a batch file with the following commands:
fit formula "y = a0 + a1 * sin (a2 + x * pi / 180)"
fit with 3 parameters
fit prec 0.05
a0 = 1
a0 constraints off
a1 = 1
a1 constraints off
a2 = 1
a2 constraints off
nonlfit (s0,100)
This assumes that your original curve is in set s0 and that you want to make 100 iterations.
nonlfit() doesn't produce any plots by itself. It only
fits. I.e., at this point, you can use the fitted
values A0, A1, A2...:
Plot a set, e.g.:
activate s3 100
s3.x=s0.x
s3.y= a0 + a1 * sin (a2 + x * pi / 180)
Use for another fit as the initial values, or just ECHO them
(to stdout) with ECHO A0.