Grace FAQ (v0.7)

by the Grace Team 16.10.1999

This document contains Frequently Asked Questions (FAQ) about Grace, a WYSIWYG 2D plotting tool for scientific data.

Contents

1 General Questions 4 1.1 What is Grace? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2 Where can I get Grace? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.3 Where can I get the most recent information about Grace? . . . . . . . . . . . . . . . . . . . 5 1.4 What is the difference between Xmgr and Grace? . . . . . . . . . . . . . . . . . . . . . . . . 5 1.5 Why did you change the name? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.6 Is Grace free? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.7 Who wrote Grace? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.8 Is there a Postscript|LaTeX|HTML|SGML version of this document? . . . . . . . . . . . . . 6 1.9 Who maintains the FAQ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2 Getting Help 6 2.1 Are there any books about Grace? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.2 Is there a User’s Guide available for Grace? . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.3 Is there a Tutorial available for Grace? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.4 Where do I get support for Grace? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.5 Is there a newsgroup devoted to Grace? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.6 Is there a mailing list for Grace? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.7 How do I subscribe to the mailing lists? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3 Providing Help: Finding and Reporting Bugs 8 3.1 I think I found a bug in Grace! How do I report it? . . . . . . . . . . . . . . . . . . . . . . . 8 3.2 Is there a list of known bugs? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.3 The bug report #xxx is marked as "Fixed" in the w3todo, but I checked the last version of

Grace and the bug is still there! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.4 The bug report #xxx I reported is marked as "Ignored" in the w3todo and I even got no reply?! 9 3.5 I have got an idea! How do I report a wish? . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.6 I want to help! How can I contribute to grace? . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.7 How do I submit patches/contributions? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.8 I like Grace! Should I donate anything to its authors? . . . . . . . . . . . . . . . . . . . . . . 9 4 Installation 9

4.1 How do I install Grace? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 4.2 Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4.2.1 Can I compile Grace myself? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.2.2 When I type ’./configure’ I get: “configure: warning: Motif has not been found; build-

ing a GUI-less version” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.2.3 What is Motif (LessTif)? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.2.4 While compiling Grace I get error messages about missing include files. . . . . . . . . 10 4.2.5 ‘configure’ stops telling it can’t find "ar". . . . . . . . . . . . . . . . . . . . . . . . . . 11

4.3 Are there Grace binaries available? For which platforms? . . . . . . . . . . . . . . . . . . . . 11 4.4 Is there a Windows|OS/2|VMS port of Grace? . . . . . . . . . . . . . . . . . . . . . . . . . . 11

5 Basic Concepts 11 5.1 What is a project? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 5.2 What is a parameter file? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 5.3 Which data formats does Grace recognize? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 5.4 What is block data? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 5.5 What is the NXY data type? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 5.6 Where is gracebat? How does batch printing work? . . . . . . . . . . . . . . . . . . . . . . . 12 5.7 What is the Julian Date? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

6 Using Grace 12 6.1 How do I start Grace? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 6.2 Does Grace have an UNDO function? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 6.3 Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

6.3.1 How can I customize the default appearance of Grace? . . . . . . . . . . . . . . . . . 12 6.3.2 Which environment variables does Grace use? . . . . . . . . . . . . . . . . . . . . . . 13 6.3.3 What command line options does Grace recognize? . . . . . . . . . . . . . . . . . . . 13 6.3.4 I work with the 800x600 screen resolution and several popups are too large to fit in

my desktop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 6.3.5 Can one change the colour selecton for the menu, locator, tool and status bars, and all

the popup menues? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6.4 Plotting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6.4.1 I’d like to plot data against an axis on the right (top) and another data set in a different

scale against an axis on the left (bottom) . . . . . . . . . . . . . . . . . . . . . . . . . 13 6.4.2 How do I do polar plots? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

6.5 Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 6.5.1 Can I use different fonts, symbols, font size, or sub/superscripts in Grace? . . . . . . 14 6.5.2 What is T1lib good for? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 6.5.3 How do I produce special characters (Umlauts) with Grace? . . . . . . . . . . . . . . 14 6.5.4 Can I use my own fonts and/or encodings? . . . . . . . . . . . . . . . . . . . . . . . . 14

6.6 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 6.6.1 At which precision is numerical data saved? How can I set the precision? . . . . . . . 14 6.6.2 Grace cannot find help files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 6.6.3 How do I read in project files created by Xmgr or older versions of Grace? . . . . . . 15 6.6.4 I can’t open anymore project files saved with an old version of Xmgr. . . . . . . . . . 15 6.6.5 How do I save disk space? Can I use compressed project files? . . . . . . . . . . . . . 15 6.6.6 Can I import bitmap graphics into Grace? . . . . . . . . . . . . . . . . . . . . . . . . 15 6.6.7 Can I export Grace graphs to GIF|TIFF| PostScript|PDF etc? . . . . . . . . . . . . . 15

6.7 Where have all the region operations gone to? . . . . . . . . . . . . . . . . . . . . . . . . . . 16 6.8 How can I input data in date/time formats? . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 6.9 Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

6.9.1 When I load a project saved with an earlier version of Xmgr (<4.0), symbols of all

(some) sets are drawn in black. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 6.9.2 How do I set the background color of a plot, outside of the graph frame? . . . . . . . 16 6.9.3 How do I use more than 16 colors for objects/lines in grace? . . . . . . . . . . . . . . 16

6.10 How can I use pipes with Grace? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

7 Runtime Problems 17 7.1 When I start Grace I get the message “Can’t find library libXXX.so” or similar. . . . . . . . 17 7.2 I get errors like "X Error of failed request: BadValue (integer parameter out of range for

operation)" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 7.3 Grace crashes with "Oops Got SIGSEV" (on linux) . . . . . . . . . . . . . . . . . . . . . . . 17 7.4 I run Grace and get the following error messages: "Warning: translation table syn-

tax error: Unknown keysym name: osfPageLeft Warning: ... found while parsing ’<Key>osfPageLeft:SWLeftPage()’" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

7.5 I run Grace on a Solaris 2.5.1 box, and when I try to open a file, I can’t read the names of the files (files section of the dialog) because Grace writes ALL the path of each file in the list and there is no horizontal scroll. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

7.6 Grace cannot find font database and initialize the T1 library . . . . . . . . . . . . . . . . . . 18 7.7 When I include an EPS file generated by Grace into my (La)TeX document, the graphic hides

some of the surrounding text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 7.8 Printing to my old PostScript printer produces an error. . . . . . . . . . . . . . . . . . . . . 18 7.9 My decimal tick labels are systematically of the form e.g. 0,5 instead of O.5 (i.e. I get a

comma instead of a dot). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 7.10 Pressing Ctrl and clicking with the left mouse button on the canvas or dialog panels make

Grace crash. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 8 Mathematics 19

8.1 What algorithm is used for non-linear curve fitting? . . . . . . . . . . . . . . . . . . . . . . . 19

9 Command Line Interface 19 9.1 Which non-interactive batch commands does Grace know? . . . . . . . . . . . . . . . . . . . 19 9.2 How can I do feature extraction non-interactively? . . . . . . . . . . . . . . . . . . . . . . . . 19 9.3 How can I use non-linear fits in the batch mode? . . . . . . . . . . . . . . . . . . . . . . . . . 19 9.4 Is it possible to call the command "POINT expr, expr" with more than two values, as needed,

for example, for points in XYDYDY sets? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 9.5 Is it possible to make Grace starting with a completely empty canvas, until the commands are

loaded and executed? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

10 Miscellaneous 20 10.1 Is Grace Year 2000 compliant? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 10.2 Can Grace plot 3d graphs? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 10.3 Which features are planned for the future? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 10.4 Are there things that Grace can’t do? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 10.5 What different kinds of sets can Grace plot? . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 10.6 How do I make a Grace image fit on a given paper size? . . . . . . . . . . . . . . . . . . . . 21

1 General Questions

1.1 What is Grace?

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 2.6 (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.

1.2 Where can I get Grace?

You can get the newest information about Grace and download the latest version at the Grace home page

<http://plasma-gate.weizmann.ac.il/Grace/>.

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>.

1.3 Where can I get the most recent information about Grace?

Please refer to the official Grace Home Page <http://plasma-gate.weizmann.ac.il/Grace/>. There you can also find the latest version of this FAQ, links to the latest release and to mirror sites closer to you.

1.4 What is the difference between Xmgr and Grace?

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 for typesetting. (See question 6.5.2 (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 2.2 (User’s Guide).

As Grace is still under development, there are currently several features of Xmgr which are not yet implemented in Grace (of course, alongside with a lot of new stuff not found in Xmgr). A full compatibility is desirable except for “bad” features of Xmgr.

Among the Xmgr features not (yet) implemented in Grace are:

• X-Y graph flip

• Horizontal and vertical lines as symbols

• Smith plots

• Box plot sets

1.5 Why did you change the name?

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.

1.6 Is Grace free?

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 <http://www.gnu.org> for details).

1.7 Who wrote Grace?

The sources of Grace still contain a significant amount 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.

Some integral parts of Grace are borrowed from other packages, namely libraries which are also available as stand-alone distributions. In alphabetical order:

   • Cephes math library <http://people.ne.mediaone.net/moshier/index.html>

• 6.5.2 (T1lib)

   • Xbae <http://www.lesstif.org/Xbae.html/>

1.8 Is there a Postscript|LaTeX|HTML|SGML version of this document?

Yes. It is written in SGML which means that all the above versions can easily be created using sgml-tools (see their home page <http://www.sgmltools.org/>). At the Grace home page (see question 1.3 (Home Page)), all these versions are available.

1.9 Who maintains the FAQ?

Until recently, the FAQ had been maintained by Heiko Selber <mailto:selber@fhi-berlin.mpg.de>. There is no "official" maintainer right now. If you’d like to take the job, please let us know.

2 Getting Help

2.1 Are there any books about Grace?

As of now, Grace is a purely virtual creature living in the net, i.e. there is no printed literature. All relevant docs are currently bundled with Grace. See questions 1.3 (Home Page) and 2.2 (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.

2.2 Is there a User’s Guide available for Grace?

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 6.3.2 (Environment Variables)). You can always download the newest version from the Grace homepage (see question 1.3 (Home Page)).

The User’s Guide is currently quite incomplete, though.

2.3 Is there a Tutorial available for Grace?

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.

2.4 Where do I get support for Grace?

You have the following options:

• There is a User’s Guide (see question 2.2 (User’s Guide)) which came with Grace on your computer. It is usually located in $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.

• Have a look at the Grace home page (question 1.3 (Home Page)).

• On the Grace mailing list (see question 2.6 (Mailing Lists) for details) you can easily get in contact with users and developers of Grace. However be aware that people here are trying to help in their spare time - so you can’t always expect quick responses.

2.5 Is there a newsgroup devoted to Grace?

No, there isn’t. We feel that a mailing list (see question 2.6 (Mailing Lists)) is more appropriate to discuss the topics related to Grace as long the volume of the lists stays low enough.

2.6 Is there a mailing list for Grace?

Yes. Grace has three mailing lists: grace, grace-announce and grace-dev.

See question 2.7 (Subscription) for details on how to subscribe.

grace 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 2.4 (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.

grace-announce 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.

grace-dev 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 <http://plasma-gate.weizmann.ac.il/Grace/maillists/> available for

browsing.

2.7 How do I subscribe to the mailing lists?

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'.

3 Providing Help: Finding and Reporting Bugs

3.1 I think I found a bug in Grace! How do I report it?

First Make sure that what you found really is a bug.

Second Try to make sure that it is a bug in Grace, and that the failure is not caused by another piece of software.

Third Make sure you are running the latest official release of Grace. The development of Grace is rather fast, so your bug might already be fixed.

Fourth Try to find out if the bug is already known (see question 3.2 (Known Bugs)).

Fifth OK: You have found a new bug. Use w3todo (question 3.2 (Known Bugs)) to report it. Follow the instructions on the page and try to be as precise as possible. It won’t be of much help if you write “The program crashes.” Try to find a simple reproducible case. Mention the version of Grace and where you got the build and the operating system you use. You should submit the system info as provided by “uname -a” (if this utility exists, of course) and the output of “xmgrace -version”. Often the problem is related to some specific data set. Please try hard on reducing this to the minimum which is sufficient of reproducing the bug. If it’s only a few lines of data please submit it together with the other details. Once you submit the bug report, it will be automatically relayed to the mailing list. You will usually be notified when the bug is fixed or if we need more information, so please don’t forget to give your correct e-mail address.

3.2 Is there a list of known bugs?

Yes. You can search and browse the database of known bugs in Xmgr and Grace at the bug report facil-

ity w3todo <http://plasma-gate.weizmann.ac.il/w3todo/index.phtml> 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.

Some bugs and fixes may not appear in w3todo, but are covered on the 2.6 (mailinglists).

3.3 The bug report #xxx is marked as "Fixed" in the w3todo, but I checked the last version of Grace and the bug is still there!

The term "fixed" means the bug is fixed in the current development version, and the next public version will have the fix in it. Reports with fixes incorporated in an existing public version are marked as "Closed".

3.4 The bug report #xxx I reported is marked as "Ignored" in the w3todo and I even got no reply?!

You must have missed something very obvious. Check out how to properly submit a bug report in this document. Most probably your report was incomplete or just redundant to an existing entry. It’s worth checking the log file of the bug report (the "View log" button at the bottom of the report viewing page).

3.5 I have got an idea! How do I report a wish?

You can submit wishes and suggestions just the way you would submit bug reports (see question 3.2 (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.

3.6 I want to help! How can I contribute to grace?

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. Every small contribution is appreciated!

Make Grace known to your friends and colleagues. The more users Grace has, the faster it will be improved.

3.7 How do I submit patches/contributions?

Prepare diffs against the most recent version. Use either unified (-u) or context (-c) diff format. Specify exactly against which version the diff is supposed to work. Finally send them to <fnevgeny@plasma-gate.

weizmann.ac.il>

In case you plan to help this way more than once you should join the 2.6 (developer mailinglist)

3.8 I like Grace! Should I donate anything to its authors?

No need to. But if you feel like making a donation, choose any charity organization you like. You wanted to give them some money, anyway, right? ;-)

4 Installation

4.1 How do I install Grace?

You have the choice: either you compile the sources yourself or you download precompiled binaries. You can get both from the Grace Home Page <http://plasma-gate.weizmann.ac.il/Grace/>. Whether binaries for your platforms are available (see question 4.3 (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 READMEs that accompany the downloading packages of Grace.

4.2 Compilation

4.2.1 Can I compile Grace myself?

Yes! Actually, this is the preferred method of installation. After getting the sources (question 4.1 (Installation)) and ungzipping and untaring them (use e.g. gzip -dc grace-5.0.4.tar.gz | tar xvf -), proceed according to the relevant section of the 2.2 (User’s Guide), which covers the compilation process.

4.2.2 When I type ’./configure’ I get: “configure: warning: Motif has not been found; building a GUI-less version”

Check whether Motif (question 4.2.3 (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.

4.2.3 What is Motif (LessTif)?

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% source 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 (at least 0.89.0 and above) - if you don’t mind that it might be 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 might hope that bugs in LessTif will be fixed rather quickly. In addition to the source compatibility it may work with binaries prepared for real Motif (binary compatibility). This is not guaranteed at all and you also have to install the correct version, i.e. compatible to either Motif 1.2 or 2.0. Most Lesstif binary packages ship only with the 1.2 version, so you might have to build the 2.0 version yourself. If you want to build Grace from its sources you only need the Motif 1.2 compatible version.

4.2.4 While compiling Grace I get error messages about missing include files.

The answer to this question varies:

• The include files are there but in a non-standard place. Check with your local sys admin.

• If the missing files are like Xm/*.h, this means you don’t have Motif development kit installed (or again, you have to tell explicitly to compiler where to look for the header files). This mostly concerns Linux.

4.2.5 ‘configure’ stops telling it can’t find "ar".

"ar" is the library archiver (the program used to create static libraries like libFoo.a). You should have it in your path. Under Solaris, for example, this can be found in /usr/ccs/bin.

4.3 Are there Grace binaries available? For which platforms?

You will find binaries for several flavours of UNIX and probably a Win32 package at <ftp://plasma-gate.

weizmann.ac.il/pub/grace/bin/>.

4.4 Is there a Windows|OS/2|VMS port of Grace?

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 the respective platform.

Both OS/2 and Win32 ports may lack some of the functionality (notably, support for "direct"/native printing; probably you will have to use the Postscript output for printing).

A port to OS/2 made by Alexander Mai <mailto:st002279@hrzpub.tu-darmstadt.de> can be found at

<http://www.tu.darmstadt.de/~st002279/os2>. It requires XFree86.

5 Basic Concepts

5.1 What is a project?

A project is a file which contains all information necessary to restore a Graph created by Grace.

5.2 What is a parameter file?

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).

5.3 Which data formats does Grace recognize?

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 2.2 (User’s Guide)) for details. Alternatively, the file format can be set with a command line switch.

5.4 What is block data?

The option Read Block Data can be used to read in files where the values are organized in columns. You can interactively select the type of set to be created and which columns should be used. Refer to the User’s Guide (question 2.2 (User’s Guide)) for details.

5.5 What is the NXY data type?

Strictly speaking, it’s not a data format. Rather, you may want to use the relevant command line switch to read in a block data file and automatically assign the data columns to sets of the XY type so that the first column of the block data is used as X for all the sets and the rest of the data columns are assigned to Y’s. Refer to the User’s Guide (question 2.2 (User’s Guide)) for details.

5.6 Where is gracebat? How does batch printing work?

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.

5.7 What is the Julian Date?

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. Some further

explanations are given on this page <http://www.magnet.ch/serendipity/hermetic/cal_stud/jdn.htm>.

The convcal utility in $GRACE_HOME/auxiliary/ can be used for about any to Julian date convertion.

6 Using Grace

6.1 How do I start Grace?

There are three ways to invoke Grace. The full-featured GUI-based version is called xmgrace. A batchprinting version is called gracebat (see question 5.6 (Gracebat)). A command-line interface mode is called

grace.

All three of them are usually located in $GRACE_HOME/bin/.

6.2 Does Grace have an UNDO function?

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).

6.3 Settings

6.3.1 How can I customize the default appearance of Grace?

There are several ways: the init files, X Resources, and environment (shell) variables. Please refer to the User’s Guide (question 2.2 (User Guide)) for details.

6.3.2 Which environment variables does Grace use?

There are few, the most important being GRACE_HOME. It specifies the directory where the Grace files (fonts, docs, libs, ...) are stored. Default is /usr/local/grace.

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.

Please refer to the User’s Guide (question 2.2 (User Guide)) for description of all relevant variables.

6.3.3 What command line options does Grace recognize?

Quite a few. You can display them with xmgrace -help.

Or check for the man page xmgrace(1). However it may not always be up-to-date.

6.3.4 I work with the 800x600 screen resolution and several popups are too large to fit in my desktop.

The window sizes are proportional to the font size used which by default is set to be optimal for the resolution most people are using, i.e. 1024x768. For a lower resolution, set font sizes to a smaller value, e.g. put it in your .Xresources (or like) file:

     XMgrace*fontList: -adobe-helvetica-medium-r-normal-*-8-*-*-*-*-*-*-*
     XMgrace*tabFontList: -adobe-helvetica-medium-r-normal-*-8-*-*-*-*-*-*-*

6.3.5 Can one change the colour selecton for the menu, locator, tool and status bars, and all the popup menues?

As with any X application, use the "-bg <colorname> -fg <another_colorname>" command line flags. Or, define the relevant X resources:

     XMgrace*foreground: ...
     XMgrace*background: ...

6.4 Plotting

6.4.1 I’d like to plot data against an axis on the right (top) and another data set in a different scale against an axis on the left (bottom)

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.

6.4.2 How do I do polar plots?

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 2.2 (User Guide)) for details.

6.5 Strings

6.5.1 Can I use different fonts, symbols, font size, or sub/superscripts in Grace?

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 2.2 (User’s Guide)) for details.

6.5.2 What is T1lib good for?

T1lib is a font rastering 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 <mailto:Rainer.Menzner@neuroinformatik.ruhr-uni-bochum.
de> and you can get more info on t1lib at <http://www.neuroinformatik.ruhr-uni-bochum.de/ini/
PEOPLE/rmz/t1lib.html>.

6.5.3 How do I produce special characters (Umlauts) with Grace?

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 6.5.4 (next question).

6.5.4 Can I use my own fonts and/or encodings?

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 2.2 (User’s Guide)) for details.

6.6 Files

6.6.1 At which precision is numerical data saved? How can I set the precision?

By default, numbers are saved with eight valid digits. To set your own precision, use the command

DEFAULT SFORMAT formatstring

in an init resource file (see question 6.3.1 (Customization)) with formatstring being in the printf(3) format.

6.6.2 Grace cannot find help files.

Set the GRACE_HOME environment variable to your Grace directory. The help files are in $GRACE_HOME/doc. See question 6.3.2 (Environment Variables) on how to set environment variables.

6.6.3 How do I read in project files created by Xmgr or older versions of Grace?

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.

6.6.4 I can’t open anymore project files saved with an old version of Xmgr.

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.

6.6.5 How do I save disk space? Can I use compressed project files?

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.

6.6.6 Can I import bitmap graphics into Grace?

Well, not yet. The import of images will be implemented in a future release.

6.6.7 Can I export Grace graphs to GIF|TIFF| PostScript|PDF etc?

PostScript (for printing), EPS (encapsulated PostScript; for the inclusion of graphics into e.g. LaTeX documents) and PNM (PBM/PGM/PPM) are implemented by default.

Additionally, if some extra libraries are installed, listed in the User’s Guide (question 2.2 (User’s Guide)), the JPEG, PNG, and PDF backends will be built as well.

You can get various other formats using netpbm and pstoedit.

Bitmaps: Using the PNM device + the netpbm utils (available at e.g. <ftp://ftp.x.org/contrib/ utilities/> one can get TIFF, GIF, G3, BMP, PCX,... (conversion can be done on the fly with appropriate filter definitions).

Notice that the direct support of the GIF format is impossible due to the copyright policy of Unisys - it’s not a technical problem. In fact it was supported in earlier versions but to avoid any legal problems this feature has been removed.

One can use pstoedit <http://www.geocities.com/SiliconValley/Network/1958/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!

6.7 Where have all the region operations gone to?

Region operations have no meaning by themselves. Regions are restriction conditions applied to data set(s) which a transformation is performed on. For example, to kill data points in a region, use "Evaluate expression", select same source and dest set(s), leave the "formula" field empty, select your region in the "Restriction" menu, check "Negated".

6.8 How can I input data in date/time formats?

You can use several date/time formats in input data files. Make sure, however, that the time fields don’t contain space separators inside, e.g. 1999-12-31-23:59:59.5

Also, you can use an external program to convert the data into the 5.7 (Julian Date) format, like the one (convcal) that is supplied with Grace.

6.9 Colors

6.9.1 When I load a project saved with an earlier version of Xmgr (<4.0), symbols of all (some) sets are drawn in black.

Make sure you added a valid @VERSION versionid line to the beginning of the file.

6.9.2 How do I set the background color of a plot, outside of the graph frame?

This can be done using the "Plot/Plot appearance" popup.

This changes the background of the entire canvas, not only the background of graphs.

6.9.3 How do I use more than 16 colors for objects/lines in grace?

You may edit your Default.agr file in $GRACE_HOME/templates. Just add lines similar to

 @map color 2 to (255, 0, 0), "red"

defining a RGB value and an according name for that color triplet.

6.10 How can I use pipes with Grace?

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 2.2 (User’s Guide)) or the tutorials (question 2.3 (Tutorials)) for further information.

One example for using pipes is included in the `make tests' slide show.

7 Runtime Problems

7.1 When I start Grace I get the message “Can’t find library libXXX.so” or similar.

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, PDF (see question 6.6.7 (Output Devices)) and probably other libraries. If the message is exactly Can't find library libXm.so (usually this happens on Linux systems ...) then you don’t have Motif (the Xm libraries) installed (see question 4.2.3 (Motif)), 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 this (may be a platform-specific task). On Linux 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. If you’re not root you may try to adjust the environment variable LD_LIBRARY_PATH to include the required pathname.

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.

7.2 I get errors like "X Error of failed request: BadValue (integer parameter out of range for operation)"

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 4.2.3 (Motif)) caused this behaviour. If you use LessTif, try to get the latest version (see question 4.2.3 (Motif)). If this error persists, report it as a bug (question 3.1 (Bug Reports)).

7.3 Grace crashes with "Oops Got SIGSEV" (on linux)

Detect whether you are using a version linked against Lesstif instead of 4.2.3 (Motif). "xmgrace -version" and "ldd xmgrace" are useful commands for this purpose.

If you are using Lesstif, read the according FAQ 4.2.3 (Motif) else report it as a bug (3.1 (Bug Reports)).

7.4 I run Grace and get the following error messages: "Warning: translation table syntax error: Unknown keysym name: osfPageLeft Warning: ... found while parsing ’<Key>osfPageLeft:SWLeftPage()’"

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 6.3.2 (Environment Variables) on how to set environment variables.

7.5 I run Grace on a Solaris 2.5.1 box, and when I try to open a file, I can’t read the names of the files (files section of the dialog) because Grace writes ALL the path of each file in the list and there is no horizontal scroll.

This is a known bug of Motif implementation on Solaris 2.5.1 (both Sparc and Intel hardware). Ask your vendor for a patch.

7.6 Grace cannot find font database and initialize the T1 library

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
     --> Broken or incomplete installation - read the FAQ!

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 6.3.2 (Environment Variables) on how to set environment variables.

If you get this message after installing a prebuilt package, then you have either forgotten to download the platform-independent part of the installation (named like grace-x.y.zz.common.tar.gz) or not set the GRACE_HOME environment variable, see few lines above.

7.7 When I include an EPS file generated by Grace into my (La)TeX document, the graphic hides some of the surrounding text.

LaTeX does not do hard clipping of EPS files unless instructed to do so. Use \includegraphics*{} and NOT \includegraphics{}. If using the epsf package, remember to include the \epsfclipon flag.

The erasing comes about because Grace fills the background with the page size and not the bbox size. The background filling can be disabled from the "Plot/Plot appearance" popup.

7.8 Printing to my old PostScript printer produces an error.

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).

7.9 My decimal tick labels are systematically of the form e.g. 0,5 instead of O.5 (i.e. I get a comma instead of a dot).

You’re using a localized version of OS. You have either LANG or LC_NUMERIC shell variables set, so Grace uses the locale setting to produce numeric labels. Set at least LC_NUMERIC to C or POSIX to disable this behaviour. Notice that there is nothing specific to Grace about locale. Either you want the localization or not. Setting by default LANG to anything but C/POSIX assumes you do.

7.10 Pressing Ctrl and clicking with the left mouse button on the canvas or dialog panels make Grace crash.

This is a known bug in Motif-2.1. Most vendors have fixed it in their ports and/or have a patch ready, but not all, a notable exception being Motif libraries shipped by Red Hat for Linux/Intel. Grace has a workaround for this bug. In order to enable it, add the following lines to the X resources:

     XMgrace*translations: #override\n\
             Ctrl <Btn1Down>: do_nothing()

8 Mathematics

8.1 What algorithm is used for non-linear curve fitting?

It is the Levenberg-Marquardt algorithm, based on LMDIF from MINPACK, with some modifications.

9 Command Line Interface

9.1 Which non-interactive batch commands does Grace know?

Lots. Almost every mouseclick in the GUI has an equivalent in the batch language. See the User’s Guide (question 2.2 (User’s Guide)) for details.

9.2 How can I do feature extraction non-interactively?

Currently not at all. This will be implemented in a later release.

9.3 How can I use non-linear fits in the batch mode?

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.:

            s3 on
            s3 length s0.length
            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.

9.4 Is it possible to call the command "POINT expr, expr" with more than two values, as needed, for example, for points in XYDYDY sets?

No, but you can do something like this (given the set type was properly defined):

            S0 POINT expr, expr
            S0.Y1[S0.LENGTH - 1] = expr
            S0.Y2[S0.LENGTH - 1] = expr
            ...

9.5 Is it possible to make Grace starting with a completely empty canvas, until the commands are loaded and executed?

Start Grace with -pexec "G0 OFF" or load a parameter file with the above command.

10 Miscellaneous

10.1 Is Grace Year 2000 compliant?

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>.

10.2 Can Grace plot 3d graphs?

No. Not yet, I should say. Be patient. It may take quite a while to implement it, though.

10.3 Which features are planned for the future?

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/JPEG/... image import and manipulations.

10.4 Are there things that Grace can’t do?

Probably. If you have an idea for improvement, send mail to the mailing list (question 2.6 (Mailing Lists)) or post it as a wish to the w3todo web page (see question 3.2 (Known Bugs)).

10.5 What different kinds of sets can Grace plot?

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 2.2 (User’s Guide)) for details.

10.6 How do I make a Grace image fit on a given paper size?

Select the correct paper size in the Device setup popup. You can also try the command psresize from the psutils package <http://www.dcs.ed.ac.uk/~ajcd/ psutils/> in order to resize a Postscript file generated by Grace.