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.
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.
Copyright (©) 1991-95 Paul J Turner, Portland, OR
Copyright (©) 1996-99 Grace Development Team
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.
./configure --help
to get list of additional switches specific to Grace./configure <options>
. Just an example:
% ./configure --enable-grace-home=/opt/grace --enable-extra-incpath=/usr/local/include:/opt/include \ --enable-extra-ldpath=/usr/local/lib:/opt/lib --prefix=/usrwould use
/usr/local/include
and
/opt/include
in addition to the default include path
and /usr/local/lib
and /opt/lib
in addition
to the default ld path. As well, all stuff would be put under
the /opt/grace directory and soft links made to
/usr/bin
, /usr/lib
and /usr/include
.
Note: If you change one of the
--enable-extra-incpath
or
--enable-extra-ldpath
options from one run of
configure to another, remember to delete the
config.cache
file!!!
make
If something goes wrong, try to see if the problem has been
described already in the Grace FAQ (in the
doc
directory).
make tests
make install
make links
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 --prefix
option
during the configuration, see above).
Not written yet...
A project file contains all information necessary to restore a plot created by Grace, as well as some of preferences. Each plot is represented on a single page, but may have an unlimited number of graphs.
A graph consists of (every element is optional): a graph frame, axes, a title and a subtitle, a number of sets and additional annotative objects (time stamp string, text strings, lines, boxes and ellipses).
A set is a way of representing numerical data (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).
A dataset is a collection of points with x and y coordinates, up to four optional data values (which, depending on the set type, can be displayed as error bars or like) and one optional character string.
Regions are sections of the 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 occupied by region.
In many cases, when Grace needs to access a file given with a
relative pathname
, it searches for the file along the
following path:
./pathname:./.grace/pathname:~/.grace/pathname:$GRACE_HOME/pathname
Arrange the graphs in a grid rows by cols
Override any parameter file settings
Execute batch_file on start up
Assume data file is block data
Form a set from the current block data set using the current set type from columns given in the argument
Arrange graphs in gcols columns
Read data from descriptor (anonymous pipe) on startup
Set default hardcopy device
Set canvas size fixed to width*height
Use free page layout
Set the current graph number
Set the type of the current graph
No interactive session, just print and quit
Install private colormap
Turn the graph legend on
Set the axis scaling of the current graph to logarithmic
Open the log window
Set the number of columns for block data (default is 30)
Run Grace in monochrome mode (affects the display only)
Assume the answer is yes to all requests - if the operation would overwrite a file, Grace will do so without prompting
Don't use private colormap
No log window, overrides resource setting
In batch mode, do not print
Don't catch signals
Read data from named pipe on startup
Assume data file is in X Y1 Y2 Y3 ... format
Load parameters from parameter_file to the current graph
Interpret string as a parameter setting
Read data from stdin on startup
file Save print output to file
Remove data file after read
Write the results from regression to results_file
Arrange graphs in grows rows
Exchange the color indices for black and white
Save all graphs to save_file
Integer seed for random number generator
Source type of next data file
Set allowed time slice for real time inputs to delay ms
Add timestamp to plot
Set the type of the next data file
Show the program version
Set the viewport for the current graph
Set the working directory
Set the world coordinates for the current graph
This message
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.
Print command. If the variable is defined but is an empty string, "Print to file" will be selected as default.
The editor used for manual editing of dataset values.
The HTML viewer for on-line browsing of help documents
These flags control behavior of the FFTW planner (see README.FFTW for detailed info)
Upon start-up, Grace loads its init file, gracerc
. The file
is searched for in the
magic path; once
found, the rest of the path is ignored. It's recommended that in the
gracerc
file, one doesn't use statements which are part of
a project file - such defaults, if needed, should be set in the
default template.
Whenever a new project is started, Grace loads the default template,
templates/Default.agr
. The file
is searched for in the
magic path; once
found, the rest of the path is ignored. It's recommended that in the
default template, one doesn't use statements which are NOT part of
a project file - such defaults, if needed, should be set in the
gracerc
init file.
The following Grace-specific X resource settings are supported:
It is also possible to customize menus by assigning key accelerators to any item.
The list below describes the menu X resources. For example, in order to make Grace popup the Non-linear curve fitting by pressing Control+F, you would add the following two lines
XMgrace*transformationsMenu.nonLinearFit.acceleratorText: Ctrl+F
XMgrace*transformationsMenu.nonLinearFit.accelerator: Ctrl<Key>f
to your .Xresources
file (the file which is read when an X
session starts; it could be .Xdefaults
, .Xsession
or
some other file - ask your system administrator when in doubt).
-> fileMenu
* open
* save
* saveAs
* describe
-------------
-> readMenu
* sets
* parameters
* blockData
-> writeMenu
* sets
* parameters
-------------
* clearAll
-------------
* print
* deviceSetup
-------------
* workingDirectory
-------------
* exit
-> editMenu
* dataSets
* setOperations
-------------
* arrangeGraphs
* overlayGraphs
* autoscale
-------------
-> regionsMenu
* status
* define
* clear
* reportOn
* hotLinks
-------------
* setLocatorFixedPoint
* clearLocatorFixedPoint
* locatorProps
-------------
* preferences
-> dataMenu
-> dataSetOperationsMenu
* Sort
* reverse
-------------
* dropPoints
* pruneData
* geometricTransforms
-> regionOperationsMenu
* evaluate
* extractPoints
* extractSets
* deletePoints
* killSets
-------------
-> transformationsMenu
* join
* split
* evaluateExpression
* histograms
* fourierTransforms
* regression
* nonLinearFit
* runningAverages
* differences
* seasonalDifferences
* integration
* correlation
* interpolation
* splines
* samplePoints
* digitalFilter
* linearConvolution
* featureExtraction
-> plotMenu
* plotAppearance
* graphAppearance
* setAppearance
* axisProperties
-> viewMenu
() showLocatorBar
() showStatusBar
() showToolBar
-------------
* redraw
-> windowMenu
* commands
* pointTracking
* drawingObjects
* fontTool
* results
-> helpMenu
* onContext
* userGiude
* tutorial
* faq
* changes
* comments
-------------
* licenseTerms
* about
Not written yet... Read the Tutorial.
When the pointer focus is on the canvas (where the graph is drawn), there are some shortcuts to activate several actions. They are:
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.
Double clicking on parts of the canvas will invoke certain actions or raise some popups:
The double clicking actions can be enabled/disabled from the "Edit/Preferences" popup.
Not written yet...
Not written yet...
Not written yet...
Command | Description |
PAGE SIZE xdim ydim | set page dimensions (in pixels) of terminal device (Display) |
DEVICE "devname" PAGE SIZE xdim ydim | set page dimensions (in pixels) of device devname |
DEVICE "devname" DPI dpi | set device's dpi (dots per pixel) |
DEVICE "devname" FONT onoff | enable/disable usage of built-in fonts for device devname |
DEVICE "devname" FONT ANTIALIASING onoff | enable/disable font aliasing for device devname |
DEVICE "devname" OP "options" | set device specific options (see Device-specific settings) |
HARDCOPY DEVICE "devname" | set device devname as current hardcopy device |
|
Not written yet...
Not written yet...
The grace_np library is a set of compiled functions that allows you to launch and drive a Grace subprocess from your C or Fortran application. Functions are provided to start the subprocess, to send it commands or data, to stop it or detach from it.
There is no fortran equivalent for the GracePrintf function, you should format all the data and commands yourself before sending them with GraceCommandF.
The Grace subprocess listen for the commands you send and interpret them as if they were given in a batch file. You can send any command you like (redraw, autoscale, ...). If you want to send data, you should include them in a command like "g0.s0 point 3.5 4.2".
Apart from the fact it monitors the data sent via the anonymous pipe, the Grace subprocess is a normal process. You can interact with it through the GUI. Note that no error can be sent back to the parent process. If your application send erroneous commands, an error popup will be displayed by the subprocess.
If you exit the subprocess while the parent process is still using it, the broken pipe will be detected. An error code will be returned to every further call to the library (but you can still start a new process if you want to manage this situation).
Here is an example use of the library, you will find this program in the distribution.
#include <stdlib.h>
#include <stdio.h>
#include <unistd.h>
#include "grace_np.h"
#ifndef EXIT_SUCCESS
# define EXIT_SUCCESS 0
#endif
#ifndef EXIT_FAILURE
# define EXIT_FAILURE -1
#endif
void my_error_function(const char *msg)
{
fprintf(stderr, "library message : \"%s\"\n", msg);
}
int
main (int argc, char* argv[])
{
int i;
GraceRegisterErrorFunction (my_error_function);
/* Start Grace with a buffer size of 2048 and open the pipe */
if (GraceOpen(2048) == -1) {
fprintf (stderr, "Can't run Grace. \n");
exit (EXIT_FAILURE);
}
/* Send some initialization commands to Grace */
GracePrintf ("world xmax 100");
GracePrintf ("world ymax 10000");
GracePrintf ("xaxis tick major 20");
GracePrintf ("xaxis tick minor 10");
GracePrintf ("yaxis tick major 2000");
GracePrintf ("yaxis tick minor 1000");
GracePrintf ("s0 on");
GracePrintf ("s0 symbol 1");
GracePrintf ("s0 symbol size 0.3");
GracePrintf ("s0 symbol fill pattern 1");
GracePrintf ("s1 on");
GracePrintf ("s1 symbol 1");
GracePrintf ("s1 symbol size 0.3");
GracePrintf ("s1 symbol fill pattern 1");
/* Display sample data */
for (i = 1; i <= 100 && GraceIsOpen(); i++) {
GracePrintf ("g0.s0 point %d, %d", i, i);
GracePrintf ("g0.s1 point %d, %d", i, i * i);
/* Update the Grace display after every ten steps */
if (i % 10 == 0) {
GracePrintf ("redraw");
/* Wait a second, just to simulate some time needed for
calculations. Your real application shouldn't wait. */
sleep (1);
}
}
if (GraceIsOpen()) {
/* Tell Grace to save the data */
GracePrintf ("saveall \"sample.agr\"");
/* Flush the output buffer and close Grace */
GraceClose();
/* We are done */
exit (EXIT_SUCCESS);
} else {
exit (EXIT_FAILURE);
}
}
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 submultiple of one already known, it takes a LONG time (seconds to minutes).
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.
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.
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.
Example:
F\sX\N(\xe\f{}) = sin(\xe\B)\c7\Ce\S-X\N\c7\Ccos(\xe\f{})
prints roughly
-x
F (e) = sin(e)·e ·cos(e)
x
using string's initial font and e prints as epsilon from the Symbol font.
NOTE:
Characters from the upper half of the char table can be entered directly
from the keyboard, using appropriate xmodmap(1)
settings, or
with the help of the font tool ("Window/Font tool").
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.
Some of the output devices accept several configuration options. You can set the options by passing a respective string to the interpreter using the "DEVICE "devname" OP "options"" command (see Device parameters). A few options can be passed in one command, separated by commas.
Command | Description |
grayscale | set grayscale output |
color | set color output |
level1 | use only PS Level 1 subset of commands |
level2 | use also PS Level 2 commands if needed |
xoffset:x | set page offset in X direction x pp |
yoffset:y | set page offset in Y direction y pp |
|
Command | Description |
grayscale | set grayscale output |
color | set color output |
bbox:tight | enable "tight" bounding box |
bbox:page | bounding box coinsides with page dimensions |
|
Command | Description |
binary | set binary output |
binary:on | same |
ascii:off | same |
ascii | set ASCII output |
ascii:on | same |
binary:off | same |
|
Command | Description |
interlaced:on | make interlaced image |
interlaced:off | don't make interlaced image |
transparent:on | produce transparent image |
transparent:off | don't produce transparent image |
|
Command | Description |
format:pbm | output in PBM format |
format:pgm | output in PGM format |
format:ppm | output in PPM format |
rawbits:on | "rawbits" (binary) output |
rawbits:off | ASCII output |
|
Command | Description |
grayscale | set grayscale output |
color | set color output |
optimize:on/off | enable/disable optimization |
quality:value | set compression quality (0 - 100) |
smoothing:value | set smoothing (0 - 100) |
baseline:on/off | do/don't force baseline output |
progressive:on/off | do/don't output in progressive format |
dct:ifast | use fast integer DCT method |
dct:islow | use slow integer DCT method |
dct:float | use floating-point DCT method |
|
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.