A plot in Grace is built in a tree-like manner (reflected 1:1 in the Explorer tool) out of "Quarks". Quark is an object that may have its own presentation properties plus a number of children quarks.

Some quarks impose a coordinate transform; these are "Project", "Frame", and "Graph". Correspondly, there are three types of coordinates in Grace: the viewport, the frame, and the world coordinates. A child position is always defined in the coordinate frame of its parent, so e.g. points of data sets are defined in the graph's world coordinates.

The frame coordinates go from 0 to 1 in both X and Y dimensions of a Frame.

The viewport coordinates correspond to the image of the plot drawn on the canvas (or printed on, say, PS output page). Actually, there is yet another level in the hierarchy of coordinates - the device coordinates. However, you (as a user of Grace) should not worry about the latter. The mapping between the viewport coordinates and the device coordinates is always set in such a way that the origin of the viewport corresponds to the left bottom corner of the device page, the smallest of the device dimensions corresponds to one unit in the viewport coordinates. Oh, and the most important thing about the viewport → device transformation is that it is homotetic, i.e. a square is guaranteed to remain a square, not a rectangle, a circle remains a circle (not an ellipse) etc.

The transformation converting the world coordinates into the frame and further into the viewport ones is determined by both the graph type and the axis scaling.

Frame is a rectangular placeholder for one or more graphs (if there are more than one graph in a frame, such graphs are called overlaid), and optional annotating objects (texts, boxes, etc). As well, Frame is responsible for displaying legend box holding legend entries for all of its children graphs.

A graph may hold (every element is optional) Axes, Sets, and additional annotative objects. The graph type can be any of: XY Graph XY Chart Polar Graph Fixed Graph Pie chart

A set is a way of representing datasets. It consists of a pointer to a dataset plus a collection of parameters describing the visual appearance of the data (like color, line dash pattern etc). The set type can be any of the following:

Set type | # of num. cols | Description @ XY | 2 | An X-Y scatter and/or line plot, plus (optionally) an annotated value @ XYDX | 3 | Same as XY, but with error bars (either one- or two-sided) along X axis @ XYDY | 3 | Same as XYDX, but error bars are along Y axis @ XYDXDX | 4 | Same as XYDX, but left and right error bars are defined separately @ XYDYDY | 4 | Same as XYDXDX, but error bars are along Y axis @ XYDXDY | 4 | Same as XY, but with X and Y error bars (either one- or two-sided) @ XYDXDXDYDY | 6 | Same as XYDXDY, but left/right and upper/lower error bars are defined separately @ BAR | 2 | Same as XY, but vertical bars are used instead of symbols @ BARDY | 3 | Same as BAR, but with error bars (either one- or two-sided) along Y axis @ BARDYDY | 4 | Same as BARDY, but lower and upper error bars are defined separately @ XYHILO | 5 | Hi/Low/Open/Close plot @ XYZ | 3 | Same as XY; makes no sense unless the annotated value is Z @ XYR | 3 | X, Y, Radius. Only allowed in Fixed graphs @ XYSIZE | 3 | Same as XY, but symbol size is variable @ XYCOLOR | 3 | X, Y, color index (of the symbol fill)@ XYCOLPAT | 4 | X, Y, color index, pattern index (currently used for Pie charts only) @ XYVMAP | 4 | Vector map @ XYBOXPLOT | 6 | Box plot (X, median, upper/lower limit, upper/lower whisker) @

Set types

Not all set types, however, can be plotted on any graph type. The following table summarizes it:

Set type | XY Graph | XY Chart | Fixed | Polar | Pie @ XY | + | + | + | + | + @ XYDX | + | - | + | - | - @ XYDY | + | + | + | - | - @ XYDXDX | + | - | + | - | - @ XYDYDY | + | + | + | - | - @ XYDXDY | + | - | + | - | - @ XYDXDXDYDY | + | - | + | - | - @ BAR | + | + | + | - | - @ BARDY | - | + | - | - | - @ BARDYDY | - | + | - | - | - @ XYHILO | + | - | - | - | - @ XYZ | + | - | + | + | - @ XYR | - | - | + | - | - @ XYSIZE | + | + | + | + | - @ XYCOLOR | + | + | + | + | + @ XYCOLPAT | - | - | - | - | + @ XYVMAP | + | - | + | - | - @ XYBOXPLOT | + | - | - | - | - @

Graph/Set type connection

Regions are sections of a graph defined by the interior or exterior of a polygon, or a half plane defined by a line. Regions are used to restrict data transformations to a geometric area covered by region. Regions are auxiliary objects which are not displayed in print outputs.

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

A dataset is an array of points with X and Y coordinates, up to four optional data values (which, depending on the set presentation type, can be displayed as error bars or like) and one optional character string.

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

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

Hotlinks are sources containing varying data. Grace can be instructed a file or a pipe is a hotlink in which case it will provide specific commands to refresh the data on a mouse click (a later version will probably allow automatic refresh).

Grace allows the user to choose between several output devices to produce its graphics. The current list of supported devices is: X11 PostScript (level 1 and level 2), suitable for printing EPS (encapsulated PostScript) Metafile (which is Grace format, used at the moment mostly for debugging purposes) MIF (Maker Interchange Format used by FrameMaker) SVG (Scalable Vector Graphics, a language for describing two-dimensional vector and mixed vector/raster graphics in XML) PDF (depends on extra libraries, see ) PNM (portable anymap file format, depends on extra libraries, see ) JPEG (depends on extra libraries, see ) PNG (depends on extra libraries, see )

Grace can also be instructed to launch conversion programs automatically based on file name. As an example you can produce many vector formats using pstoedit, or almost any image format using the netpbm suite (see also the ).

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

Grace can access external functions present in either system or third-party shared libraries or modules specially compiled for use with it. The term dynamic refers to the possibility Grace has to open the library at run time to find the code of the external function, there is no need to recompile Grace itself (the functions already compiled in Grace are "statically linked").

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

-autoscale x|y|xy

Set autoscale type

Turn off all toolbars

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

Set the hint for dates analysis

Read data from descriptor (anonymous pipe) on startup

Set canvas size fixed to width*height

Use free page layout

No interactive session, just print and quit

Set default hardcopy device

Set options for default hardcopy device

Install private colormap

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

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

Save print output to file

Write results of some data manipulations to results_file

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

Set the type of the next data file

Show the program version

Set the working directory

This message

GRACE_HOME

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.

Invocation string of an HTML viewer for on-line browsing of help documents. Must include "%s" to be replaced with an URL string.

These flags control behavior of the FFTW planner (see for detailed info).

Whenever a new project is started, Grace loads the default template, templates/Default.xgr. The file is searched for in the magic path (see ); once found, the rest of the path is ignored.

The following Grace-specific X resource settings are supported: XMgrace.invertDraw Use GXinvert rather than GXxor for rubber-band lines. If the rubber-banding for zooms and lines, etc. doesn't appear on the canvas, set this resource to yes. XMgrace.toolBar Enables button toolbar XMgrace.statusBar Enables status bar XMgrace.locatorBar Enables locator bar XMgrace.instantUpdate Enables instant update feature of Explorer It is also possible to customize menus by assigning key accelerators to any item. You'll need to derive the item's X resource name from the respective menu label, which is easily done following these rules: All non-alphanumeric characters are skipped Start with lower case; each new word (if any) continues from the capital letter Add the item's type to the end - "Menu" for pulldown menus, "Button" for menu buttons. 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.nonLinearCurveFittingButton.acceleratorText: Ctrl+F XMgrace*transformationsMenu.nonLinearCurveFittingButton.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).

Similarly, it may be desirable to alter default filename patterns of file selection dialogs. The recipe for the dialog's name is like for menu buttons outlined above, with "Button" being replaced with "FSB". E.g., to list all files in the "Open project" dialog ("File/Open..."), set the following resource: XMgrace*openProjectFSB.pattern: *

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

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

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

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

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

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

Open an existing . A popup is displayed that allow to browse the file system.

Save the current work in a project file, using the name that was used for the last open or save. If no name has been set (i.e., if the project has been created from scratch) act as .

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

Abandon all modifications performed on the project since the last save. A confirmation popup is fired to allow the user canceling the operation.

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

Print the project using the current printer settings

Exit from Grace. If some work has been done and not saved, a warning popup will be displayed to allow the user to cancel the operation.

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

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

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

The preferences popup allows you to set miscellaneous properties of your Grace session, such as GUI behavior, cursor type, etc.

This popup gathers all operations that are related to the ordering of data points inside a set or between sets. You can sort according to any coordinate (X, Y, DX, ...) in ascending or descending order, reverse the order of the points, join several sets into one, split one set into several others of equal lengths, or drop a range of points from a set.

The transformations sub-menu gives you access to all data-mining features of Grace.

Given a set of curves in a graph, extract a feature from each curve and use the values of the feature to provide the Y values for a new curve.

Set the rendering properties of the display device (font anti-aliasing and color transformations).

This menu item triggers a redrawing of the canvas.

This menu item causes an update of all GUI controls. Usually, everything is updated automatically, unless one makes modifications by entering commands in the tool.

Not written yet...

The console window displays errors and results of some numerical operations, e.g. nonlinear fit (see ). The window is popped up automatically whenever an error occurs or new result messages appear. This can be altered by checking the "Options/Popup only on errors" option.

The dialog also provides an interface to the command driven version of Grace. Here, commands can be typed in the "Command:" text item and executed when <Return> is pressed. The command will be parsed and executed, and the command line is placed in the history list. Items in the history list can be recalled by using the keyboard arrow buttons. Depending on the state of the "Options/Auto redraw" and "Options/Auto update" checkboxes, each command entered will cause an immediate resync of the canvas and/or the GUI, respectively. For a reference on the Grace command interpreter, see .

Using the dataset statistics popup, you can view statistical properties of datasets (min, max, mean, standard deviation). A horizontal scrollbar at the bottom allows to get the two last properties, they are not displayed by default. Also note that if you find some columns are too narrow to show all significant digits, you can drag the vertical rules using Shift+Button 2.

Click on any element of the interface to get context-sensitive help on it. Only partially implemented at the moment.

Browse the Grace user's guide.

Frequently Asked Questions with answers.

The list of changes during the Grace development.

The whole tree of submenus each loading a sample plot.

Grace licensing terms will be displayed (GPL version 2).

A popup with basic info on the software, including some configuration details. More details can be found when running Grace with the "-version" command line flag.

The file responsible for the font configurations of Grace is fonts/FontDataBase. The first line contains a positive integer specifying the number of fonts declared in that file. All remaining lines contain declarations of one font each, composed out of three fields: Font name. The name will appear in the font selector controls. Also, backend devices that has built-in fonts, will be given the name as a font identifier. Font fall-back. Grace will try to use this in case the real font is not found. Font filename. The file with the font outline data.

Here is the default FontDataBase file: 14 Times-Roman Times-Roman n021003l.pfb Times-Italic Times-Italic n021023l.pfb Times-Bold Times-Bold n021004l.pfb Times-BoldItalic Times-BoldItalic n021024l.pfb Helvetica Helvetica n019003l.pfb Helvetica-Oblique Helvetica-Oblique n019023l.pfb Helvetica-Bold Helvetica-Bold n019004l.pfb Helvetica-BoldOblique Helvetica-BoldOblique n019024l.pfb Courier Courier n022003l.pfb Courier-Oblique Courier-Oblique n022023l.pfb Courier-Bold Courier-Bold n022004l.pfb Courier-BoldOblique Courier-BoldOblique n022024l.pfb Symbol Symbol s050000l.pfb ZapfDingbats ZapfDingbats d050000l.pfb

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

It is possible to use custom fonts with Grace. One mostly needs to use extra fonts for the purpose of localization. For many European languages, the standard fonts supplied with Grace should contain all the characters needed, but encoding may have to be adjusted. This is done by putting a Default.enc file with proper encoding scheme into the fonts/enc directory. Grace comes with a few encoding files in the directory; more can be easily found on the Internet. (If the Default.enc file doesn't exist, the IsoLatin1 encoding will be used). Notice that for fonts having an encoding scheme in themselves (such as the Symbol font, and many nationalized fonts) the default encoding is ignored.

If you do need to use extra fonts, you should modify the FontDataBase file accordingly, obeying its format. However, if you are going to exchange Grace project files with other people who do not have the extra fonts configured, an important thing is to define reasonable fall-back font names.

For example, let us assume I use Hebrew fonts, and the configuration file has lines like these: ... Courier-Hebrew Courier courh___.pfa Courier-Hebrew-Oblique Courier-Oblique courho__.pfa ... My colleague, who lives in Russia, uses Cyrillic fonts with Grace configured like this: ... Cronix-Courier Courier croxc.pfb Cronix-Courier-Oblique Courier-Oblique croxco.pfb ... The font mapping information (Font name <-> Font fall-back) is stored in the Grace project files. Provided that all the localized fonts have English characters in the lower part of the ASCII table unmodified, I can send my friend files (with no Hebrew characters, of course) and be sure they render correctly on his computer.

Thus, with properly configured national fonts, you can make localized annotations for plots intended for internal use of your institution, while being able to exchange files with colleagues from abroad. People who ever tried to do this with MS Office applications should appreciate the flexibility :-).

One must make sure, however, that the external function is of one of supported by Grace types: Grace type | Description @ f_of_i | a function of 1 int variable @ f_of_d | a function of 1 double variable @ f_of_nn | a function of 2 int parameters @ f_of_nd | a function of 1 int parameter and 1 double variable @ f_of_dd | a function of 2 double variables @ f_of_nnd | a function of 2 int parameters and 1 double variable @ f_of_ppd | a function of 2 double parameters and 1 double variable @ f_of_pppd | a function of 3 double parameters and 1 double variable @

Grace types for external functions

The return values of functions are assumed to be of the double type. Note, that there is no difference from the point of view of function prototype between parameters and variables; the difference is in the way Grace treats them - an attempt to use a vector expression as a parameter argument will result in a parse error. Let us consider few examples.

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