« back to all changes in this revision
Viewing changes to doc/UsersGuide.sgml
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Torsten Werner
- Date: 2002-03-19 14:19:58 UTC
- Revision ID: james.westby@ubuntu.com-20020319141958-5gxna6vo1ek3zjml
Tags: upstream-5.1.7
Import upstream version 5.1.7
- files added:
- T1lib
- T1lib/t1lib
- T1lib/type1
- Xbae
- Xbae/Xbae
- ac-tools
- arch
- arch/os2
- arch/vms
- arch/win32
- auxiliary
- cephes
- conf
- doc
- examples
- fonts
- fonts/enc
- fonts/type1
- grace_np
- grconvert
- patches
- scripts
- src
- templates
added
removed
doc/UsersGuide.sgml
1
<!doctype linuxdoc system>
2
3
<!-- This is the User's Guide for Grace -->
4
5
<article>
6
7
<title>Grace User's Guide (for Grace-5.1.7)</title>
8
<author>by the Grace Team</author>
9
<date>16.03.2002</date>
10
<abstract>
11
This document explains the usage of
12
<bf>Grace</bf>, a WYSIWYG 2D plotting tool for numerical data.
13
</abstract>
14
15
<toc>
16
17
<!-- **************************************** -->
18
<sect>Introduction
19
<p>
20
21
<sect1>What is Grace?
22
<p>
23
Grace is a WYSIWYG tool to make two-dimensional plots of numerical
24
data. It runs under various (if not all) flavors of Unix with X11
25
and M*tif (LessTif or Motif). It also runs under VMS, OS/2, and
26
Windows (95/98/NT/2000). Its capabilities are roughly similar to
27
GUI-based programs like Sigmaplot or Microcal Origin plus
28
script-based tools like Gnuplot or Genplot. Its strength lies in the
29
fact that it combines the convenience of a graphical user interface
30
with the power of a scripting language which enables it to do
31
sophisticated calculations or perform automated tasks.
32
33
Grace is derived from Xmgr (a.k.a. ACE/gr), originally written by
34
Paul Turner.
35
36
From version number 4.00, the development was taken over by a
37
team of volunteers under the coordination of Evgeny Stambulchik.
38
You can get the newest information about Grace and download the
39
latest version at the <url
40
url="http://plasma-gate.weizmann.ac.il/Grace/" name="Grace home page">.
41
42
When its copyright was changed to GPL, the name was changed to Grace,
43
which stands for ``GRaphing, Advanced Computation and Exploration of
44
data'' or ``Grace Revamps ACE/gr''. The first version of Grace available
45
is named 5.0.0, while the last public version of Xmgr has the version
46
number 4.1.2.
47
48
Paul still maintains and develops a non-public version of Xmgr for
49
internal use.
50
51
<sect1>Copyright statement
52
<p>
53
54
<tscreen><verb>
55
Copyright (©) 1991-1995 Paul J Turner, Portland, OR
56
Copyright (©) 1996-2002 Grace Development Team
57
58
Maintained by Evgeny Stambulchik
59
60
61
All Rights Reserved
62
63
This program is free software; you can redistribute it and/or modify
64
it under the terms of the GNU General Public License as published by
65
the Free Software Foundation; either version 2 of the License, or
66
(at your option) any later version.
67
68
This program is distributed in the hope that it will be useful,
69
but WITHOUT ANY WARRANTY; without even the implied warranty of
70
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
71
GNU General Public License for more details.
72
73
You should have received a copy of the GNU General Public License
74
along with this program; if not, write to the Free Software
75
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
76
</verb></tscreen>
77
78
<p>
79
For certain libraries required to build Grace
80
(which are therefore even included in a suitable version)
81
there may be different Copyright/License statements. Though their
82
License may by chance match the one used for Grace,
83
the Grace Copyright holders can not influence or change them.
84
85
<p>
86
<table loc="htbp">
87
<tabular ca="ll">
88
<hline>
89
Package | License @
90
<hline>
91
cephes library | Free @
92
T1lib | LGPL @
93
Xbae | BSD-like @
94
Tab Widget | BSD-like @
95
<hline>
96
</tabular>
97
<caption>
98
Licenses
99
</caption>
100
</table>
101
<P>
102
103
104
<!-- **************************************** -->
105
<sect>Installation guide
106
<p>
107
108
<sect1>Installing from sources
109
<p>
110
<enum>
111
<item> Configuration <label id="configuration">
112
<itemize>
113
<item> Requirements.
114
Grace usually compiles out of the box in a regular Unix-like
115
environment. You need an ANSI C compiler (gcc is just fine),
116
the X11R5 or above libraries and headers, and an
117
implementaion of the M*tif API, version 1.2 or above.
118
If you want to compile your own changes to certain parts of
119
Grace, you will need a parser generator (<tt/yacc/ or, better,
120
<tt/bison/).
121
<item> Extra libraries. Some features will be available only if
122
additional libraries are installed. Those are:
123
<itemize>
124
<item> The JPEG backend needs the IJG's
125
(<url name="JPEG library" url="ftp://ftp.uu.net/graphics/jpeg/">),
126
version 6.x.
127
<item> The PNG backend needs
128
the (<url name="libpng" url="http://www.libpng.org/pub/png/libpng.html">)
129
library (version 0.96 or above).
130
<item> The PDF driver requires the PDFlib library of Thomas
131
Merz to be installed, which is available
132
<url name="here" url="http://www.pdflib.com/">, version
133
3.02 or above.
134
<item> If your computer has the FFTW library installed when
135
Grace is compiled, Grace will link itself to this, and
136
drop all conventional FFT's and DFT's. All transforms
137
will be routed through this package. Note that there is
138
then no difference between pushing the "FFT" button and
139
the "DFT" button, except that FFT will complain if the
140
length isn't a power of 2, and DFT will not.
141
142
For more information on this package, see the
143
<url name="FFTW Home page" url="http://www.fftw.org">.
144
In short, this package allows one to do non-power-of-2
145
length FFT's along with the normal ones. It seems to work
146
very efficiently for any set length which factors into 2^a
147
3^b 5^c 7^d for integer a, b, c, d. The great feature here
148
is that set lengths which are powers of 10 (e.g. 1000,
149
10000) and integer multiples of these (500, 2000, 2500,
150
5000, etc.) can be computed with no significant penalty
151
(maybe 20%) over power-of-2 transforms. Very often, real
152
datasets come in these sizes, and not in powers of 2.
153
<item> In order to read/write sets in the NetCDF data format, you
154
will also need the <url name="NetCDF libraries"
155
url="http://unidata.ucar.edu/packages/netcdf/index.html">.
156
</itemize>
157
<item> Decide whether you want to compile in a separate place (thus
158
leaving the source tree pristine). You most probably would
159
want it if compiling Grace for more than one OS and keeping
160
the sources in a central shared (e.g. via NFS) location.
161
If you don't need it, skip the rest of this paragraph and go
162
right to the next step. Otherwise, assuming the sources are
163
in <tt>/usr/local/src/grace-x.y.z</tt> and the compilation
164
will be performed in <tt>/tmp/grace-obj</tt>, do the following:
165
<verb>
166
% mkdir /tmp/grace-obj
167
% cd /tmp/grace-obj
168
% /usr/local/src/grace-x.y.z/ac-tools/shtool mkshadow \
169
/usr/local/src/grace-x.y.z .
170
</verb>
171
<item> The <tt>configure</tt> shell script attempts to guess correct
172
values for various system-dependent variables used during
173
compilation. It uses those values to create <tt>Make.conf</tt> in the
174
top directory of the package. It also create <tt>config.h</tt> file
175
containing system-dependent definitions. Finally, it creates a shell
176
script <tt>config.status</tt> that you can run in the future to
177
recreate the current configuration, a file <tt>config.cache</tt> that
178
saves the results of its tests to speed up reconfiguring, and a file
179
<tt>config.log</tt> containing compiler output (useful mainly for
180
debugging <tt>configure</tt>). If at some point <tt>config.cache</tt>
181
contains results you don't want to keep, you may remove or edit it.
182
<item> Run <tt>./configure --help</tt>
183
to get list of additional switches specific to Grace
184
<item> Run <tt>./configure <options></tt>. Just an example:
185
<verb>
186
% ./configure --enable-grace-home=/opt/grace
187
--with-extra-incpath=/usr/local/include:/opt/include \
188
--with-extra-ldpath=/usr/local/lib:/opt/lib --prefix=/usr
189
</verb>
190
would use <tt>/usr/local/include</tt> and
191
<tt>/opt/include</tt> in addition to the default include path
192
and <tt>/usr/local/lib</tt> and <tt>/opt/lib</tt> in addition
193
to the default ld path. As well, all stuff would be put under
194
the /opt/grace directory and soft links made to
195
<tt>/usr/bin</tt>, <tt>/usr/lib</tt> and <tt>/usr/include</tt>.
196
<p>
197
<bf>Note</bf>: If you change one of the
198
<tt>--with-extra-incpath</tt> or
199
<tt>--with-extra-ldpath</tt> options from one run of
200
configure to another, remember to delete the
201
<tt>config.cache</tt> file!!!
202
</itemize>
203
<item> Compilation
204
<itemize>
205
<item> Issue <tt>make</tt>
206
<p>
207
If something goes wrong, try to see if the problem has been
208
described already in the <bf>Grace FAQ</bf> (in the
209
<tt>doc</tt> directory).
210
</itemize>
211
<item> Testing
212
213
<itemize>
214
<item> <tt>make tests</tt>
215
<p>
216
This will give you a slide show demonstrating some nice
217
features of Grace.
218
</itemize>
219
<item> Installation
220
<itemize>
221
<item> <tt>make install</tt>
222
<item> <tt>make links</tt>
223
<p>
224
The later (optional) step will make soft links from some files
225
under the Grace home directory to the system-wide default
226
locations (can be changed by the <tt>--prefix</tt> option
227
during the configuration, see above).
228
</itemize>
229
</enum>
230
231
<sect1>Binary installation
232
<p>
233
<enum>
234
<item> Getting pre-built packages
235
<item> Installation
236
<item> Running tests
237
</enum>
238
239
<sect1>Alternative packaging schemes (RPM, ...)
240
<p>
241
242
Not written yet...
243
244
245
<!-- **************************************** -->
246
<sect>Getting started
247
<p>
248
249
For a jump-in start, you can browse the demos ("Help/Examples" menu tree).
250
These are ordinary Grace projects, so you can play with them and modify them.
251
Also, read the <url name="Tutorial" url="Tutorial.html">.
252
<p>
253
O.k. Here's a VERY quick introduction:
254
<enum>
255
<item> Start the GUI version: xmgrace (return).
256
<item> Select/check the output medium and canvas size in File/Device
257
Setup.
258
<item> If needed, set the graph size ('Viewport' in
259
Plot/Graph Appearance).
260
<item> Load your data with Data/Import/ASCII. 'Load as': 'Single set' for
261
two-column ASCII data, 'Block data' for multi-column ASCII data.
262
<item> Adjust the scales, axis labels and tick marks in Plot/Axis
263
properties. Acknowledge all changes with 'Apply'.
264
<item> Adjust lines, symbols, legends in Plot/Set appearance.
265
<item> Adjust titles, plot frame and legend display in Plot/Graph
266
Appearance.
267
<item> Data can be manipulated in Data/Transformations. To shift a
268
data set by 20 to the left, e.g., in 'Evaluate Expression'
269
select the same set on the left and the right, and say Formula:
270
y=y-20.
271
As you'll probably notice, Grace can do MUCH more than that.
272
Explore at your leisure.
273
<item> When you like your plot, select File/Print. That's it!
274
</enum>
275
276
<sect1>General concepts
277
<p>
278
279
<sect2>Project files <label id="project-file">
280
<p>
281
282
A project file contains all information necessary to restore a plot
283
created by Grace, as well as some of preferences. Each plot is
284
represented on a single page, but may have an unlimited number of
285
graphs.You create a project file of your current graph with
286
File/Save,Save as.
287
288
<sect2>Parameter files <label id="parameter-file">
289
<p>
290
291
A parameter file contains the detailed settings of your project. It
292
can be used to transfer these settings to a different plot/project.
293
You generate a parameter file with File/Save menu entry selected
294
from the "Plot/Graph appearance popup". You can load the settings
295
contained in a parameter file with File/Open.
296
297
<sect2>Input File formats <label id="files-formats">
298
<p>
299
300
Grace understands several input files formats. The most
301
basic one is ASCII text files containing space and comma
302
separated columns of data. The data fields can be either
303
numeric (Fortran 'd' and 'D' exponent markers are supported)
304
or alphanumeric (with or without quotes). Several calendar
305
date formats are recognized automatically and you can
306
specify your own reference for numeric dates formats. Grace also
307
has a command language (see <ref id="command-interpreter"
308
name="command interpreter">), you can include commands in
309
data files using lines having "@" as their first non-blank
310
character. Depending on configuration, Grace can also read
311
NetCDF files (see <ref id="configuration" name="configuration">).
312
313
<sect2>Graphs <label id="graph">
314
<p>
315
316
A graph consists of (every element is optional): a graph frame, axes,
317
a title and a subtitle, a number of sets and additional annotative
318
objects (time stamp string, text strings, lines, boxes and ellipses).
319
320
The graph type can be any of:<label id="graph-types">
321
<itemize>
322
<item> XY Graph
323
<item> XY Chart
324
<item> Polar Graph
325
<item> Fixed Graph
326
<item> Pie chart
327
</itemize>
328
329
<sect2>Datasets <label id="datasets">
330
<p>
331
332
A dataset is a collection of points with x and y coordinates, up to
333
four optional data values (which, depending on the set type, can be
334
displayed as error bars or like) and one optional character string.
335
336
<sect2>Sets <label id="sets">
337
<p>
338
339
A set is a way of representing datasets. It consists
340
of a pointer to a dataset plus a collection of parameters describing
341
the visual appearance of the data (like color, line dash pattern etc).
342
343
The set type can be any of the following:
344
345
<p>
346
347
<table loc="htbp">
348
<tabular ca="lcp{9cm}">
349
<hline>
350
Set type | # of num. cols | Description @
351
<hline>
352
XY | 2 | An X-Y scatter and/or line plot, plus (optionally) an annotated value @
353
XYDX | 3 | Same as XY, but with error bars (either one- or two-sided) along X axis @
354
XYDY | 3 | Same as XYDX, but error bars are along Y axis @
355
XYDXDX | 4 | Same as XYDX, but left and right error bars are defined separately @
356
XYDYDY | 4 | Same as XYDXDX, but error bars are along Y axis @
357
XYDXDY | 4 | Same as XY, but with X and Y error bars (either one- or two-sided) @
358
XYDXDXDYDY | 6 | Same as XYDXDY, but left/right and upper/lower error bars are defined separately @
359
BAR | 2 | Same as XY, but vertical bars are used instead of symbols @
360
BARDY | 3 | Same as BAR, but with error bars (either one- or two-sided) along Y axis @
361
BARDYDY | 4 | Same as BARDY, but lower and upper error bars are defined separately @
362
XYHILO | 5 | Hi/Low/Open/Close plot @
363
XYZ | 3 | Same as XY; makes no sense unless the annotated value is Z @
364
XYR | 3 | X, Y, Radius. Only allowed in Fixed graphs @
365
XYSIZE | 3 | Same as XY, but symbol size is variable @
366
XYCOLOR | 3 | X, Y, color index (of the symbol fill)@
367
XYCOLPAT | 4 | X, Y, color index, pattern index (currently used for Pie charts only) @
368
XYVMAP | 4 | Vector map @
369
XYBOXPLOT | 6 | Box plot (X, median, upper/lower limit, upper/lower whisker) @
370
<hline>
371
</tabular>
372
<caption>
373
Set types
374
</caption>
375
</table>
376
377
<p>
378
379
Not all set types, however, can be plotted on any graph type. The
380
following table summarizes it:
381
382
<p>
383
384
<table loc="htbp">
385
<tabular ca="lccccc">
386
<hline>
387
Set type | XY Graph | XY Chart | Fixed | Polar | Pie @
388
<hline>
389
XY | + | + | + | + | + @
390
XYDX | + | - | + | - | - @
391
XYDY | + | + | + | - | - @
392
XYDXDX | + | - | + | - | - @
393
XYDYDY | + | + | + | - | - @
394
XYDXDY | + | - | + | - | - @
395
XYDXDXDYDY | + | - | + | - | - @
396
BAR | + | + | + | - | - @
397
BARDY | - | + | - | - | - @
398
BARDYDY | - | + | - | - | - @
399
XYHILO | + | - | - | - | - @
400
XYZ | + | - | + | + | - @
401
XYR | - | - | + | - | - @
402
XYSIZE | + | + | + | + | - @
403
XYCOLOR | + | + | + | + | + @
404
XYCOLPAT | - | - | - | - | + @
405
XYVMAP | + | - | + | - | - @
406
XYBOXPLOT | + | - | - | - | - @
407
<hline>
408
</tabular>
409
<caption>
410
Graph/Set type connection
411
</caption>
412
</table>
413
414
415
<sect2>Regions <label id="regions">
416
<p>
417
418
Regions are sections of the graph defined by the interior or exterior
419
of a polygon, or a half plane defined by a line. Regions are used to
420
restrict data transformations to a geometric area occupied by region.
421
422
<sect2>Real Time Input <label id="RTI">
423
<p>
424
425
Real Time Input refers to the ability Grace has to be
426
fed in real time by an external program. The Grace
427
process spawned by the driver program is a full featured
428
Grace process: the user can interact using the GUI at the
429
same time the program sends data and commands. The process
430
will adapt itself to the incoming data rate.
431
432
<sect2>Hotlinks <label id="hotlinks">
433
<p>
434
435
Hotlinks are sources containing varying data. Grace can be
436
instructed a file or a pipe is a hotlink in which case it
437
will provide specific commands to refresh the data on a
438
mouse click (a later version will probably allow automatic
439
refresh).
440
441
<sect2>Devices<label id="devices">
442
<p>
443
Grace allows the user to choose between several output
444
devices to produce its graphics. The current list of
445
supported devices is:
446
447
<itemize>
448
<item> X11
449
<item> PostScript (level 1 and level 2)
450
<item> EPS (encapsulated PostScript)
451
<item> Metafile (which is Grace format, used at the moment mostly
452
for debugging purposes)
453
<item> MIF (Maker Interchange Format used by FrameMaker)
454
<item> SVG (Scalable Vector Graphics, a language for describing
455
two-dimensional vector and mixed vector/raster graphics
456
in XML)
457
<item> PDF (depends on extra libraries,
458
see <ref name="configuration" id="configuration">)
459
<item> PNM (portable anymap file format)
460
<item> JPEG (depends on extra libraries,
461
see <ref name="configuration" id="configuration">)
462
<item> PNG (depends on extra libraries,
463
see <ref name="configuration" id="configuration">)
464
</itemize>
465
466
<p>
467
Note that Grace no longer supports GIF due to
468
the copyright policy of Unisys. Grace can also be
469
instructed to launch conversion programs automatically
470
based on file name. As an example you can produce MIF
471
(FrameMaker Interchange Format) or Java applets using
472
pstoedit, or almost any image format using the netpbm suite
473
(see the <url name="FAQ" url="FAQ.html">).
474
475
<sect2>Magic path<label id="magic-path">
476
<p>
477
In many cases, when Grace needs to access a file given with a
478
relative <tt>pathname</tt>, it searches for the file along the
479
following path:
480
<tt>./pathname:./.grace/pathname:~/.grace/pathname:$GRACE_HOME/pathname</tt>
481
482
<sect2>Dynamic modules<label id="dynamic-modules">
483
<p>
484
Grace can access external functions present in either system
485
or third-party shared libraries or modules specially compiled
486
for use with it. The term dynamic refers to the possibility
487
Grace has to open the library at run time to find the code of
488
the external function, there is no need to recompile Grace
489
itself (the functions already compiled in Grace are
490
"statically linked").
491
492
<sect2>Coordinate frames <label id="coordinates">
493
494
<p>
495
There are two types of coordinates in Grace: the <bf>world
496
coordinates</bf> and the <bf>viewport coordinates</bf>. Points of
497
data sets are defined in the world coordinates. The viewport
498
coordinates correspond to the image of the plot drawn on the canvas
499
(or printed on, say, PS output page). The transformation converting
500
the world coordinates into the viewport ones is determined by both
501
the graph type and the axis scaling.
502
</p>
503
504
<p>
505
Actually, there is yet another level in the hierarchy of coordinates
506
- the <bf>device coordinates</bf>. However, you (as a user of Grace)
507
should not worry about the latter. The mapping between the viewport
508
coordinates and the device coordinates is always set in such a way
509
that the origin of the viewport corresponds to the left bottom corner
510
of the device page, the smallest of the device dimensions corresponds
511
to one unit in the viewport coordinates. Oh, and the most important
512
thing about the viewport → device transformation is that it is
513
homotetic, i.e. a square is guaranteed to remain a square, not a
514
rectangle, a circle remains a circle (not an ellipse) etc.
515
</p>
516
517
<sect1>Invocation
518
<p>
519
520
<sect2>Operational mode
521
<p>
522
523
With respect to the user interface, there are three modes of
524
operation that Grace can be invoked in. The full-featured GUI-based
525
version is called <tt>xmgrace</tt>. A batch-printing version is
526
called <tt>gracebat</tt>. A command-line interface mode is called
527
<tt>grace</tt>. Usually, a single executable is called in all cases,
528
with two of the three files being (symbolic) links to a "real" one.
529
530
<sect2>Command line options
531
<p>
532
<descrip>
533
<tag> -autoscale <it>x|y|xy</it> </tag>
534
Override any parameter file settings
535
536
<tag> -barebones </tag>
537
Turn off all toolbars
538
539
<tag> -batch <it>batch_file</it> </tag>
540
Execute batch_file on start up
541
542
<tag> -block <it>block_data</it> </tag>
543
Assume data file is block data
544
545
<tag> -bxy <it>x:y:etc.</it> </tag>
546
Form a set from the current block data set using the current set
547
type from columns given in the argument
548
549
<tag> -datehint <it>iso|european|us|days|seconds|nohint</it> </tag>
550
Set the hint for dates analysis
551
552
<tag> -dpipe <it>descriptor</it> </tag>
553
Read data from descriptor (anonymous pipe) on startup
554
555
<tag> -fixed <it>width</it> <it>height</it> </tag>
556
Set canvas size fixed to width*height
557
558
<tag> -free </tag> Use free page layout
559
560
<tag> -graph <it>graph_number</it> </tag>
561
Set the current graph number
562
563
<tag> -graphtype <it>graph_type</it> </tag>
564
Set the type of the current graph
565
566
<tag> -hardcopy </tag>
567
No interactive session, just print and quit
568
569
<tag> -hdevice <it>hardcopy_device_name</it> </tag>
570
Set default hardcopy device
571
572
<tag> -install </tag>
573
Install private colormap
574
575
<tag> -legend <it>load</it> </tag>
576
Turn the graph legend on
577
578
<tag> -log <it>x|y|xy</it> </tag>
579
Set the axis scaling of the current graph to logarithmic
580
581
<tag> -mono </tag>
582
Run Grace in monochrome mode (affects the display only)
583
584
<tag> -netcdf <it>file</it> </tag>
585
Assume data <it>file</it> is in netCDF format. This option is
586
present only if the netCDF support was compiled in
587
588
<tag> -netcdfxy <it>X_var</it> <it>Y_var</it> </tag>
589
If -netcdf was used previously, read from the netCDF file
590
<it>X_var</it> <it>Y_var</it> variables and create a set. If
591
<it>X_var</it> name is "null" then load the index of Y to X.
592
This option is present only if the netCDF support was compiled
593
in
594
595
596
597
<tag> -noask </tag>
598
Assume the answer is yes to all requests - if the operation would
599
overwrite a file, Grace will do so without prompting
600
601
<tag> -noinstall </tag>
602
Don't use private colormap
603
604
<tag> -noprint </tag>
605
In batch mode, do not print
606
607
<tag> -nosigcatch </tag>
608
Don't catch signals
609
610
<tag> -npipe <it>file</it> </tag>
611
Read data from named pipe on startup
612
613
<tag> -nxy <it>nxy_file</it> </tag>
614
Assume data file is in X Y1 Y2 Y3 ... format
615
616
<tag> -param <it>parameter_file</it> </tag>
617
Load parameters from parameter_file to the current graph
618
619
<tag> -pexec <it>parameter_string</it> </tag>
620
Interpret string as a parameter setting
621
622
<tag> -pipe </tag>
623
Read data from stdin on startup
624
625
<tag> -printfile </tag> <it>file</it>
626
Save print output to file
627
628
<tag> -remove </tag>
629
Remove data file after read
630
631
<tag> -results <it>results_file</it> </tag>
632
Write results of some data manipulations to results_file
633
634
<tag> -rvideo </tag>
635
Exchange the color indices for black and white
636
637
<tag> -saveall <it>save_file</it> </tag>
638
Save all graphs to save_file
639
640
<tag> -seed <it>seed_value</it> </tag>
641
Integer seed for random number generator
642
643
<tag> -source <it>disk|pipe</it> </tag>
644
Source type of next data file
645
646
<tag> -timer <it>delay</it> </tag>
647
Set allowed time slice for real time inputs to delay ms
648
649
<tag> -timestamp </tag> Add timestamp to plot
650
651
<tag> -settype <it>xy|xydx|...</it> </tag>
652
Set the type of the next data file
653
654
<tag> -version </tag>
655
Show the program version
656
657
<tag> -viewport <it>xmin ymin xmax ymax</it> </tag>
658
Set the viewport for the current graph
659
660
<tag> -wd <it>directory</it> </tag>
661
Set the working directory
662
663
<tag> -world <it>xmin ymin xmax ymax</it> </tag>
664
Set the world coordinates for the current graph
665
666
<tag> -usage|-help </tag>
667
This message
668
669
</descrip>
670
671
<sect1>Customization
672
<p>
673
<sect2>Environment variables <label id="environment-variables">
674
<p>
675
<itemize>
676
<item> GRACE_HOME
677
<p>
678
Set the location of Grace. This will be where help files,
679
auxiliary programs, and examples are located. If you are unable
680
to find the location of this directory, contact your system
681
administrator.
682
<p>
683
<item> GRACE_PRINT_CMD
684
<p>
685
Print command. If the variable is defined but is an empty
686
string, "Print to file" will be selected as default.
687
<p>
688
<item> GRACE_EDITOR
689
<p>
690
The editor used for manual editing of dataset values.
691
<p>
692
<item> GRACE_HELPVIEWER
693
<p>
694
The HTML viewer for on-line browsing of help documents
695
<p>
696
<item> GRACE_FFTW_WISDOM_FILE and
697
GRACE_FFTW_RAM_WISDOM
698
<p>
699
These flags control behavior of the FFTW planner (see
700
<ref id="fftw-tuning" name="FFTW tuning"> for detailed info)
701
<p>
702
</itemize>
703
704
<sect2>Init file<label id="gracerc">
705
<p>
706
Upon start-up, Grace loads its init file, <tt>gracerc</tt>. The file
707
is searched for in the magic path (see
708
<ref id="magic-path" name="magic path">); once found, the rest of the
709
path is ignored. It's recommended that in the <tt>gracerc</tt> file,
710
one doesn't use statements which are part of a project file - such
711
defaults, if needed, should be set in the default template (see
712
<ref id="default-template" name="default template">).
713
714
<sect2>Default template<label id="default-template">
715
<p>
716
Whenever a new project is started, Grace loads the default template,
717
<tt>templates/Default.agr</tt>. The file is searched for in the magic
718
path (see <ref id="magic-path" name="magic path">); once found, the
719
rest of the path is ignored. It's recommended that in the default
720
template, one doesn't use statements which are NOT part of a project
721
file - such defaults, if needed, should be set in the
722
<tt>gracerc</tt> (see <ref id="gracerc" name="init file">).
723
724
<sect2>X resources
725
<p>
726
727
The following Grace-specific X resource settings are supported:
728
729
<itemize>
730
<item> XMgrace.invertDraw
731
<newline>
732
Use GXinvert rather than GXxor for rubber-band lines.
733
If the rubber-banding for zooms and lines, etc. doesn't
734
appear on the canvas, set this resource to yes.
735
<newline>
736
737
<item> XMgrace.allowDoubleClick
738
<newline>
739
When Yes, allow double clicks on the canvas to bring up various
740
popups depending on the location of the pointer when the double
741
click occurs.
742
<newline>
743
744
<item> XMgrace.toolBar
745
<newline>
746
Enables button toolbar
747
<newline>
748
749
<item> XMgrace.statusBar
750
<newline>
751
Enables status bar
752
<newline>
753
754
<item> XMgrace.locatorBar
755
<newline>
756
Enables locator bar
757
<newline>
758
759
</itemize>
760
761
762
It is also possible to customize menus by assigning key accelerators to
763
any item.
764
765
You'll need to derive the item's X resource name from the respective
766
menu label, which is easily done following these rules:
767
<itemize>
768
<item> All non-alphanumeric characters are skipped
769
<item> Start with lower case; each new word (if any) continues from
770
the capital letter
771
<item> Add the item's type to the end - "Menu" for pulldown menus,
772
"Button" for menu buttons.
773
</itemize>
774
775
For example, in order to make Grace popup the Non-linear curve fitting
776
by pressing Control+F, you would add the following two lines
777
778
<tt>
779
XMgrace*transformationsMenu.nonLinearCurveFittingButton.acceleratorText: Ctrl+F
780
<newline>
781
XMgrace*transformationsMenu.nonLinearCurveFittingButton.accelerator: Ctrl<Key>f
782
</tt>
783
784
785
to your <tt>.Xresources</tt> file (the file which is read when an X
786
session starts; it could be <tt>.Xdefaults</tt>, <tt>.Xsession</tt> or
787
some other file - ask your system administrator when in doubt).
788
789
<p>
790
Similarly, it may be desirable to alter default filename patterns of
791
file selection dialogs. The recipe for the dialog's name is like for
792
menu buttons outlined above, with "Button" being replaced with "FSB".
793
E.g., to list all files in the "Open project" dialog ("File/Open..."),
794
set the following resource:
795
796
<tt>
797
XMgrace*openProjectFSB.pattern: *
798
</tt>
799
800
</p>
801
802
803
<!-- **************************************** -->
804
<sect>Guide to the graphical user interface<label id="GUI-guide">
805
<p>
806
<sect1>GUI controls
807
<p>
808
This section describes interface controls - basic building blocks, used in
809
many popups.
810
</p>
811
<sect2>File selection dialogs <label id="FS-dialog">
812
<p>
813
Whenever the user is expected to provide a filename, either for reading
814
in or writing some data, a file selection dialog is popped up. In
815
addition to the standard entries (the directory and file lists and the
816
filter entry), there is a pulldown menu for quick directory change to
817
predefined locations (the current working directory, user's home
818
directory and the file system root). Also, a "Set as cwd" button is
819
there which allows to set any directory as you navigate through the
820
directory tree as the current working directory (cwd). Once defined, it
821
can be used in any other file selection dialog to switch to that
822
directory quickly.
823
824
<sect2>List selectors <label id="list-selector">
825
<p>
826
Various selectors are available in several popups. They all display
827
lists of objects (graphs, sets, ...) and can be used to perform
828
simple operations on these objects (copying, deleting, ...). The
829
operations are available from a popup menu that appears when pressing
830
mouse button 3 on them. Depending on the required functionality, they
831
may allow multiple choices or not. The following
832
shortcuts are enabled (if the result of an action would contradict the
833
list's selection policy, this would be ignored):
834
<itemize>
835
<item> Ctrl+a select all
836
<item> Ctrl+u unselect all
837
<item> Ctrl+i invert selection
838
</itemize>
839
840
<sect3> Graph selector <label id="graph-selector">
841
<p>
842
The operations that can be performed on graphs through the graph
843
selector's popup menu are:
844
<itemize>
845
<item> focus to
846
<item> hide
847
<item> show
848
<item> duplicate
849
<item> kill
850
<item> swap
851
<item> create new
852
</itemize>
853
All this operations are not available in every instance of the
854
selector. For example in the "read sets" popup only one graph can
855
be selected at a time, and the swap operation is disabled.
856
857
Double-clicking on a list entry will switch the focus to that graph.
858
859
<sect3> Set selector <label id="set-selector">
860
<p>
861
The operations that can be performed on sets through the set
862
selector's popup menu are:
863
<itemize>
864
<item> hide
865
<item> show
866
<item> bring to front
867
<item> send to back
868
<item> duplicate
869
<item> kill
870
<item> kill data
871
<item> swap
872
<item> edit
873
<itemize>
874
<item> in spreadsheet (see
875
<ref name="Spreadsheet data set editor" id="SSEditor">)
876
<item> in text editor
877
</itemize>
878
<item> create new
879
<itemize>
880
<item> by formula
881
<item> in spreadsheet (see
882
<ref name="Spreadsheet data set editor" id="SSEditor">)
883
<item> in text editor
884
<item> from block data
885
</itemize>
886
<item> pack all sets
887
<item> selector operations
888
<itemize>
889
<item> view set comments
890
<item> show data-less
891
<item> show hidden
892
<item> select all
893
<item> unselect all
894
<item> invert selection
895
<item> update
896
</itemize>
897
</itemize>
898
899
Double-clicking on a list entry will open the spreadsheet editor
900
(see <ref name="Spreadsheet data set editor" id="SSEditor">) on
901
the set data.
902
903
<sect1>The main window<label id="main-window">
904
<p>
905
906
<sect2>The canvas<label id="canvas">
907
<p>
908
909
<sect3>Canvas hotkeys
910
<p>
911
912
When the pointer focus is on the canvas (where the graph is drawn),
913
there are some shortcuts to activate several actions. They are:
914
915
<itemize>
916
<item> Ctrl <Key>A: Autoscale the current graph
917
<item> Ctrl <Key>D: Delete an object
918
<item> Ctrl <Key>L: Move current graph legend
919
<item> Ctrl <Key>M: Move an object
920
<item> Ctrl <Key>T: Place timestamp
921
<item> Ctrl <Key>U: Refresh hotlinks
922
<item> Ctrl <Key>V: Set the viewport with mouse
923
<item> Ctrl <Key>Z: Zoom
924
<item> Ctrl Alt <Key>L: Draw a line
925
<item> Ctrl Alt <Key>B: Draw a box
926
<item> Ctrl Alt <Key>E: Draw an ellipse
927
<item> Ctrl Alt <Key>T: Write a text string
928
</itemize>
929
930
<sect3>Clicks and double clicks<label id="clicks">
931
<p>
932
A single click inside a graph switches focus to that graph. This is the
933
default policy, but it can be changed from the "Edit/Preferences"
934
popup.
935
</p>
936
937
<p>
938
Double clicking on parts of the canvas will invoke certain actions
939
or raise some popups:
940
941
<itemize>
942
<item> on a focus marker: move selected viewport corner
943
<item> on an axis: "Plot/Axis properties" popup
944
<item> on a set: "Plot/Set appearance" popup
945
<item> on a legend: "Plot/Graph appearance" popup
946
<item> on a (sub)title: "Plot/Graph appearance" popup
947
<item> on an object (box, line, ...): a popup for editing
948
properties of that object
949
</itemize>
950
951
The double clicking actions can be enabled/disabled from the
952
"Edit/Preferences" popup.
953
954
<sect2>Toolbar buttons<label id="toolbar">
955
<p>
956
Along the left-hand side of the canvas (if shown) is the ToolBar. It
957
is armed with several buttons to provide quick and easy access to the
958
more commonly used Grace functions.
959
960
<itemize>
961
<item> <tt> Draw</tt>: This will redraw the canvas and sets.
962
Useful if "Auto Redraw" has been deselected in the Edit|Preferences
963
dialog or after executing commands directly from the Window|Commands
964
interpreter.
965
<p>
966
967
<item> <tt> Lens</tt>: A zoom lens. Click on the lens, then select the
968
area of interest on the graph with the "rubber band". The region
969
enclosed by the rubber band will fill the entire graph.
970
<item> <tt> AS</tt>: AutoScale. Autoscales the graph to contain all
971
data points of all visible (not hidden) sets.
972
<item> <tt> Z/z</tt>: Zoom in/out by 5%. The zoom percentage can be
973
set in the Edit/Preferences dialog.
974
<item> <tt>Arrows</tt>: Scroll active graph by 5% in the arrow's
975
direction. The scroll percentage can be set in the
976
Edit/Preferences dialog.
977
978
<p>
979
<item> <tt>AutoT</tt>: AutoTick Axes. This will find the optimum
980
number of major and minor tick marks for both axes.
981
<item> <tt>AutoO</tt>: Autoscale On set. Click the <tt>AutoO</tt>
982
button, then click on the graph near the set you wish to use for
983
determining the autoscale boundaries of the graph.
984
<p>
985
<item> <tt>ZX,ZY</tt>: Zoom along an axis. These buttons work like the
986
zoom lens above but are restricted to a single axis.
987
<item> <tt>AX,AY</tt>: Autoscale one axis only.
988
<p>
989
The following buttons deal with the graph stack and there is a good
990
example under Help/Examples/General Intro/World Stack.
991
<item> <tt>Pu/Po</tt>: Push and pop the current world settings to/from
992
the graph stack. When popping, makes the new stack top current.
993
<item> <tt>PZ</tt>: Push before Zooming. Functions as the zoom lens,
994
but first pushes the current world settings to the stack.
995
<item> <tt>Cy</tt>: Cycles through the stack settings of the active
996
graph. Each graph may have up to twenty layers on the stack.
997
<p>
998
<item> <tt>Exit</tt>: Pretty obvious, eh?
999
</itemize>
1000
1001
1002
<sect1> File menu <label id="file-menu">
1003
<p>
1004
The file menu contains all entries related to the input/output features
1005
of Grace.
1006
1007
<sect2> New <label id="new">
1008
<p>
1009
Reset the state of Grace as if it had just started (one empty
1010
graph ranging from 0 to 1 along both axes). If some work has
1011
been done and not yet saved, a warning popup is displayed to
1012
allow canceling the operation.
1013
1014
<sect2> Open <label id="open">
1015
<p>
1016
Open an existing <ref id="project-file" name="project file">. A
1017
popup is displayed that allow to browse the file system.
1018
1019
<sect2> Save <label id="save">
1020
<p>
1021
Save the current work in a project file, using the name that was
1022
used for the last open or save. If no name has been set (i.e.,
1023
if the project has been created from scratch) act as <ref
1024
id="save-as" name="save as">.
1025
1026
<sect2> Save as <label id="save-as">
1027
<p>
1028
Save the current work in a project file with a new name. A popup allows
1029
to browse the file system and set the name, the format to use for saving
1030
data points (the default value is "%16.8g"), and a textual description of
1031
the project. A warning is displayed if a file with the same name already
1032
exists.
1033
1034
<sect2> Revert to saved <label id="revert-to-saved">
1035
<p>
1036
Abandon all modifications performed on the project since the
1037
last save. A confirmation popup is fired to allow the user
1038
canceling the operation.
1039
1040
<sect2> Print setup <label id="print-setup">
1041
<p>
1042
Set the properties of the printing device. Each device has its
1043
own set of specific options (see <ref name="Device-specific
1044
settings" id="device-settings">). According to the device, the
1045
output can be sent either directly to a printer or directed to a
1046
file. The global settings available for all devices are the
1047
sizing parameters. The size of the graph is fixed. Changing the 'Page'
1048
settings changes the size of the canvas underneath the graph.
1049
Switching between portrait and landscape rotates the canvas.
1050
Make sure the canvas size is large enough to hold your graph.
1051
Otherwise you get a 'Printout truncated' warning. If your canvas
1052
size cannot easily be changed because, for example, you want to
1053
print on letter size paper, you need to adjust the size of
1054
your graph ('Viewport' in Plot/Graph Appearance).
1055
1056
<sect2> Print <label id="print">
1057
<p>
1058
Print the project using the current printer settings
1059
1060
<sect2> Exit <label id="exit">
1061
<p>
1062
Exit from Grace. If some work has been done and not saved, a
1063
warning popup will be displayed to allow the user to cancel the
1064
operation.
1065
1066
<sect1> Edit menu <label id="edit-menu">
1067
<p>
1068
<sect2> Data sets <label id="data-sets">
1069
<p>
1070
Using the data set popup, you can view the properties of
1071
datasets. This include its type, length, associated comment and
1072
some statistics (min, max, mean, standard deviation). A
1073
horizontal scrollbar at the bottom allows to get the two last
1074
properties, they are not displayed by default. Also note that if
1075
you find some columns are too narrow to show all significant
1076
digits, you can drag the vertical rules using Shift+Button 2.
1077
1078
Using the menu on the top of this dialog, you can manipulate existing
1079
sets or add new ones. Among the most important entries in the menu,
1080
are options to create or modify a set using the spreadsheet data set
1081
editor (see <ref name="Spreadsheet data set editor" id="SSEditor">).
1082
1083
<sect3>Spreadsheet data set editor<label id="SSEditor">
1084
<p>
1085
The dialog presents an editable matrix of numbers, corresponding
1086
to the data set being edited. The set type (and hence, the number
1087
of data columns) can be changed using the "Type:" selector.
1088
Clicking on a column label pops up a dialog allowing to adjust
1089
the column formatting. Clicking on the row labels toggles the
1090
respective row state (selected/unselected). The selected rows can
1091
be deleted via the dialog's "Edit" menu. Another entry in this
1092
menu lets you add a row; the place of the new row is determined
1093
by the row containing a cell with the keyboard focus on. As well,
1094
just typing in an empty cell will add one or several rows
1095
(filling the intermediate rows with zeros).
1096
1097
To resize columns, drag the vertical rules using Shift+Button 2.
1098
</p>
1099
</sect3> <!-- Spreadsheet data set editor -->
1100
1101
1102
<sect2> Set operations <label id="set-operations">
1103
<p>
1104
The set operations popup allows you to interact with sets as a
1105
whole. If you want to operate on the data ordering of the sets,
1106
you should use the <ref name="data set operations"
1107
id="data-set-operations"> popup from the Data menu. The popup
1108
allows you to select a source (one set within one graph) and a
1109
destination and perform some action upon them (copy, move,
1110
swap). This popup also give you a quick access to several graph
1111
and set selectors if you want to perform some other operation
1112
like hiding a graph or creating a new set from block data.
1113
1114
<sect2> Arrange graphs <label id="arrange-graphs">
1115
<p>
1116
This entry fires up a popup to lay out several graphs in a
1117
regular grid given by <bf>M</bf> rows and <bf>N</bf> columns.
1118
1119
The graph selector at the top allows one to select a number of graphs
1120
the arrangement will operate on. If the number of selected graphs
1121
isn't equal to <bf>M</bf> times <bf>N</bf>, new graphs may be created
1122
or extra graphs killed if needed. These options are controlled by the
1123
respective checkboxes below the graph selector.
1124
1125
The order in which the matrix is filled in with the graphs can be
1126
selected (first horizontally then vertically or vise versa, with
1127
either of them inverted). Additionaly, one may choose to fill the matrix
1128
in the snake-like manner (adjacent "strokes" are anti-parallel).
1129
1130
The rest of the controls of the dialog window deal with the matrix
1131
spacing: left/right/top/bottom page offsets (in the viewport
1132
coordinates) and <it>relative</it> inter-cell distances, vertical
1133
and horizontal. Next to each of the vertical/horizontal spacing
1134
spinboxes, a "Pack" checkbox is found. Enabling it effectively sets
1135
the respective inter-cell distance to zero and alter axis tickmark
1136
settings such that only bottom/left-most tickmarks are visible.
1137
1138
If you don't want the regular layout this arrangement gives you,
1139
you can change it afterwards using the mouse (select a graph and
1140
double click on the focus marker, see <ref id="clicks"
1141
name="clicks and double clicks">).
1142
1143
<sect2> Overlay graphs <label id="overlay-graphs">
1144
<p>
1145
You can overlay a graph on top of another one. The main use of
1146
this feature is to plot several curves using different scales on
1147
the same (apparently) graph. The main difficulty is to be sure
1148
you operate on the graph you want at all times (you can hide one
1149
for a moment if this becomes too difficult).
1150
1151
<sect2> Autoscale <label id="autoscale">
1152
<p>
1153
Using this entry, you can autoscale one graph or all graphs
1154
according to the specified sets only. This is useful if you need
1155
either to have truly comparable graphs despite every one
1156
contains data of different ranges, or if you want to focus your
1157
attention on one set only while it is displayed with other data
1158
in a complex graph.
1159
1160
<sect2> Regions menu <label id="regions-menu">
1161
<p>
1162
<sect3> Status <label id="status">
1163
<p>
1164
This small popup only displays the current state (type and
1165
whether it is active or not) of the existing regions.
1166
1167
<sect3> Define <label id="define">
1168
<p>
1169
You can define a new region (or redefine an existing one),
1170
the allowed region types are:
1171
1172
<itemize>
1173
<item> Inside polygon
1174
<item> Outside polygon
1175
<item> Above line
1176
<item> Below line
1177
<item> Left of line
1178
<item> Right of line
1179
<item> In horizontal range
1180
<item> In vertical range
1181
<item> Out of horizontal range
1182
<item> Out of vertical range
1183
</itemize>
1184
1185
A region can be either linked to the current graph only or to
1186
all graphs.
1187
1188
<sect3> Clear <label id="clear">
1189
<p>
1190
This kills a region.
1191
1192
<sect3> Report on <label id="report-on">
1193
<p>
1194
This popup reports you which sets or points are inside or
1195
outside of a region.
1196
1197
<sect2> Hot links <label id="hot-links">
1198
<p>
1199
You can link a set to a file or a pipe using this feature. Once
1200
a link has been established, you can update it (i.e., read data
1201
again) by clicking on the update button. If you have specified a
1202
command (using Grace language) in the corresponding text field
1203
of the popup, it will be executed after each update. Note that
1204
you can use several commands separated by ';' characters.
1205
<p>
1206
Currently, only simple XY sets can be used for hotlinks.
1207
1208
<sect2> Set locator fixed point <label id="set-locator-fixed-point">
1209
<p>
1210
After having selected this menu entry, you can select a point on
1211
a graph that will be used as the origin of the locator display
1212
(just below the menu bar). The fixed point is taken into account
1213
only when the display type of the locator is set to [DX,DY].
1214
1215
<sect2> Clear locator fixed point <label id="clear-locator-fixed-point">
1216
<p>
1217
This entry is provided to remove a fixed point set before and
1218
use the default again: point [0, 0].
1219
1220
<sect2> Locator props <label id="locator-props">
1221
<p>
1222
The locator props popup allows you to customize the display of
1223
the locator, mainly its type and the format and precision of the
1224
display. You can use all the formats that are allowed in the
1225
graphs scales.
1226
1227
<sect2> Preferences <label id="preferences">
1228
<p>
1229
The preferences popup allows you to set miscellaneous properties
1230
of your Grace session, such as GUI behavior, cursor type,
1231
date reading hint and reference date used for calendar conversions.
1232
1233
<sect1> Data menu <label id="data-menu">
1234
<p>
1235
<sect2> Data set operations <label id="data-set-operations">
1236
<p>
1237
This popup gathers all operations that are related to the
1238
ordering of data points inside a set or between sets. If you
1239
want to operate on the sets as a whole, you should use the <ref
1240
name="set operations" id="set-operations"> popup from the Edit
1241
menu. You can sort according to any coordinate (X, Y, DX, ...)
1242
in ascending or descending order, reverse the order of the
1243
points, join several sets into one, split one set into several
1244
others of equal lengths, or drop a range of points from a
1245
set. The <ref name="set selector" id="set-selector"> of the
1246
popup shows the number of points in each set in square brackets
1247
like this: G0.S0[63], the points are numbered from 0 to n-1.
1248
1249
<sect2> Transformations menu <label id="transformations-menu">
1250
<p>
1251
The transformations sub-menu gives you access to all data-mining
1252
features of Grace.
1253
1254
<sect3> Evaluate expression <label id="evaluate-expression">
1255
<p>
1256
Using evaluate expression allows you to create a set by
1257
applying an explicit formula to another set, or to parts of
1258
another set if you use regions restrictions.
1259
1260
All the classical mathematical functions are available (cos,
1261
sin, but also lgamma, j1, erf, ...). As usual all
1262
trigonometric functions use radians by default but you can
1263
specify a unit if you prefer to say cos (x rad) or sin (3 * y
1264
deg). For the full list of available numerical functions and
1265
operators, see
1266
<ref name="Operators and functions" id="operators-and-functions">.
1267
1268
In the formula, you can use X, Y, Y1, ..., Y4 to denote any
1269
coordinate you like from the source set. An implicit loop
1270
will be used around your formula so if you say:
1271
1272
<tscreen><verb>
1273
x = x - 4966.5
1274
</verb></tscreen>
1275
1276
you will shift all points of your set 4966.5 units to the left.
1277
1278
You can use more than one set in the same formula, like this:
1279
1280
<tscreen><verb>
1281
y = y - 0.653 * sin (x deg) + s2.y
1282
</verb></tscreen>
1283
1284
which means you use both X and Y from the source set but also
1285
the Y coordinate of set 2. Beware that the loop is a simple
1286
loop over the indices, all the sets you use in such an hybrid
1287
expression should therefore have the same number of points
1288
and point i of one set should really be related to point i of
1289
the other set. If your sets do not follow these requirements,
1290
you should first homogenize them using
1291
<ref name="interpolation" id="interpolation">.
1292
1293
<sect3> Histograms <label id="histograms">
1294
<p>
1295
The histograms popup allows you to compute either standard
1296
or cumulative histograms from the Y coordinates of
1297
your data. Optionally, the histograms can be normalized to 1 (hence
1298
producing a PDF (Probability Distribution Function).
1299
1300
The bins can be either a linear mesh defined by its min, max, and
1301
length values, or a mesh formed by abscissas of another set (in which
1302
case abscissas of the set must form a strictly monotonic array).
1303
1304
<sect3> Fourier transforms <label id="fourier-transforms">
1305
<p>
1306
This popup is devoted to direct and inverse Fourier
1307
transforms. The default is to perform a direct transform on
1308
unfiltered data and to produce a set with the index as
1309
abscissa and magnitude as ordinate. You can filter the input
1310
data window through triangular, Hanning, Welch, Hamming,
1311
Blackman and Parzen filters. You can load magnitude, phase or
1312
coefficients and use either index, frequency or period as
1313
abscissas. You can choose between direct and inverse Fourier
1314
transforms. If you specify real input data, X is assumed to
1315
be equally spaced and ignored; if you specify complex input
1316
data X is taken as the real part and Y as the imaginary part.
1317
1318
If Grace was configured with the FFTW library (see <ref
1319
name="configuration" id="configuration">), then the DFT and
1320
FFT buttons really perform the same transform (so there is no
1321
speed-up in using FFT in this case). If you want Grace can to
1322
use FFTW <it>wisdom</it> files, you should set several <ref
1323
name="environment variables" id="environment-variables"> to
1324
name them.
1325
1326
<sect3> Running averages <label id="running-averages">
1327
<p>
1328
The running average popup allows you to compute some values
1329
on a sliding window over your data. You choose both the value
1330
you need (average, median, minimum, maximum, standard
1331
deviation) and the length of the window and perform the
1332
operation. You can restrict the operation to the points
1333
belonging to (or outside of) a region.
1334
1335
<sect3> Differences <label id="differences">
1336
<p>
1337
The differences popup is used to compute approximations of
1338
the first derivative of a function with finite
1339
differences. The only choice (apart from the source set of
1340
course) is the type of differences to use: forward, backward
1341
or centered.
1342
1343
<sect3> Seasonal differences <label id="seasonal-differences">
1344
<p>
1345
The seasonal differences popup is used to subtract data from
1346
a period to data of the preceding period (namely y[i] - y[i +
1347
period]). Beware that the period is entered in terms of index
1348
in the set and not in terms of abscissa!
1349
1350
<sect3> Integration <label id="integration">
1351
<p>
1352
The integration popup is used to compute the integral of a
1353
set and optionally to load it. The numerical value of the
1354
integral is shown in the text field after
1355
computation. Selecting "cumulative sum" in the choice item
1356
will create and load a new set with the integral and compute
1357
the end value, selecting "sum only" will only compute the end
1358
value.
1359
1360
<sect3> Interpolation/Splines <label id="interpolation">
1361
<p>
1362
This popup is used to interpolate a set on an array of alternative X
1363
coordinates. This is mainly used before performing some complex
1364
operations between two sets with the <ref name="evaluate
1365
expression" id="evaluate-expression"> popup.
1366
1367
The sampling array can be either a linear mesh defined by its min,
1368
max, and length values, or a mesh formed by abscissas of another set.
1369
1370
Several interpolation methods can be used: linear, spline or Akima
1371
spline.
1372
1373
Note that if the sampling mesh is not entirely within the source set
1374
X bounds, evaluation at the points beyond the bounds will be performed
1375
using interpolation parameters from the first (or the last) segment
1376
of the source set, which can be considered a primitive extrapolation.
1377
This behaviour can be disabled by checking the "Strict" option on the
1378
popup.
1379
1380
The abscissas of the set being interpolated must form a strictly
1381
monotonic array.
1382
1383
<sect3> Regression <label id="regression">
1384
<p>
1385
The regression popup can be used to fit a set against
1386
polynomials or some specific functions (y=A*x^B,
1387
y=A*exp(B*x), y=A+B*ln(x) and y=1/(A+Bx)) for which a simple
1388
transformation of input data can be used to apply linear
1389
regression formulas.
1390
1391
You can load either the fitted values, the residuals or the
1392
function itself. Choosing to load fitted values or residuals
1393
leads to a set of the same length and abscissas as the
1394
initial set. Choosing to load the function is almost similar
1395
to load the fitted values except that you choose yourself the
1396
boundaries and the number of points. This can be used for
1397
example to draw the curve outside of the data sample range or
1398
to produce an evenly spaced set from an irregular one.
1399
1400
<sect3> Non-linear fit <label id="non-linear-fit">
1401
<p>
1402
The non linear fit popup can be used for functions outside of
1403
the simple regression methods scope. With this popup you
1404
provide the expression yourself using a0, a1, ..., a9 to
1405
denote the fit parameters (as an example you can say y = a0 * cos
1406
(a1 * x + a2)). You specify a tolerance, starting values and
1407
optional bounds and run several steps before loading the
1408
results.
1409
1410
The fit characteristics (number of parameters, formula, ...)
1411
can be saved in a file and retrieved as needed using the file
1412
menu of the popup.
1413
1414
In the "Advanced" tab, you can additionally apply a restriction to the
1415
set(s) to be fitted (thus ignoring points not satisfying the
1416
criteria), use one of preset weighting schemes or define your own,
1417
and choose whether to load the fitted values, the residuals or
1418
the function itself. Choosing to load fitted values or residuals leads
1419
to a set of the same length and abscissas as the initial set. Choosing
1420
to load the function is almost similar to load the fitted values
1421
except that you choose yourself the boundaries and the number of
1422
points. This can be used for example to draw the curve outside of the
1423
data sample range or to produce an evenly spaced set from an irregular
1424
one.
1425
1426
<sect3> Correlation/covariance <label id="correlation/covariance">
1427
<p>
1428
This popup can be used to compute autocorrelation
1429
of one set or cross correlation between two sets. You only
1430
select the set (or sets) and specify the maximum lag. A check
1431
box allows one to evaluate covariance instead of correlation.
1432
1433
<sect3> Digital filter <label id="digital-filter">
1434
<p>
1435
You can use a set as a weight to filter another set. Only the
1436
Y part and the length of the weighting set are important, the
1437
X part is ignored.
1438
1439
<sect3> Linear convolution <label id="linear-convolution">
1440
<p>
1441
The convolution popup is used to ... convolve two sets. You
1442
only select the sets and apply.
1443
1444
<sect3> Geometric transforms <label id="geometric-transforms">
1445
<p>
1446
You can rotate, scale or translate sets using the geometric
1447
transformations popup. You specify the characteristics of
1448
each transform and the application order.
1449
1450
<sect3> Sample points <label id="sample-points">
1451
<p>
1452
This popup provides two sampling methods. The first one is
1453
to choose a starting point and a step, the second one is to
1454
select only the points that satisfy a boolean expression you
1455
specify.
1456
1457
<sect3> Prune data <label id="prune-data">
1458
<p>
1459
This popup is devoted to reducing huge sets (and then saving
1460
both computation time and disk space).
1461
1462
The interpolation method can be applied only to ordered sets:
1463
it is based on the assumption that if a real point and an
1464
interpolation based on neighboring points are closer than a
1465
specified threshold, then the point is redundant and can be
1466
eliminated.
1467
1468
The geometric methods (circle, ellipse, rectangle) can be
1469
applied to any set, they test each point in turn and keep
1470
only those that are not in the neighborhood of previous
1471
points.
1472
<p>
1473
1474
<sect2> Feature extraction <label id="feature-extraction">
1475
<p>
1476
Given a set of curves in a graph, extract a feature from each
1477
curve and use the values of the feature to provide the Y values
1478
for a new curve.
1479
1480
<p>
1481
<table loc="htbp">
1482
<tabular ca="lp{10cm}">
1483
<hline>
1484
Feature | Description @
1485
<hline>
1486
Y minimum | Minimum Y value of set @
1487
Y maximum | Maximum Y value of set @
1488
Y average | Average Y value of set @
1489
Y std. dev. | Standard deviation of Y values @
1490
Y median | Median Y value @
1491
X minimum | Minimum X value of set @
1492
X maximum | Maximum X value of set @
1493
X average | Average X value of set @
1494
X std. dev. | Standard deviation of X values @
1495
X median | Median X value @
1496
Frequency | Perform DFT (FFT if set length a power of 2) to find largest frequency component @
1497
Period | Inverse of above @
1498
Zero crossing | Time of the first zero crossing, + or - going @
1499
Rise time | Assume curve starts at the minimum and rises to the maximum, get time to go from 10% to 90% of rise. For single exponential curves, this is 2.2*time constant @
1500
Fall time | Assume curve starts at the maximum and drops to the minimum, get time to go from 90% to 10% of fall @
1501
Slope | Perform linear regression to obtain slope @
1502
Y intercept | Perform linear regression to obtain Y-intercept @
1503
Set length | Number of data points in set @
1504
Half maximal width | Assume curve starts from the minimum, rises to the maximum and drops to the minimum again. Determine the time for which the curve is elevated more than 50% of the maximum rise. @
1505
Barycenter X | Barycenter along X axis @
1506
Barycenter Y | Barycenter along Y axis @
1507
X (Y max) | X of Maximum Y @
1508
Y (X max) | Y of Maximum X @
1509
integral | cumulative sum @
1510
<hline>
1511
</tabular>
1512
<caption>
1513
Extractable features
1514
</caption>
1515
</table>
1516
1517
<sect2> Import menu <label id="read-menu">
1518
<p>
1519
<sect3> ASCII <label id="read-sets">
1520
<p>
1521
Read new sets of data in a graph. A <ref id="graph-selector"
1522
name="graph selector"> is used to specify the graph where the
1523
data should go (except when reading block data, which are
1524
copied to graphs later on).
1525
1526
Reading as "Single set" means that if the source contains
1527
only one column of numeric data, one set will be created
1528
using the indices (from 1 to the total number of points) as
1529
abscissas and read values as ordinates and that if the source
1530
contains more than one column of data, the first two numeric
1531
columns will be used. Reading as "NXY" means that the first
1532
numeric column will provide the abscissas and all remaining
1533
columns will provide the ordinates of several sets. Reading
1534
as "Block data" means all column will be read and stored and
1535
that another popup will allow to select the abscissas and
1536
ordinates at will. It should be noted that block data are
1537
stored as long as you do not override them by a new read. You
1538
can still retrieve data from a block long after having closed
1539
all popups, using the <ref id="set-selector" name="set
1540
selector">.
1541
1542
The set type can be one of the predefined set presentation types
1543
(see <ref id="sets" name="sets">).
1544
1545
The data source can be selected as "Disk" or "Pipe". In the
1546
first case the text in the "Selection" field is considered to
1547
be a file name (it can be automatically set by the file
1548
selector at the top of the popup). In the latter case the
1549
text is considered to be a command which is executed and
1550
should produce the data on its standard output. On systems
1551
that allows is, the command can be a complete sequence of
1552
programs glued together with pipes.
1553
1554
If the source contains date fields, they should be
1555
automatically detected. Several formats are recognized (see
1556
appendix <ref id="dates" name="dates in grace">). Calendar
1557
dates are converted to numerical dates upon reading.
1558
1559
The "Autoscale on read" menu controls whether, upon reading in new
1560
sets, which axes of the graph should be autoscaled.
1561
1562
<sect3> NetCDF <label id="read-netCDF">
1563
<p>
1564
This entry exists only if Grace has been compiled with
1565
support for the NetCDF data format (see <ref
1566
id="configuration" name="configuration">).
1567
1568
<sect2> Export menu <label id="write-menu">
1569
<p>
1570
<sect3> ASCII <label id="write-sets">
1571
<p>
1572
Save data sets in a file. A <ref id="set-selector" name="set
1573
selector"> is used to specify the set to be saved. The format
1574
to use for saving data points can be specified (the default
1575
value is "%16.8g"). A warning is displayed if a file with the
1576
same name already exists.
1577
1578
1579
<sect1> Plot menu <label id="plot-menu">
1580
<p>
1581
<sect2> Plot appearance <label id="plot-appearance">
1582
<p>
1583
The plot appearance popup let you set the time stamp properties
1584
and the background color of the page. The color is used outside
1585
of graphs and also on graphs were no specific background color
1586
is set. The time stamp is updated every time the project is modified.
1587
1588
<sect2> Graph appearance <label id="graph-appearance">
1589
<p>
1590
The graph appearance popup can be displayed from both the plot menu
1591
and by double-clicking on a legend, title, or subtitle of a graph
1592
(see <ref name="Clicks and double clicks" id="clicks">). The graph
1593
selector at the top allows to choose the graph you want to operate
1594
on, it also allows certain common actions through its popup menu (see
1595
<ref name="graph selector" id="graph-selector">). Most of the actions
1596
can also be performed using the "Edit" menu available from the popup
1597
menubar. The main tab includes the properties you will need more
1598
often (title for example), and other tabs are used to fine tune some
1599
less frequently used options (fonts, sizes, colors, placements).
1600
1601
If you need special characters or special formatting in your
1602
title or subtitle, you can use Grace escape sequences (the
1603
sequence will appear verbatim in the text field but will be
1604
rendered on the graph), see <ref name="typesetting"
1605
id="typesetting">. If you don't remember the mapping between
1606
alphabetic characters and the glyph you need in some specific
1607
fonts (mainly symbol and zapfdingbats), you can invoke the font
1608
tool from the text field by hitting CTRL-e. You can change fonts
1609
and select characters from there, they will be copied back in
1610
the text field when you press the "Accept" button. Beware of
1611
the position of the cursor as you enter text or change font in
1612
the font tool, the character or command will be inserted at this
1613
position, not at the end of the string!
1614
1615
You can save graph appearance parameters or retrieve settings
1616
previously saved via the "File" menu of this popup. In the "Save
1617
parameters" dialog, you can choose to save settings either for
1618
the current graph only or for all graphs.
1619
1620
1621
<sect2> Set appearance <label id="set-appearance">
1622
<p>
1623
The set appearance popup can be displayed from both the plot
1624
menu and by double-clicking anywhere in a graph (see <ref
1625
name="Clicks and double clicks" id="clicks">). The set selector
1626
at the top allows to choose the set you want to operate on, it
1627
also allows certain common actions through its popup menu (see
1628
<ref name="set selector" id="set-selector">). The main tab
1629
gathers the properties you will need more often (line and
1630
symbol properties or legend string for example), and other tabs
1631
are used to fine tune some less frequently used options (drop
1632
lines, fill properties, annotated values and error bars
1633
properties for example).
1634
1635
You should note that despite the legend string related to
1636
<em>one</em> set is entered in the set appearance popup, this is not
1637
sufficient to display it. Displaying <em>all</em> legends is a graph
1638
level decision, so the toggle is in the main tab of the <ref
1639
name="graph appearance" id="graph-appearance"> popup.
1640
1641
If you need special characters or special formatting in your
1642
legend, you can use Grace escape sequences (the sequence will
1643
appear verbatim in the text field but will be rendered on the
1644
graph), see <ref name="typesetting" id="typesetting">. If you
1645
don't remember the mapping between alphabetic characters and the
1646
glyph you need in some specific fonts (mainly symbol and
1647
zapfdingbats), you can invoke the font tool from the text
1648
field by hitting CTRL-e. You can change fonts and select
1649
characters from there, they will be copied back in the text
1650
field when you press the "Accept" button. Beware of the
1651
position of the cursor as you enter text or change font in the
1652
font tool, the character or command will be inserted at this
1653
position, not at the end of the string!
1654
1655
<sect2> Axis properties <label id="axis-properties">
1656
<p>
1657
The axis properties popup can be displayed from both the "Plot"
1658
menu and by double-clicking exactly on an axis (see <ref
1659
name="Clicks and double clicks" id="clicks">). The pulldown menu
1660
at the top allows to select the axis you want to operate on. The
1661
"Active" toggle globally activates or deactivates the axis (all
1662
GUI elements are insensitive for deactivated axes). The start
1663
and stop fields depict the displayed range. Three types of
1664
scales are available: linear, logarithmic or reciprocal, and
1665
you can invert the axis (which normally increases from left to
1666
right and from bottom to top). The main tab includes the
1667
properties you will need more often (axis label, tick
1668
spacing and format for example), and other tabs are used to fine
1669
tune some less frequently used options (fonts, sizes, colors,
1670
placements, stagger, grid lines, special ticks, ...).
1671
1672
If you need special characters or special formatting in your
1673
label, you can use Grace escape sequences (the
1674
sequence will appear verbatim in the text field but will be
1675
rendered on the graph), see <ref name="typesetting"
1676
id="typesetting">. If you don't remember the mapping between
1677
alphabetic characters and the glyph you need in some specific
1678
fonts (mainly symbol and zapfdingbats), you can invoke the font
1679
tool from the text field by hitting CTRL-e. You can change fonts
1680
and select characters from there, they will be copied back in
1681
the text field when you press the "Accept" button. Beware of
1682
the position of the cursor as you enter text or change font in
1683
the font tool, the character or command will be inserted at this
1684
position, not at the end of the string!
1685
1686
Once you have set the options as you want, you can apply
1687
them. One useful feature is that you can set several axes at
1688
once with the bottom pulldown menu (current axis, all axes
1689
current graph, current axis all graphs, all axes all
1690
graphs). Beware that you always apply the properties of all
1691
tabs, not only the selected one.
1692
1693
<sect1> View menu <label id="view-menu">
1694
<p>
1695
<sect2> Show locator bar <label id="show-locator-bar">
1696
<p>
1697
This toggle item shows or hides the locator below the menu bar.
1698
1699
<sect2> Show status bar <label id="show-status-bar">
1700
<p>
1701
This toggle item shows or hides the status string below the
1702
canvas.
1703
1704
<sect2> Show tool bar <label id="show-tool-bar">
1705
<p>
1706
This toggle item shows or hides the tool bar at the left of the
1707
canvas.
1708
1709
<sect2> Page setup <label id="page-setup">
1710
<p>
1711
Set the properties of the display device. It is the same dialog as
1712
in <ref name="Print setup" id="print-setup">.
1713
1714
<sect2> Redraw <label id="redraw">
1715
<p>
1716
This menu item triggers a redrawing of the canvas.
1717
1718
<sect2> Update all <label id="update-all">
1719
<p>
1720
This menu item causes an update of all GUI controls. Usually, everything
1721
is updated automatically, unless one makes modifications by entering
1722
commands in the <ref name="Command" id="commands"> tool.
1723
1724
1725
<sect1> Window menu <label id="window-menu">
1726
<p>
1727
<sect2> Commands <label id="commands">
1728
<p>
1729
Command driven version of the interface to Grace. Here, commands
1730
are typed at the "Command:" text item and executed when
1731
<Return> is pressed. The command will be parsed and executed,
1732
and the command line is placed in the history list. Items in the
1733
history list can be recalled by simply clicking on them with the
1734
left mouse button. For a reference on the Grace command interpreter,
1735
see <ref id="command-interpreter" name="Command interpreter">.
1736
</p>
1737
<sect2> Point tracking <label id="point-tracking">
1738
<p>
1739
Not written yet...
1740
</p>
1741
<sect2> Drawing objects <label id="drawing-objects">
1742
<p>
1743
Not written yet...
1744
</p>
1745
<sect2> Font tool <label id="font-tool">
1746
<p>
1747
Not written yet...
1748
</p>
1749
<sect2> Console <label id="console">
1750
<p>
1751
The console window displays errors and results of some numerical
1752
operations, e.g. nonlinear fit (see <ref id="non-linear-fit"
1753
name="Non-linear fit">). The window is popped up automatically
1754
whenever an error occurs or new result messages appear. This can
1755
be altered by checking the "Options/Popup only on errors" option.
1756
</p>
1757
1758
<sect1> Help menu <label id="help-menu">
1759
<p>
1760
<sect2> On context <label id="on-context">
1761
<p>
1762
Click on any element of the interface to get context-sensitive help
1763
on it. Only partially implemented at the moment.
1764
</p>
1765
<sect2> User's guide <label id="users-guide">
1766
<p>
1767
Browse the Grace user's guide.
1768
</p>
1769
<sect2> Tutorial <label id="tutorial">
1770
<p>
1771
Browse the Grace tutorial.
1772
</p>
1773
<sect2> FAQ <label id="faq">
1774
<p>
1775
Frequently Asked Questions with answers.
1776
</p>
1777
<sect2> Changes <label id="changes">
1778
<p>
1779
The list of changes during the Grace development.
1780
</p>
1781
<sect2> Examples <label id="examples">
1782
<p>
1783
The whole tree of submenus each loading a sample plot.
1784
</p>
1785
<sect2> Comments <label id="comments">
1786
<p>
1787
Use this to send your suggestions or bug reports.
1788
</p>
1789
<sect2> License terms <label id="license-terms">
1790
<p>
1791
Grace licensing terms will be displayed (GPL version 2).
1792
</p>
1793
<sect2> About <label id="about">
1794
<p>
1795
A popup with basic info on the software, including some
1796
configuration details. More details can be found when running Grace
1797
with the "-version" command line flag.
1798
</p>
1799
1800
<!-- **************************************** -->
1801
<sect>Command interpreter <label id="command-interpreter">
1802
<p>
1803
1804
<sect1>General notes
1805
1806
<p>
1807
The interpreter parses its input in a line-by-line manner. There may
1808
be several statements per line, separated by semicolon (<tt>;</tt>).
1809
The maximal line length is 4 kbytes (hardcoded). The parser is
1810
case-insensitive and ignores lines beginning with the "<tt>#</tt>" sign.
1811
</p>
1812
1813
<sect1>Definitions
1814
1815
<p>
1816
<table loc="htbp">
1817
<tabular ca="lll">
1818
<hline>
1819
Name | Description | Examples @
1820
<hline>
1821
expr |
1822
Any numeric expression |
1823
1.5 + sin(2) @
1824
iexpr |
1825
Any expression that evaluates to an integer |
1826
25, 0.1 + 1.9, PI/asin(1) @
1827
nexpr |
1828
Non-negative iexpr |
1829
2 - 1 @
1830
indx |
1831
Non-negative iexpr |
1832
@
1833
qstr |
1834
Quoted string |
1835
"a string" @
1836
vexpr |
1837
Vector expression |
1838
"2*x" @
1839
<hline>
1840
</tabular>
1841
<caption>
1842
<label id="types">
1843
Basic types
1844
</caption>
1845
</table>
1846
</p>
1847
1848
<p>
1849
<table loc="htbp">
1850
<tabular ca="llll">
1851
<hline>
1852
Expression | Description | Types | Example @
1853
<hline>
1854
GRAPH[<it>id</it>] |
1855
graph <it>id</it> |
1856
indx <it>id</it> |
1857
GRAPH[0] @
1858
G<it>nn</it> |
1859
graph <it>nn</it> |
1860
<it>nn</it>: 0-99 |
1861
G0 @
1862
<hline>
1863
</tabular>
1864
<caption>
1865
<label id="graph-sel">
1866
Graph selections
1867
</caption>
1868
</table>
1869
</p>
1870
1871
<p>
1872
<table loc="htbp">
1873
<tabular ca="llll">
1874
<hline>
1875
Expression | Description | Types | Example @
1876
<hline>
1877
<it>graph</it>.SETS[<it>id</it>] |
1878
set <it>id</it> in graph <it>graph</it>|
1879
indx <it>id</it>, graphsel <it>graph</it> |
1880
GRAPH[0].SETS[1] @
1881
<it>graph</it>.S<it>nn</it> |
1882
set <it>nn</it> in graph <it>graph</it>|
1883
<it>nn</it>: 0-99, graphsel <it>graph</it> |
1884
G0.S1 @
1885
SET[<it>id</it>] |
1886
set <it>id</it> in the current graph|
1887
indx <it>id</it> |
1888
SET[1] @
1889
S<it>nn</it> |
1890
set <it>nn</it> in the current graph|
1891
<it>nn</it>: 0-99 |
1892
S1 @
1893
S_ |
1894
the last allocated set in the current graph|
1895
- |
1896
S_ @
1897
S$ |
1898
the active set in the current graph|
1899
- |
1900
S$ @
1901
<hline>
1902
</tabular>
1903
<caption>
1904
<label id="set-sel">
1905
Set selections
1906
</caption>
1907
</table>
1908
</p>
1909
1910
<p>
1911
<table loc="htbp">
1912
<tabular ca="llll">
1913
<hline>
1914
Expression | Description | Types | Example @
1915
<hline>
1916
R<it>n</it> |
1917
region <it>n</it> |
1918
<it>n</it>: 0-4 |
1919
R0 @
1920
<hline>
1921
</tabular>
1922
<caption>
1923
<label id="region-sel">
1924
Region selections
1925
</caption>
1926
</table>
1927
</p>
1928
1929
1930
<p>
1931
<table loc="htbp">
1932
<tabular ca="llll">
1933
<hline>
1934
Expression | Description | Types | Example @
1935
<hline>
1936
COLOR <it>"colorname"</it> |
1937
a mapped color <it>colorname</it> |
1938
- |
1939
COLOR "red" @
1940
COLOR <it>id</it> |
1941
a mapped color with ID <it>id</it> |
1942
nexpr <it>id</it> |
1943
COLOR 2 @
1944
<hline>
1945
</tabular>
1946
<caption>
1947
<label id="color-sel">
1948
Color selections
1949
</caption>
1950
</table>
1951
</p>
1952
1953
<p>
1954
<table loc="htbp">
1955
<tabular ca="llll">
1956
<hline>
1957
Expression | Description | Types | Example @
1958
<hline>
1959
PATTERN <it>id</it> |
1960
pattern with ID <it>id</it> |
1961
nexpr <it>id</it> |
1962
PATTERN 1 @
1963
<hline>
1964
</tabular>
1965
<caption>
1966
<label id="pattern-sel">
1967
Pattern selections
1968
</caption>
1969
</table>
1970
</p>
1971
1972
<p>
1973
<table loc="htbp">
1974
<tabular ca="llll">
1975
<hline>
1976
Expression | Description | Types | Example @
1977
<hline>
1978
X |
1979
the first column |
1980
- |
1981
X @
1982
Y |
1983
the second column |
1984
- |
1985
Y @
1986
Y<it>n</it> |
1987
(<it>n</it> + 2)-th column |
1988
<it>n</it> = 0 - 4 |
1989
Y3 @
1990
<hline>
1991
</tabular>
1992
<caption>
1993
<label id="datacol-sel">
1994
Data column selections
1995
</caption>
1996
</table>
1997
</p>
1998
1999
<p>
2000
Not finished yet...
2001
</p>
2002
2003
<sect1>Variables
2004
<p>
2005
2006
<table loc="htbp">
2007
<tabular ca="ll">
2008
<hline>
2009
Variable | Description @
2010
<hline>
2011
datacolumn | data column of current set @
2012
set.datacolumn | data column of set @
2013
<hline>
2014
vvar | user-defined array @
2015
<hline>
2016
vvariable [i:j] | segment of a vector variable (elements from i-th to j-th inclusive, i <= j) @
2017
<hline>
2018
</tabular>
2019
<caption>
2020
<label id="vvariables">
2021
Vector variables
2022
</caption>
2023
</table>
2024
2025
<p>
2026
2027
<table loc="htbp">
2028
<tabular ca="ll">
2029
<hline>
2030
Variable | Description @
2031
<hline>
2032
vvariable[i] | i-th element of a vector variable @
2033
<hline>
2034
var | user-defined variable @
2035
<hline>
2036
</tabular>
2037
<caption>
2038
<label id="svariables">
2039
Scalar variables
2040
</caption>
2041
</table>
2042
2043
2044
<sect1>Numerical operators and functions<label id="operators-and-functions">
2045
<p>
2046
2047
In numerical expressions, the infix format is used. Arguments of
2048
both operators and functions can be either scalars or vector arrays.
2049
2050
<p>
2051
2052
<table loc="htbp">
2053
<tabular ca="cl">
2054
<hline>
2055
Operator | Description @
2056
<hline>
2057
+ | addition @
2058
- | substraction @
2059
* | multiplication @
2060
/ | division @
2061
% | modulus @
2062
^ | raising to power @
2063
<hline>
2064
</tabular>
2065
<caption>
2066
<label id="arithmetic-operators">
2067
Arithmetic operators
2068
</caption>
2069
</table>
2070
2071
<p>
2072
2073
<table loc="htbp">
2074
<tabular ca="cl">
2075
<hline>
2076
Operator | Description @
2077
<hline>
2078
AND or && | logical AND @
2079
OR or || | logical OR @
2080
NOT or ! | logical NOT @
2081
<hline>
2082
</tabular>
2083
<caption>
2084
<label id="logical-operators">
2085
Logical operators
2086
</caption>
2087
</table>
2088
2089
<p>
2090
2091
<table loc="htbp">
2092
<tabular ca="cl">
2093
<hline>
2094
Operator | Description @
2095
<hline>
2096
EQ or == | equal @
2097
NE or != | not equal @
2098
LT or < | less than @
2099
LE or <= | less than or equal @
2100
GT or > | greater than @
2101
GE or >= | greater than or equal @
2102
<hline>
2103
</tabular>
2104
<caption>
2105
<label id="comparison-operators">
2106
Comparison operators
2107
</caption>
2108
</table>
2109
2110
<p>
2111
2112
<table loc="htbp">
2113
<tabular ca="ll">
2114
<hline>
2115
Function | Description @
2116
<hline>
2117
abs(x) | absolute value @
2118
acos(x) | arccosine @
2119
acosh(x) | hyperbolic arccosine @
2120
asin(x) | arcsine @
2121
asinh(x) | hyperbolic arcsine @
2122
atan(x) | arctangent @
2123
atan2(y,x) | arc tangent of two variables @
2124
atanh(x) | hyperbolic arctangent @
2125
ceil(x) | greatest integer function @
2126
cos(x) | cosine @
2127
cosh(x) | hyperbolic cosine @
2128
exp(x) | e^x @
2129
fac(n) | factorial function, n! @
2130
floor(x) | least integer function @
2131
irand(n) | random integer less than n @
2132
ln(x) | natural log @
2133
log10(x) | log base 10 @
2134
log2(x) | base 2 logarithm of x @
2135
maxof(x,y) | returns greater of x and y @
2136
mesh(n) | mesh array (0 ... n - 1) @
2137
mesh(x1, x2, n) | mesh array of n equally spaced points between x1 and x2 inclusive @
2138
minof(x,y) | returns lesser of x and y @
2139
mod(x,y) | mod function (also x % y) @
2140
pi | the PI constant @
2141
rand | pseudo random number distributed uniformly on (0.0,1.0) @
2142
rand(n) | array of n random numbers @
2143
rint(x) | round to closest integer @
2144
sin(x) | sine function @
2145
sinh(x) | hyperbolic sine @
2146
sqr(x) | x^2 @
2147
sqrt(x) | x^0.5 @
2148
tan(x) | tangent function @
2149
tanh(x) | hyperbolic tangent @
2150
<hline>
2151
</tabular>
2152
<caption>
2153
<label id="functions">
2154
Functions
2155
</caption>
2156
</table>
2157
2158
<table loc="htbp">
2159
<tabular ca="ll">
2160
<hline>
2161
Function | Description @
2162
<hline>
2163
chdtr(df, x) | chi-square distribution @
2164
chdtrc(v, x) | complemented Chi-square distribution @
2165
chdtri(df, y) | inverse of complemented Chi-square distribution @
2166
erf(x) | error function @
2167
erfc(x) | complement of error function @
2168
fdtr(df1, df2, x) | F distribution function @
2169
fdtrc(x) | complemented F distribution @
2170
fdtri(x) | inverse of complemented F distribution @
2171
gdtr(a, b, x) | gamma distribution function @
2172
gdtrc(a, b, x) | complemented gamma distribution function @
2173
ndtr(x) | Normal distribution function @
2174
ndtri(x) | inverse of Normal distribution function @
2175
norm(x) | gaussian density function @
2176
pdtr(k, m) | Poisson distribution @
2177
pdtrc(k, m) | complemented Poisson distribution @
2178
pdtri(k, y) | inverse Poisson distribution @
2179
rnorm(xbar,s) | pseudo random number distributed N(xbar,s) @
2180
stdtr(k, t) | Student's t distribution @
2181
stdtri(k, p) | functional inverse of Student's t distribution @
2182
<hline>
2183
</tabular>
2184
<caption>
2185
<label id="stat-functions">
2186
Statistical functions
2187
</caption>
2188
</table>
2189
2190
<table loc="htbp">
2191
<tabular ca="ll">
2192
<hline>
2193
Function | Description @
2194
<hline>
2195
ai(x), bi(x) | Airy functions (two independent solutions of the differential equation <tt>y''(x) = xy</tt>) @
2196
beta(x) | beta function @
2197
chi(x) | hyperbolic cosine integral @
2198
ci(x) | cosine integral @
2199
dawsn(x) | Dawson's integral @
2200
ellie(phi, m) | incomplete elliptic integral of the second kind @
2201
ellik(phi, m) | incomplete elliptic integral of the first kind @
2202
ellpe(m) | complete elliptic integral of the second kind @
2203
ellpk(m) | complete elliptic integral of the first kind @
2204
expn(n, x) | exponential integral @
2205
fresnlc(x) | cosine Fresnel integral @
2206
fresnls(x) | sine Fresnel integral @
2207
gamma(x) | gamma function @
2208
hyp2f1(a, b, c, x) | Gauss hyper-geometric function @
2209
hyperg(a, b, x) | confluent hyper-geometric function @
2210
i0e(x) | modified Bessel function of order zero, exponentially scaled @
2211
i1e(x) | modified Bessel function of order one, exponentially scaled @
2212
igam(a, x) | incomplete gamma integral @
2213
igamc(a, x) | complemented incomplete gamma integral @
2214
igami(a, p) | inverse of complemented incomplete gamma integral @
2215
incbet(a, b, x) | incomplete beta integral @
2216
incbi(a, b, y) | Inverse of incomplete beta integral @
2217
iv(v, x) | modified Bessel function of order v @
2218
jv(v, x) | Bessel function of order v @
2219
k0e(x) | modified Bessel function, third kind, order zero, exponentially scaled @
2220
k1e(x) | modified Bessel function, third kind, order one, exponentially scaled @
2221
kn(n, x) | modified Bessel function, third kind, integer order @
2222
lbeta(x) | natural log of |beta(x)| @
2223
lgamma(x) | log of gamma function @
2224
psi(x) | psi (digamma) function @
2225
rgamma(x) | reciprocal gamma function @
2226
shi(x) | hyperbolic sine integral @
2227
si(x) | sine integral @
2228
spence(x) | dilogarithm @
2229
struve(v, x) | Struve function @
2230
yv(v, x) | Bessel function of order v @
2231
zeta(x, q) | Riemann zeta function of two arguments @
2232
zetac(x) | Riemann zeta function @
2233
<hline>
2234
</tabular>
2235
<caption>
2236
<label id="spec-functions">
2237
Special math functions
2238
</caption>
2239
</table>
2240
2241
<p>
2242
2243
<table loc="htbp">
2244
<tabular ca="cl">
2245
<hline>
2246
Function | Description @
2247
<hline>
2248
MIN(x) | min value of array x @
2249
MAX(x) | max value of array x @
2250
AVG(x) | average of array x @
2251
SD(x) | standard deviation of array x @
2252
SUM(x) | sum of all elements of array x @
2253
<hline>
2254
</tabular>
2255
<caption>
2256
<label id="aggregate-functions">
2257
Aggregate functions
2258
</caption>
2259
</table>
2260
2261
<sect1>Procedures
2262
<p>
2263
Methods of directly manipulating the data corresponding to the
2264
Data|Transformation menu are described in table
2265
<ref id="transformations">.
2266
2267
<table loc="htbp">
2268
<tabular ca="p{3cm}p{5cm}p{3.5cm}p{3cm}">
2269
<hline>
2270
Statement | Description | Types | Example @
2271
<hline>
2272
INTERPOLATE (set, mesh, method, strict) |
2273
interpolate <it>set</it> on a sampling <it>mesh</it> using <it>method</it>. <it>strict</it> flag controls whether result should be bound within the source set |
2274
vexpr <it>mesh</it>, <it>method</it>: one of LINEAR, SPLINE, and ASPLINE, onoff <it>strict</it> |
2275
INTERPOLATE (S0, S1.X, ASPLINE, OFF) @
2276
HISTOGRAM (set, bins, cumulative, normalize) |
2277
calculate histogram of <it>set</it> on defined <it>bins</it>. <it>cumulative</it> and <it>normalize</it> flags control whether to calculate cumulative and normalized (aka PDF) histograms, respectively. Data points are placed at upper limit of the bin |
2278
vexpr <it>bins</it>, onoff <it>cumulative</it>, onoff <it>normalize</it> |
2279
HISTOGRAM (S0, MESH(0, 1, 11), OFF, ON) @
2280
XCOR (set1, set2, maxlag, covar) |
2281
calculate cross-correlation (or -covariance if the <it>covar</it> flag is set) of <it>set1</it> with <it>set2</it> with maximum lag <it>maxlag</it>. |
2282
nexpr <it>maxlag</it>, onoff <it>covar</it> |
2283
XCOR (S0, S0, 50, OFF) @
2284
RESTRICT (set, restriction) |
2285
filter <it>set</it> according to logical <it>restriction</it>. The original set will be overwritten |
2286
vexpr <it>restriction</it> |
2287
RESTRICT (S0, x < 0) @
2288
RESTRICT (set, region, negate) |
2289
filter <it>set</it> by keeping only points lying inside/outside <it>region</it>. The original set will be overwritten |
2290
onoff <it>negate</it>|
2291
RESTRICT (S0, x < 0) @
2292
<hline>
2293
</tabular>
2294
<caption>
2295
<label id="transformations">
2296
Transformations
2297
</caption>
2298
</table>
2299
</p>
2300
2301
<p>
2302
Not finished yet...
2303
</p>
2304
2305
<sect1>Device parameters
2306
<p>
2307
For producing "hard copy", several parameters can be set via the command
2308
interpreter. They are summarized in table
2309
<ref id="device-parameters" name="Device parameters">.
2310
2311
<table loc="htbp">
2312
<tabular ca="lp{7cm}">
2313
<hline>
2314
Command | Description @
2315
<hline>
2316
PAGE SIZE xdim, ydim | set page dimensions (in pp) of all devices @
2317
PAGE RESIZE xdim, ydim | same as above plus rescale the current plot accordingly @
2318
DEVICE <it>"devname"</it> PAGE SIZE xdim, ydim | set page dimensions (in pp) of device <it>devname</it> @
2319
DEVICE <it>"devname"</it> DPI dpi | set device's dpi (dots per pixel) @
2320
DEVICE <it>"devname"</it> FONT onoff | enable/disable usage of built-in fonts for device <it>devname</it> @
2321
DEVICE <it>"devname"</it> FONT ANTIALIASING onoff | enable/disable font aliasing for device <it>devname</it> @
2322
DEVICE <it>"devname"</it> OP <it>"options"</it> | set device specific options (see <ref id="device-settings" name="Device-specific settings">) @
2323
HARDCOPY DEVICE <it>"devname"</it> | set device <it>devname</it> as current hardcopy device @
2324
PRINT TO <it>"filename"</it> | set print output to <it>filename</it> (but do not print) @
2325
PRINT TO DEVICE | set print output to hardcopy device (but do not print) @
2326
<hline>
2327
</tabular>
2328
<caption>
2329
<label id="device-parameters">
2330
Device parameters
2331
</caption>
2332
</table>
2333
2334
<sect1>Flow control
2335
2336
<p>
2337
<table loc="htbp">
2338
<tabular ca="lp{7cm}ll">
2339
<hline>
2340
Statement | Description | Types | Example @
2341
<hline>
2342
PRINT |
2343
execute print job |
2344
|
2345
PRINT @
2346
SLEEP <it>n</it> |
2347
sleep for <it>n</it> seconds |
2348
expr <it>n</it> |
2349
SLEEP(3) @
2350
EXIT(<it>status</it>) |
2351
cause normal program termination with exit status <it>status</it> |
2352
iexpr <it>status</it> |
2353
EXIT(0) @
2354
EXIT |
2355
cause normal program termination; same as EXIT(0) |
2356
|
2357
EXIT @
2358
HELP <it>url</it> |
2359
open a HTML document pointed to by <it>url</it> |
2360
qstr <it>url</it> |
2361
HELP "doc/FAQ.html" @
2362
HELP |
2363
open User's Guide |
2364
|
2365
HELP @
2366
<hline>
2367
</tabular>
2368
<caption>
2369
<label id="flow-control">
2370
Flow control
2371
</caption>
2372
</table>
2373
</p>
2374
2375
<sect1>Declarations
2376
<p>
2377
User-defined variables are set and used according to the syntax
2378
described in table <ref id="user-variables" name="User variables">.
2379
2380
<table loc="htbp">
2381
<tabular ca="lp{7cm}ll">
2382
<hline>
2383
Statement | Description | Types | Example @
2384
<hline>
2385
DEFINE <it>var</it> |
2386
define new scalar variable <it>var</it> |
2387
|
2388
DEFINE myvar @
2389
DEFINE <it>vvar</it>[] |
2390
define new vector variable <it>vvar</it> of zero length |
2391
|
2392
DEFINE myvvar[] @
2393
DEFINE <it>vvar</it>[<it>n</it>] |
2394
define new vector variable <it>vvar</it> of length <it>n</it> |
2395
nexpr <it>n</it> |
2396
DEFINE myvvar[10] @
2397
<hline>
2398
CLEAR <it>var</it> |
2399
undefine new variable <it>var</it> and deallocate associated storage |
2400
|
2401
CLEAR myvar @
2402
<hline>
2403
<it>vvar</it> LENGTH <it>n</it> |
2404
reallocate vector variable <it>vvar</it> |
2405
nexpr <it>n</it> |
2406
myvvar LENGTH 25 @
2407
<hline>
2408
</tabular>
2409
<caption>
2410
<label id="user-variables">
2411
User variables
2412
</caption>
2413
</table>
2414
</p>
2415
2416
<p>
2417
Not finished yet...
2418
</p>
2419
2420
<sect1>Graph properties
2421
<p>
2422
We divide the commands pertaining to the properties and appearance of
2423
graphs into those which directly manipulate the graphs and those that
2424
affect the appearance of graph elements---the parameters that can appear
2425
in a Grace project file.
2426
</p>
2427
2428
<sect2>Command operations
2429
<p>
2430
General graph creation/annihilation and control commands appear in
2431
table <ref id="graph-ops" name="Graph operations">.
2432
2433
<table loc="htbp">
2434
<tabular ca="p{3.5cm}p{4.5cm}p{3cm}p{3.5cm}">
2435
<hline>
2436
Statement | Description | Types | Example @
2437
<hline>
2438
FOCUS <it>graph</it> | Makes <it>graph</it> current and unhides it if necessary |
2439
graphsel <it>graph</it> | FOCUS G0 @
2440
KILL <it>graph</it> | Kills <it>graph</it> | graphsel <it>graph</it> | KILL G0 @
2441
ARRANGE(<it>nrows</it>, <it>ncols</it>, <it>offset</it>, <it>hgap</it>, <it>vgap</it>) |
2442
Arrange existing graphs (or add extra if needed) to form an <it>nrows</it> by <it>ncols</it> matrix, leaving <it>offset</it> at each page edge with <it>hgap</it> and <it>vgap</it> relative horizontal and vertical spacings |
2443
nexpr <it>nrows</it>, <it>ncols</it>, expr <it>offset</it>, <it>hgap</it>, <it>vgap</it> |
2444
ARRANGE(2, 2, 0.1, 0.15, 0.2) @
2445
ARRANGE(<it>nrows</it>, <it>ncols</it>, <it>offset</it>, <it>hgap</it>, <it>vgap</it>, <it>hvinv</it>, <it>hinv</it>, <it>vinv</it>) |
2446
Same as above, plus additional <it>hvinv</it>, <it>hinv</it>, and <it>vinv</it> flags allowing to alter the order of the matrix filling |
2447
nexpr <it>nrows</it>, <it>ncols</it>, expr <it>offset</it>, <it>hgap</it>, <it>vgap</it>, onoff <it>hvinv</it>, <it>hinv</it>, <it>vinv</it> |
2448
ARRANGE(2, 2, 0.1, 0.15, 0.2, ON, OFF, ON) @
2449
ARRANGE(<it>nrows</it>, <it>ncols</it>, <it>offset</it>, <it>hgap</it>, <it>vgap</it>, <it>hvinv</it>, <it>hinv</it>, <it>vinv</it>, <it>snake</it>) |
2450
Same as above, plus additional <it>snake</it> flag allowing to fill the matrix in a snake-like fashion |
2451
nexpr <it>nrows</it>, <it>ncols</it>, expr <it>offset</it>, <it>hgap</it>, <it>vgap</it>, onoff <it>hvinv</it>, <it>hinv</it>, <it>vinv</it>, <it>snake</it> |
2452
ARRANGE(2, 2, 0.1, 0.15, 0.2, ON, OFF, ON, ON) @
2453
</tabular>
2454
<caption>
2455
<label id="graph-ops">
2456
Graph operations
2457
</caption>
2458
</table>
2459
</p>
2460
<sect2>Parameter settings
2461
<p>
2462
Setting the active graph and its type is accomplished with the commands
2463
found in table <ref id="graphsel-pars" name="Graph selection parameters">.
2464
2465
<table loc="htbp">
2466
<tabular ca="p{3.25cm}p{4.5cm}p{3.5cm}p{3.25cm}">
2467
<hline>
2468
Statement | Description | Types | Example @
2469
<hline>
2470
WITH <it>graph</it> | Makes <it>graph</it> current |
2471
graphsel <it>graph</it> | WITH G0 @
2472
TYPE <it>type</it> | Sets <it>type</it> of current graph |
2473
graphtype <it>type</it> |TYPE XY @
2474
<it>graph</it> onoff| (De)Activates selected <it>graph</it> | graphsel <it>graph</it>, onoff | G0 ON @
2475
<it>graph</it> HIDDEN onoff | Hides selected <it>graph</it> | graphsel <it>graph</it>, onoff | G1 HIDDEN TRUE @
2476
<it>graph</it> TYPE <it>type</it> | Sets <it>type</it> of <it>graph</it> |
2477
graphsel <it>graph</it>, graphtype <it>type</it> | G0 TYPE XYDY @
2478
</tabular>
2479
<caption>
2480
<label id="graphsel-pars">
2481
Graph selection parameters
2482
</caption>
2483
</table>
2484
2485
The axis range and scale of the current graph as well as its location
2486
on the plot viewport are set with the commands listed in table
2487
<ref id="graphaxis-pars" name="Axis parameters">.
2488
<table loc="htbp">
2489
<tabular ca="p{3.25cm}p{4.5cm}p{3.5cm}p{3.25cm}">
2490
<hline>
2491
Statement | Description | Types | Example @
2492
<hline>
2493
WORLD XMIN <it>xmin</it> | Sets minimum value of current graph's x axis to <it>xmin</it> |
2494
expr <it>xmin</it> | WORLD XMIN -10 @
2495
WORLD XMAX <it>xmax</it> | Sets maximum value of current graph's x axis to <it>xmin</it> |
2496
expr <it>xmax</it> | WORLD XMAX 22.5 @
2497
WORLD YMIN <it>ymin</it> | Sets minimum value of current graph's y axis to <it>ymin</it> |
2498
expr <it>ymin</it> | WORLD YMIN 0 @
2499
WORLD YMAX <it>ymax</it> | Sets maximum value of current graph's y axis to <it>ymax</it> |
2500
expr <it>ymax</it> | WORLD YMAX 1e4 @
2501
VIEW XMIN <it>xmin</it> | Sets left edge of current graph at x=<it>xmin</it> in the viewport |
2502
expr <it>xmin</it>| VIEW XMIN .2 @
2503
VIEW XMAX <it>xmax</it> | Sets right edge of current graph at x=<it>xmax</it> in the viewport |
2504
expr <it>xmax</it>| VIEW XMAX 1.0 @
2505
VIEW YMIN <it>ymin</it> | Sets bottom edge of current graph at y=<it>ymin</it> in the viewport |
2506
expr <it>ymin</it>| VIEW YMIN .25 @
2507
VIEW YMAX <it>ymax</it> | Sets top edge of current graph at y=<it>ymax</it> in the viewport |
2508
expr <it>ymax</it>| VIEW YMAX .75 @
2509
XAXES SCALE <it>type</it> | Set scaling of the x axes to <it>type</it> |
2510
<it>type</it>: one of NORMAL, LOGARITHMIC, or RECIPROCAL | XAXES SCALE NORMAL @
2511
YAXES SCALE <it>type</it> | Set scaling of the y axes to <it>type</it> |
2512
<it>type</it>: one of NORMAL, LOGARITHMIC, or RECIPROCAL | YAXES SCALE LOGARITHMIC @
2513
XAXES INVERT onoff | If ON, draws xmin to xmax from right to left |
2514
onoff | XAXES INVERT OFF @
2515
YAXES INVERT onoff | If ON, draws ymin to ymax from top to bottom |
2516
onoff | YAXES INVERT OFF @
2517
AUTOSCALE ONREAD <it>type</it> | Set automatic scaling on read according to <it>type</it> |
2518
<it>type</it>: one of NONE, XAXES, YAXES, XYAXES | AUTOSCALE ONREAD NONE @
2519
</tabular>
2520
<caption>
2521
<label id="graphaxis-pars">
2522
Axis parameters
2523
</caption>
2524
</table>
2525
2526
The commands to set the appearance and textual content of titles and
2527
legends are given in table
2528
<ref id="graphlegend-pars" name="Titles and legends">.
2529
2530
<table loc="htbp">
2531
<tabular ca="p{3.5cm}p{4.5cm}p{3.25cm}p{3.25cm}">
2532
<hline>
2533
Statement | Description | Types | Example @
2534
<hline>
2535
TITLE <it>title</it> | Sets the title of current graph |
2536
qstr <it>title</it> | TITLE "Foo" @
2537
TITLE FONT <it>font</it> | Selects font of title string |
2538
fontsel <it>font</it> | TITLE FONT 1 @
2539
TITLE SIZE <it>size</it> | Sets size of title string |
2540
expr <it>size</it> | TITLE SIZE 1.5 @
2541
TITLE COLOR <it>color</it> | Sets color of title string |
2542
colorsel <it>color</it> | TITLE COLOR 1 @
2543
SUBTITLE <it>subtitle</it> | Sets the subtitle of current graph |
2544
qstr <it>subtitle</it> | SUBTITLE "Bar" @
2545
SUBTITLE FONT <it>font</it> | Selects font of subtitle string |
2546
fontsel <it>font</it> | SUBTITLE FONT "Times-Italic" @
2547
SUBTITLE SIZE <it>size</it> | Sets size of subtitle string |
2548
expr <it>size</it> | SUBTITLE SIZE .60 @
2549
SUBTITLE COLOR <it>color</it> | Sets color of subtitle string |
2550
colorsel <it>color</it> | SUBTITLE COLOR "blue" @
2551
LEGEND onoff | Toggle legend display |onoff | LEGEND ON @
2552
LEGEND LOCTYPE <it>type</it> | Posistion legend in <it>type</it> coordinates |
2553
<it>type</it>: either WORLD or VIEW | LEGEND LOCTYPE WORLD @
2554
LEGEND <it>xloc, yloc</it> | Set location of legend box (upper left corner) |
2555
expr <it>xloc, yloc</it> | LEGEND .5,.75 @
2556
LEGEND FONT <it>font</it>| Set legend font type |
2557
fontsel <it>font</it> | LEGEND FONT "Helvetica" @
2558
LEGEND CHAR SIZE <it>size</it> | Sets size of legend label characters (1 is normal)|
2559
expr <it>size</it> | LEGEND CHAR SIZE .30 @
2560
LEGEND <it>color</it>| Set color of legend text |
2561
colorsel <it>color</it> | LEGEND COLOR 1 @
2562
LEGEND VGAP <it>gap</it> | Sets vertical gap between legend entries |
2563
nexpr <it>gap</it> | LEGEND VGAP 1 @
2564
LEGEND HGAP <it>gap</it> | Sets horizontal gap between symbol and description |
2565
nexpr <it>gap</it> | LEGEND HGAP 4 @
2566
LEGEND LENGTH <it>length</it>| Sets <it>length</it> of legend|
2567
nexpr <it>length</it> | LEGEND LENGTH 5 @
2568
LEGEND INVERT onoff | Determines relationship between order of sets and order of legend labels |
2569
onoff | LEGEND INVERT true @
2570
LEGEND BOX onoff | Determines if the legend bounding box is drawn |
2571
onoff | LEGEND BOX off @
2572
LEGEND BOX COLOR <it>color</it> | Sets color of legend bounding box | colorsel <it>color</it> |
2573
LEGEND BOX COLOR 1@
2574
LEGEND BOX PATTERN <it>pattern</it>| Sets pattern of legend bounding box | patternsel <it>pattern</it> |
2575
LEGEND BOX PATTERN 2@
2576
LEGEND BOX LINESTYLE <it>style</it>| Sets line style of bounding box |nexpr <it>style</it> |
2577
LEGEND BOX LINESTYLE 1 @
2578
LEGEND BOX LINEWIDTH <it>width</it>| Sets line width of bounding box|nexpr <it>width</it> |
2579
LEGEND BOX LINEWIDTH 2 @
2580
LEGEND BOX FILL onoff | Determines if the legend bounding box is filled |
2581
onoff | LEGEND BOX FILL false @
2582
LEGEND BOX FILL COLOR <it>color</it> | Sets color of legend box fill | colorsel <it>color</it> |
2583
LEGEND BOX COLOR 3 @
2584
LEGEND BOX FILL <it>pattern</it>| Sets pattern of legend box fill |patternsel <it>pattern</it> |
2585
LEGEND BOX FILL PATTERN 1@
2586
</tabular>
2587
<caption>
2588
<label id="graphlegend-pars">
2589
Titles and legends
2590
</caption>
2591
</table>
2592
</p>
2593
<p>
2594
Not finished yet...
2595
</p>
2596
2597
<sect1>Set properties
2598
<p>
2599
Again, as with the graphs, we separate those parser commands that
2600
manipulate the data in a set from the commands that determine
2601
parameters---elements that are saved in a project file.
2602
2603
<sect2>Commands
2604
<p>
2605
Operations for set I/O are summarized in table
2606
<ref id="set-io" name="Set input, output, and creation">. (Note that
2607
this is incomplete and only lists <it>input</it> commands at the moment.)
2608
2609
<table loc="htbp">
2610
<tabular ca="p{3.5cm}p{4.5cm}p{3cm}p{3.5cm}">
2611
<hline>
2612
Statement | Description | Types | Example @
2613
<hline>
2614
READ <it>file</it> | Reads <it>file</it> as a single set |
2615
qstr <it>file</it> | READ "foo.dat" @
2616
READ <it>settype</it> <it>file</it> | Reads <it>file</it> into a single set of type <it>settype</it> |
2617
xytype <it>settype</it>, qstr <it>file</it> | READ xydy "bar.dat" @
2618
READ NXY <it>file</it> | Reads <it>file</it> as NXY data |
2619
qstr <it>file</it> | READ NXY "gad.dat" @
2620
READ BLOCK <it>file</it> | Reads <it>file</it> as block data |
2621
qstr <it>file</it> | READ BLOCK "zooks.dat" @
2622
BLOCK <it>settype</it> <it>columns</it> | Forms a data set of type <it>settype</it> using <it>columns</it> from current block data file. |
2623
xytype <it>settype</it>, qstr <it>columns</it> | BLOCK xydxdy "0:2:1:3" @
2624
</tabular>
2625
<caption>
2626
<label id="set-io">
2627
Set input, output, and creation
2628
</caption>
2629
</table>
2630
2631
The parser commands analogous to the Data|Data set operations dialogue
2632
can be found in table <ref id="set-ops" name="Set operations">.
2633
<table loc="htbp">
2634
<tabular ca="p{3.5cm}p{4.5cm}p{3cm}p{3.5cm}">
2635
<hline>
2636
Statement | Description | Types | Example @
2637
<hline>
2638
COPY <it>src</it> TO <it>dest</it> | Copies <it>src</it> to <it>dest</it>|
2639
setsel <it>src,dest</it> | COPY S0 TO S1 @
2640
MOVE <it>src</it> TO <it>dest</it> | Moves <it>src</it> to <it>dest</it> |
2641
setsel <it>src,dest</it> | MOVE G0.S0 TO G1.S0 @
2642
SWAP <it>src</it> AND <it>dest</it> | Interchanges <it>src</it> and <it>dest</it> |
2643
setsel <it>src,dest</it> | SWAP G0.S0 AND G0.S1 @
2644
KILL <it>set</it> | Kills <it>set</it> | setsel <it>set</it> | KILL G0.S0 @
2645
</tabular>
2646
<caption>
2647
<label id="set-ops">
2648
Set operations
2649
</caption>
2650
</table>
2651
</p>
2652
<p>
2653
Not Finished yet...
2654
2655
<sect2>Parameter settings
2656
<p>
2657
Not written yet...
2658
2659
<!-- **************************************** -->
2660
<sect>Advanced topics
2661
<p>
2662
2663
<sect1>Fonts<label id="fonts">
2664
<p>
2665
For all devices, Grace uses Type1 fonts. Both PFA (ASCII) and PFB
2666
(binary) formats can be used.
2667
<p>
2668
<sect2>Font configuration
2669
<p>
2670
The file responsible for the font configurations of Grace is
2671
<tt>fonts/FontDataBase</tt>. The first line contains a positive integer
2672
specifying the number of fonts declared in that file. All remaining lines
2673
contain declarations of one font each, composed out of three fields:
2674
<enum>
2675
<item> Font name. The name will appear in the font selector controls.
2676
Also, backend devices that has built-in fonts, will be given the
2677
name as a font identifier.
2678
<item> Font fall-back. Grace will try to use this in case the real
2679
font is not found.
2680
<item> Font filename. The file with the font outline data.
2681
</enum>
2682
<p>
2683
Here is the default <tt>FontDataBase</tt> file:
2684
<tscreen><code>
2685
14
2686
Times-Roman Times-Roman n021003l.pfb
2687
Times-Italic Times-Italic n021023l.pfb
2688
Times-Bold Times-Bold n021004l.pfb
2689
Times-BoldItalic Times-BoldItalic n021024l.pfb
2690
Helvetica Helvetica n019003l.pfb
2691
Helvetica-Oblique Helvetica-Oblique n019023l.pfb
2692
Helvetica-Bold Helvetica-Bold n019004l.pfb
2693
Helvetica-BoldOblique Helvetica-BoldOblique n019024l.pfb
2694
Courier Courier n022003l.pfb
2695
Courier-Oblique Courier-Oblique n022023l.pfb
2696
Courier-Bold Courier-Bold n022004l.pfb
2697
Courier-BoldOblique Courier-BoldOblique n022024l.pfb
2698
Symbol Symbol s050000l.pfb
2699
ZapfDingbats ZapfDingbats d050000l.pfb
2700
</code></tscreen>
2701
<p>
2702
2703
<sect2>Font data files
2704
<p>
2705
For text rastering, three types of files are used.
2706
<enum>
2707
<item> <tt>.pfa</tt>-/<tt>.pfb</tt>-files: These contain the character
2708
outline descriptions. The files are assumed to be in the
2709
<tt>fonts/type1</tt> directory; these are the filenames
2710
specified in the <tt>FontDataBase</tt> configuration file.
2711
<item> <tt>.afm</tt>-files: These contain high-precision font metric
2712
descriptions as well as some extra information, such as kerning
2713
and ligature information for a particular font. It is assumed
2714
that the filename of a font metric file has same basename as the
2715
respective font outline file, but with the <tt>.afm</tt>
2716
extension; the metric files are expected to be found in the
2717
<tt>fonts/type1</tt> directory, too.
2718
<item> <tt>.enc</tt>-files: These contain encoding arrays in a special
2719
but simple form. They are only needed if someone wants to load
2720
a special encoding to re-encode a font. Their place is
2721
<tt>fonts/enc</tt>
2722
</enum>
2723
2724
<sect2>Custom fonts
2725
<p>
2726
It is possible to use custom fonts with Grace. One mostly needs to use
2727
extra fonts for the purpose of localization. For many European
2728
languages, the standard fonts supplied with Grace should contain all the
2729
characters needed, but encoding may have to be adjusted. This is done by
2730
putting a <tt>Default.enc</tt> file with proper encoding scheme into the
2731
<tt>fonts/enc</tt> directory. Grace comes with a few encoding files in
2732
the directory; more can be easily found on the Internet. (If the
2733
<tt>Default.enc</tt> file doesn't exist, the IsoLatin1 encoding will be
2734
used). Notice that for fonts having an encoding scheme in themselves
2735
(such as the Symbol font, and many nationalized fonts) the default
2736
encoding is ignored.
2737
<p>
2738
If you do need to use extra fonts, you should modify the
2739
<tt>FontDataBase</tt> file accordingly, obeying its format. However,
2740
if you are going to exchange Grace project files with other people who
2741
do not have the extra fonts configured, an important thing is to define
2742
reasonable fall-back font names.
2743
<p>
2744
For example, let us assume I use Hebrew fonts, and the configuration file
2745
has lines like these:
2746
<tscreen><code>
2747
...
2748
Courier-Hebrew Courier courh___.pfa
2749
Courier-Hebrew-Oblique Courier-Oblique courho__.pfa
2750
...
2751
</code></tscreen>
2752
My colleague, who lives in Russia, uses Cyrillic fonts with Grace
2753
configured like this:
2754
<tscreen><code>
2755
...
2756
Cronix-Courier Courier croxc.pfb
2757
Cronix-Courier-Oblique Courier-Oblique croxco.pfb
2758
...
2759
</code></tscreen>
2760
The font mapping information (Font name <-> Font fall-back) is
2761
stored in the Grace project files. Provided that all the localized fonts
2762
have English characters in the lower part of the ASCII table unmodified,
2763
I can send my friend files (with no Hebrew characters, of course) and be
2764
sure they render correctly on his computer.
2765
<p>
2766
Thus, with properly configured national fonts, you can make localized
2767
annotations for plots intended for internal use of your institution,
2768
while being able to exchange files with colleagues from abroad. People
2769
who ever tried to do this with MS Office applications should appreciate
2770
the flexibility :-).
2771
2772
<sect1>Interaction with other applications
2773
<p>
2774
2775
<sect2>Using pipes
2776
<p>
2777
2778
<sect2>Using grace_np library
2779
<p>
2780
The grace_np library is a set of compiled functions that
2781
allows you to launch and drive a Grace subprocess from your C or
2782
Fortran application. Functions are provided to start the
2783
subprocess, to send it commands or data, to stop it or detach
2784
from it.
2785
2786
<table loc="htbp">
2787
<tabular ca="p{4.5cm}lp{5.5cm}">
2788
<hline>
2789
Function | Arguments | Description @
2790
<hline>
2791
int GraceOpenVA | (char *<it>exe</it>, int <it>buf_size</it>, ...)
2792
| launch a Grace executable <it>exe</it> and open a communication channel with it using <it>buf_size</it> bytes for data buffering. The remaining NULL-terminated list of options is command line arguments passed to the Grace process @
2793
int GraceOpen | (int <it>buf_size</it>)
2794
| equivalent to GraceOpenVA("xmgrace", buf_size, "-noask", NULL) @
2795
int GraceIsOpen | (void) | test if a Grace subprocess is currently connected @
2796
int GraceClose | (void) | close the communication channel and exit the Grace subprocess @
2797
int GraceClosePipe | (void) | close the communication channel and leave the Grace subprocess alone @
2798
<hline>
2799
int GraceFlush | (void) | flush all the data remaining in the buffer @
2800
int GracePrintf | (const char* <it>format</it>, ...)
2801
| format a command and send it to the Grace subprocess @
2802
int GraceCommand | (const char* <it>cmd</it>)
2803
| send an already formated command to the Grace subprocess @
2804
<hline>
2805
GraceErrorFunctionType GraceRegisterErrorFunction
2806
| (GraceErrorFunctionType <it>f</it>)
2807
| register a user function <it>f</it> to display library errors @
2808
<hline>
2809
</tabular>
2810
<caption>
2811
<label id="C functions"> grace_np library C functions.
2812
</caption>
2813
</table>
2814
2815
<table loc="htbp">
2816
<tabular ca="p{5cm}lp{5cm}">
2817
<hline>
2818
Function | Arguments | Description @
2819
<hline>
2820
integer GraceOpenF | (integer <it>buf_size</it>)
2821
| launch a Grace subprocess and open a communication channel with it @
2822
integer GraceIsOpenF | (void) | test if a Grace subprocess is currently connected @
2823
integer GraceCloseF | (void) | close the communication channel and exit the Grace subprocess @
2824
integer GraceClosePipeF | (void) | close the communication channel and leave the Grace subprocess alone @
2825
<hline>
2826
integer GraceFlushF | (void) | flush all the data remaining in the buffer @
2827
integer GraceCommandF | (character*(*) <it>cmd</it>)
2828
| send an already formatted command to the Grace subprocess @
2829
<hline>
2830
GraceFortranFunctionType GraceRegisterErrorFunctionF
2831
| (GraceFortranFunctionType <it>f</it>)
2832
| register a user function <it>f</it> to display library errors @
2833
<hline>
2834
</tabular>
2835
<caption>
2836
<label id="fortran functions"> grace_np library F77 functions.
2837
</caption>
2838
</table>
2839
2840
<p> There is no fortran equivalent for the GracePrintf function,
2841
you should format all the data and commands yourself before
2842
sending them with GraceCommandF.
2843
2844
The Grace subprocess listen for the commands you send and
2845
interpret them as if they were given in a batch file. You can
2846
send any command you like (redraw, autoscale, ...). If you want
2847
to send data, you should include them in a command like "g0.s0
2848
point 3.5, 4.2".
2849
2850
Apart from the fact it monitors the data sent via an anonymous
2851
pipe, the Grace subprocess is a normal process. You can interact
2852
with it through the GUI. Note that no error can be sent back to
2853
the parent process. If your application send erroneous commands,
2854
an error popup will be displayed by the subprocess.
2855
2856
If you exit the subprocess while the parent process is still
2857
using it, the broken pipe will be detected. An error code will
2858
be returned to every further call to the library (but you can
2859
still start a new process if you want to manage this situation).
2860
2861
Here is an example use of the library, you will find this
2862
program in the distribution.
2863
2864
<tscreen><code>
2865
#include <stdlib.h>
2866
#include <stdio.h>
2867
#include <unistd.h>
2868
#include <grace_np.h>
2869
2870
#ifndef EXIT_SUCCESS
2871
# define EXIT_SUCCESS 0
2872
#endif
2873
2874
#ifndef EXIT_FAILURE
2875
# define EXIT_FAILURE -1
2876
#endif
2877
2878
void my_error_function(const char *msg)
2879
{
2880
fprintf(stderr, "library message: \"%s\"\n", msg);
2881
}
2882
2883
int
2884
main(int argc, char* argv[])
2885
{
2886
int i;
2887
2888
GraceRegisterErrorFunction(my_error_function);
2889
2890
/* Start Grace with a buffer size of 2048 and open the pipe */
2891
if (GraceOpen(2048) == -1) {
2892
fprintf(stderr, "Can't run Grace. \n");
2893
exit(EXIT_FAILURE);
2894
}
2895
2896
/* Send some initialization commands to Grace */
2897
GracePrintf("world xmax 100");
2898
GracePrintf("world ymax 10000");
2899
GracePrintf("xaxis tick major 20");
2900
GracePrintf("xaxis tick minor 10");
2901
GracePrintf("yaxis tick major 2000");
2902
GracePrintf("yaxis tick minor 1000");
2903
GracePrintf("s0 on");
2904
GracePrintf("s0 symbol 1");
2905
GracePrintf("s0 symbol size 0.3");
2906
GracePrintf("s0 symbol fill pattern 1");
2907
GracePrintf("s1 on");
2908
GracePrintf("s1 symbol 1");
2909
GracePrintf("s1 symbol size 0.3");
2910
GracePrintf("s1 symbol fill pattern 1");
2911
2912
/* Display sample data */
2913
for (i = 1; i <= 100 && GraceIsOpen(); i++) {
2914
GracePrintf("g0.s0 point %d, %d", i, i);
2915
GracePrintf("g0.s1 point %d, %d", i, i * i);
2916
/* Update the Grace display after every ten steps */
2917
if (i % 10 == 0) {
2918
GracePrintf("redraw");
2919
/* Wait a second, just to simulate some time needed for
2920
calculations. Your real application shouldn't wait. */
2921
sleep(1);
2922
}
2923
}
2924
2925
if (GraceIsOpen()) {
2926
/* Tell Grace to save the data */
2927
GracePrintf("saveall \"sample.agr\"");
2928
2929
/* Flush the output buffer and close Grace */
2930
GraceClose();
2931
2932
/* We are done */
2933
exit(EXIT_SUCCESS);
2934
} else {
2935
exit(EXIT_FAILURE);
2936
}
2937
}
2938
2939
</code></tscreen>
2940
2941
<sect1>FFTW tuning<label id="fftw-tuning">
2942
<p>
2943
When the FFTW capabilities are compiled in, Grace looks at two environment
2944
variables to decide what to do with the FFTW 'wisdom' capabilities.
2945
First, a quick summary of what this is. The FFTW package is capable of
2946
adaptively determining the most efficient factorization of a set to give
2947
the fastest computation. It can store these factorizations as 'wisdom',
2948
so that if a transform of a given size is to be repeated, it is does not
2949
have to re-adapt. The good news is that this seems to work very well.
2950
The bad news is that, the first time a transform of a given size is
2951
computed, if it is not a sub-multiple of one already known, it takes a LONG
2952
time (seconds to minutes).
2953
<p>
2954
The first environment variable is GRACE_FFTW_WISDOM_FILE. If this is set
2955
to the name of a file which can be read and written (e.g.,
2956
$HOME/.grace_fftw_wisdom) then Grace will automatically create this file
2957
(if needed) and maintain it. If the file is read-only, it will be read,
2958
but not updated with new wisdom. If the symbol GRACE_FFTW_WISDOM_FILE
2959
either doesn't exist, or evaluates to an empty string, Grace will drop the
2960
use of wisdom, and will use the fftw estimator (FFTW_ESTIMATE flag sent to
2961
the planner) to guess a good factorization, instead of adaptively
2962
determining it.
2963
<p>
2964
The second variable is GRACE_FFTW_RAM_WISDOM. If this variable is defined
2965
to be non-zero, and GRACE_FFTW_WISDOM_FILE variable is not defined (or is
2966
an empty string), Grace will use wisdom internally, but maintain no
2967
persistent cache of it. This will result in very slow execution times the
2968
first time a transform is executed after Grace is started, but very fast
2969
repeats. I am not sure why anyone would want to use wisdom without
2970
writing it to disk, but if you do, you can use this flag to enable it.
2971
<p>
2972
2973
<sect1>DL modules <label id="dl-modules">
2974
<p>
2975
Grace can access external functions present
2976
in either system or third-party shared libraries or modules
2977
specially compiled for use with Grace.
2978
2979
<sect2>Function types
2980
<p>
2981
One must make sure, however, that the external function is of one
2982
of supported by Grace types:
2983
<table loc="htbp">
2984
<tabular ca="ll">
2985
<hline>
2986
Grace type | Description @
2987
<hline>
2988
f_of_i | a function of 1 <tt/int/ variable @
2989
f_of_d | a function of 1 <tt/double/ variable @
2990
f_of_nn | a function of 2 <tt/int/ parameters @
2991
f_of_nd | a function of 1 <tt/int/ parameter and 1 <tt/double/ variable @
2992
f_of_dd | a function of 2 <tt/double/ variables @
2993
f_of_nnd | a function of 2 <tt/int/ parameters and 1 <tt/double/ variable @
2994
f_of_ppd | a function of 2 <tt/double/ parameters and 1 <tt/double/ variable @
2995
f_of_pppd | a function of 3 <tt/double/ parameters and 1 <tt/double/ variable @
2996
<hline>
2997
</tabular>
2998
<caption>
2999
<label id="grace-types">
3000
Grace types for external functions
3001
</caption>
3002
</table>
3003
3004
The return values of functions are assumed to be of the
3005
<tt/double/ type.
3006
3007
Note, that there is no difference from the point of view of
3008
function prototype between parameters and variables; the
3009
difference is in the way Grace treats them - an attempt to use
3010
a vector expression as a parameter argument will result in a
3011
parse error.
3012
3013
Let us consider few examples.
3014
3015
<sect2>Examples
3016
<p>
3017
Caution: the examples provided below (paths and compiler flags)
3018
are valid for Linux/ELF with gcc. On other operating systems,
3019
you may need to refer to compiler/linker manuals or ask a guru.
3020
3021
<sect3>Example 1
3022
<p>
3023
Suppose I want to use function <tt/pow(x,y)/ from the Un*x math
3024
library (libm). Of course, you can use the "^" operator defined
3025
in the Grace language, but here, for the sake of example, we
3026
want to access the function directly.
3027
3028
The command to make it accessible by Grace is
3029
<tscreen>
3030
USE "pow" TYPE f_of_dd FROM "/usr/lib/libm.so"
3031
</tscreen>
3032
3033
Try to plot y = pow(x,2) and y = x^2 graphs (using, for
3034
example, "create new -> Formula" from any <ref name="set
3035
selector" id="set-selector">) and compare.
3036
3037
<sect3>Example 2
3038
<p>
3039
Now, let us try to write a function ourselves. We will define
3040
function <tt/my_function/ which simply returns its (second)
3041
argument multiplied by integer parameter transferred as the
3042
first argument.
3043
3044
In a text editor, type in the following C code and save it as
3045
"my_func.c":
3046
3047
<tscreen><code>
3048
double my_function (int n, double x)
3049
{
3050
double retval;
3051
retval = (double) n * x;
3052
return (retval);
3053
}
3054
</code></tscreen>
3055
3056
OK, now compile it:
3057
3058
<tscreen><code>
3059
$gcc -c -fPIC my_func.c
3060
$gcc -shared my_func.o -o /tmp/my_func.so
3061
</code></tscreen>
3062
3063
(You may strip it to save some disk space):
3064
3065
<tscreen><code>
3066
$strip /tmp/my_func.so
3067
</code></tscreen>
3068
3069
That's all! Ready to make it visible to Grace as "myf" - we are
3070
too lazy to type the very long string "my_function" many times.
3071
3072
<tscreen>
3073
USE "my_function" TYPE f_of_nd FROM "/tmp/my_func.so" ALIAS "myf"
3074
</tscreen>
3075
3076
3077
<sect3>Example 3
3078
<p>
3079
A more serious example. There is a special third-party library
3080
available on your system which includes a very important for
3081
you yet very difficult-to-program from the scratch function
3082
that you want to use with Grace. But, the function prototype
3083
is NOT one of any predefined <ref name="types"
3084
id="grace-types">. The solution is to write a simple function
3085
wrapper. Here is how:
3086
3087
Suppose, the name of the library is "special_lib" and the
3088
function you are interested in is called "special_func" and
3089
according to the library manual, should be accessed as <tt/void
3090
special_func(double *input, double *output, int parameter)/.
3091
The wrapper would look like this:
3092
3093
<tscreen><code>
3094
double my_wrapper(int n, double x)
3095
{
3096
extern void special_func(double *x, double *y, int n);
3097
double retval;
3098
(void) special_func(&x, &retval, n);
3099
return (retval);
3100
}
3101
</code></tscreen>
3102
3103
Compile it:
3104
3105
<tscreen><code>
3106
$gcc -c -fPIC my_wrap.c
3107
$gcc -shared my_wrap.o -o /tmp/my_wrap.so -lspecial_lib -lblas
3108
$strip /tmp/my_wrap.so
3109
</code></tscreen>
3110
3111
Note that I added <tt/-lblas/ assuming that the special_lib
3112
library uses some functions from the BLAS. Generally, you have
3113
to add <it>all</it> libraries which your module depends on (and
3114
all libraries those libraries rely upon etc.), as if you wanted
3115
to compile a plain executable.
3116
3117
Fine, make Grace aware of the new function
3118
3119
<tscreen>
3120
USE "my_wrapper" TYPE f_of_nd FROM "/tmp/my_wrap.so" ALIAS "special_func"
3121
</tscreen>
3122
3123
so we can use it with its original name.
3124
3125
<sect3>Example 4
3126
<p>
3127
An example of using Fortran modules.
3128
3129
Here we will try to achieve the same functionality as in
3130
Example 2, but with the help of F77.
3131
3132
<tscreen><code>
3133
DOUBLE PRECISION FUNCTION MYFUNC (N, X)
3134
IMPLICIT NONE
3135
INTEGER N
3136
DOUBLE PRECISION X
3137
C
3138
MYFUNC = N * X
3139
C
3140
RETURN
3141
END
3142
</code></tscreen>
3143
3144
As opposite to C, there is no way to call such a function from
3145
Grace directly - the problem is that in Fortran all arguments
3146
to a function (or subroutine) are passed by reference. So, we
3147
need a wrapper:
3148
3149
<tscreen><code>
3150
double myfunc_wrapper(int n, double x)
3151
{
3152
extern double myfunc_(int *, double *);
3153
double retval;
3154
retval = myfunc_(&n, &x);
3155
return (retval);
3156
}
3157
</code></tscreen>
3158
3159
Note that most of f77 compilers by default add underscore to
3160
the function names and convert all names to the lower case,
3161
hence I refer to the Fortran function <tt/MYFUNC/ from my C
3162
wrapper as <tt/myfunc_/, but in your case it can be different!
3163
3164
Let us compile the whole stuff:
3165
3166
<tscreen><code>
3167
$g77 -c -fPIC myfunc.f
3168
$gcc -c -fPIC myfunc_wrap.c
3169
$gcc -shared myfunc.o myfunc_wrap.o -o /tmp/myfunc.so -lf2c -lm
3170
$strip /tmp/myfunc.so
3171
</code></tscreen>
3172
3173
And finally, inform Grace about this new function:
3174
3175
<tscreen>
3176
USE "myfunc_wrapper" TYPE f_of_nd FROM "/tmp/myfunc.so" ALIAS "myfunc"
3177
</tscreen>
3178
3179
<sect2>Operating system issues
3180
<p>
3181
<sect3>OS/2
3182
<p>
3183
In general the method outlined in the examples above can be
3184
used on OS/2, too. However you have to create a DLL (Dynamic Link Library)
3185
which is a bit more tricky on OS/2 than on most Un*x systems.
3186
Since Grace was ported by using EMX we also use it to create
3187
the examples; however other development environments should work
3188
as well (ensure to use the _System calling convention!).
3189
We refer to Example 2 only. Example 1 might demonstrate
3190
that DLLs can have their entry points (i.e. exported functions)
3191
callable via ordinals only, so you might not know how to access a
3192
specific function without some research.
3193
First compile the source from Example 2 to "my_func.obj"
3194
3195
<tscreen>
3196
gcc -Zomf -Zmt -c my_func.c -o my_func.obj
3197
</tscreen>
3198
3199
Then you need to create a linker definition file "my_func.def"
3200
which contains some basic info about the DLL and declares
3201
the exported functions.
3202
3203
<tscreen><code>
3204
LIBRARY my_func INITINSTANCE TERMINSTANCE
3205
CODE LOADONCALL
3206
DATA LOADONCALL MULTIPLE NONSHARED
3207
DESCRIPTION 'This is a test DLL: my_func.dll'
3208
EXPORTS
3209
my_function
3210
</code></tscreen>
3211
3212
(don't forget about the 8 characters limit on the DLL name!).
3213
Finally link the DLL:
3214
3215
<tscreen>
3216
gcc my_func.obj my_func.def -o my_func.dll -Zdll -Zno-rte -Zmt -Zomf
3217
</tscreen>
3218
3219
(check out the EMX documentation about the compiler/linker flags
3220
used here!)
3221
To use this new library function within Grace you may either
3222
put the DLL in the LIBPATH and use the short form:
3223
3224
<tscreen>
3225
USE "my_function" TYPE f_of_nd FROM "my_func" ALIAS "myf"
3226
</tscreen>
3227
3228
or put it in an arbitrary path which you need to specify explicitly
3229
then:
3230
3231
<tscreen>
3232
USE "my_function" TYPE f_of_nd FROM "e:/foo/my_func.dll" ALIAS "myf"
3233
</tscreen>
3234
3235
(as for most system-APIs you may use the Un*x-like forward
3236
slashs within the path!)
3237
3238
<!-- ****** Appendices/references ************ -->
3239
<sect> References
3240
<p>
3241
3242
<sect1>Typesetting<label id="typesetting">
3243
<p>
3244
Grace permits quite complex typesetting on a per string basis.
3245
Any string displayed (titles, legends, tick marks,...) may contain
3246
special control codes to display subscripts, change fonts within the
3247
string etc.
3248
<p>
3249
3250
<table loc="htbp">
3251
<tabular ca="ll">
3252
<hline>
3253
Control code | Description @
3254
<hline>
3255
\f{x} | switch to font named "x" @
3256
\f{n} | switch to font number n @
3257
\f{} | return to original font @
3258
\R{x} | switch to color named "x" @
3259
\R{n} | switch to color number n @
3260
\R{} | return to original color @
3261
\#{x} | treat "x" (must be of even length) as list of hexadecimal char codes @
3262
\t{xx xy yx yy} | apply transformation matrix @
3263
\t{} | reset transformation matrix @
3264
\z{x} | zoom x times @
3265
\z{} | return to original zoom @
3266
\r{x} | rotate by x degrees @
3267
\l{x} | slant by factor x @
3268
\v{x} | shift vertically by x @
3269
\v{} | return to unshifted baseline @
3270
\V{x} | shift baseline by x @
3271
\V{} | reset baseline @
3272
\h{x} | horizontal shift by x @
3273
\n | new line @
3274
\u | begin underline @
3275
\U | stop underline @
3276
\o | begin overline @
3277
\O | stop overline @
3278
\Fk | enable kerning @
3279
\FK | disable kerning @
3280
\Fl | enable ligatures @
3281
\FL | disable ligatures @
3282
\m{n} | mark current position as n @
3283
\M{n} | return to saved position n @
3284
\dl | LtoR substring direction @
3285
\dr | RtoL substring direction @
3286
\dL | LtoR text advancing @
3287
\dR | RtoL text advancing @
3288
<hline>
3289
\x | switch to Symbol font (same as \f{Symbol}) @
3290
\+ | increase size (same as \z{1.19} ; 1.19 = sqrt(sqrt(2))) @
3291
\- | decrease size (same as \z{0.84} ; 0.84 = 1/sqrt(sqrt(2))) @
3292
\s | begin subscripting (same as \v{-0.4}\z{0.71}) @
3293
\S | begin superscripting (same as \v{0.6}\z{0.71}) @
3294
\T{xx xy yx yy} | same as \t{}\t{xx xy yx yy} @
3295
\Z{x} | absolute zoom x times (same as \z{}\z{x}) @
3296
\q | make font oblique (same as \l{0.25}) @
3297
\Q | undo oblique (same as \l{-0.25}) @
3298
\N | return to normal style (same as \v{}\t{}) @
3299
<hline>
3300
\\ | print \ @
3301
<hline>
3302
\n | switch to font number n (0-9) (deprecated) @
3303
\c | begin using upper 128 characters of set (deprecated) @
3304
\C | stop using upper 128 characters of set (deprecated) @
3305
<hline>
3306
</tabular>
3307
<caption>
3308
<label id="control-codes">
3309
Control codes.
3310
</caption>
3311
</table>
3312
3313
<p>
3314
Example:
3315
<p>
3316
F\sX\N(\xe\f{}) =
3317
sin(\xe\f{})\#{b7}e\S-X\N\#{b7}cos(\xe\f{})
3318
<p>
3319
prints roughly
3320
<tscreen><verb>
3321
-x
3322
F (e) = sin(e)·e ·cos(e)
3323
x
3324
</verb></tscreen>
3325
<p>
3326
using string's initial font and e prints as epsilon from the Symbol font.
3327
<p>
3328
NOTE:
3329
Characters from the upper half of the char table can be entered directly
3330
from the keyboard, using appropriate <tt>xmodmap(1)</tt> settings, or
3331
with the help of the font tool ("Window/Font tool").
3332
<p>
3333
3334
<sect1>Device-specific limitations<label id="device-limitations">
3335
<p>
3336
3337
Grace can output plots using several device backends. The list of
3338
available devices can be seen (among other stuff) by specifying the
3339
"-version" command line switch.
3340
<itemize>
3341
<item> X11, PostScript and EPS are full-featured devices
3342
<item> Raster drivers (PNM/JPEG/PNG):
3343
<itemize>
3344
<item> only even-odd fill rule is supported
3345
<item> patterned lines are not implemented
3346
</itemize>
3347
<item> PDF driver:
3348
<itemize>
3349
<item> patterned fills are not implemented
3350
<item> bitmapped text strings are not transparent
3351
</itemize>
3352
<item> MIF driver:
3353
the driver is a brand new one and still in beta test
3354
<itemize>
3355
<item> some of patterned fills not implemented
3356
<item> bitmapped text strings not implemented
3357
</itemize>
3358
<item> SVG driver:
3359
the driver is a brand new one and still in beta test
3360
<itemize>
3361
<item> patterned fills not implemented
3362
<item> bitmapped text strings not implemented
3363
</itemize>
3364
</itemize>
3365
3366
<p>
3367
3368
<sect1>Device-specific settings<label id="device-settings">
3369
<p>
3370
3371
Some of the output devices accept several configuration options. You can
3372
set the options by passing a respective string to the interpreter
3373
using the "DEVICE <it>"devname"</it> OP <it>"options"</it>" command (see
3374
<ref id="device-parameters" name="Device parameters">). A few options
3375
can be passed in one command, separated by commas.
3376
3377
<p>
3378
3379
<table loc="htbp">
3380
<tabular ca="ll">
3381
<hline>
3382
Command | Description @
3383
<hline>
3384
grayscale | set grayscale output @
3385
color | set color output @
3386
level1 | use only PS Level 1 subset of commands @
3387
level2 | use also PS Level 2 commands if needed @
3388
docdata:7bit | the document data is 7bit clean @
3389
docdata:8bit | the document data is 8bit clean @
3390
docdata:binary | the document data may be binary @
3391
xoffset:<it>x</it> | set page offset in X direction <it>x</it> pp @
3392
yoffset:<it>y</it> | set page offset in Y direction <it>y</it> pp @
3393
mediafeed:auto | default input tray @
3394
mediafeed:match | select input with media matching page dimensions @
3395
mediafeed:manual | manual media feed @
3396
hwresolution:on | set hardware resolution @
3397
hwresolution:off | do not set hardware resolution @
3398
<hline>
3399
</tabular>
3400
<caption>
3401
PostScript driver options
3402
</caption>
3403
</table>
3404
3405
<p>
3406
3407
<table loc="htbp">
3408
<tabular ca="ll">
3409
<hline>
3410
Command | Description @
3411
<hline>
3412
grayscale | set grayscale output @
3413
color | set color output @
3414
level1 | use only PS Level 1 subset of commands @
3415
level2 | use also PS Level 2 commands if needed @
3416
bbox:tight | enable "tight" bounding box @
3417
bbox:page | bounding box coincides with page dimensions @
3418
<hline>
3419
</tabular>
3420
<caption>
3421
EPS driver options
3422
</caption>
3423
</table>
3424
3425
<p>
3426
3427
<table loc="htbp">
3428
<tabular ca="ll">
3429
<hline>
3430
Command | Description @
3431
<hline>
3432
PDF1.2 | set compatibility mode to PDF-1.2 @
3433
PDF1.3 | set compatibility mode to PDF-1.3 @
3434
compression:value | set compression level (0 - 9) @
3435
<hline>
3436
</tabular>
3437
<caption>
3438
PDF driver options
3439
</caption>
3440
</table>
3441
3442
<p>
3443
3444
<table loc="htbp">
3445
<tabular ca="ll">
3446
<hline>
3447
Command | Description @
3448
<hline>
3449
format:pbm | output in PBM format @
3450
format:pgm | output in PGM format @
3451
format:ppm | output in PPM format @
3452
rawbits:on | "rawbits" (binary) output @
3453
rawbits:off | ASCII output @
3454
<hline>
3455
</tabular>
3456
<caption>
3457
PNM driver options
3458
</caption>
3459
</table>
3460
3461
<p>
3462
3463
<table loc="htbp">
3464
<tabular ca="ll">
3465
<hline>
3466
Command | Description @
3467
<hline>
3468
grayscale | set grayscale output @
3469
color | set color output @
3470
optimize:on/off | enable/disable optimization @
3471
quality:value | set compression quality (0 - 100) @
3472
smoothing:value | set smoothing (0 - 100) @
3473
baseline:on/off | do/don't force baseline output @
3474
progressive:on/off | do/don't output in progressive format @
3475
dct:ifast | use fast integer DCT method @
3476
dct:islow | use slow integer DCT method @
3477
dct:float | use floating-point DCT method @
3478
<hline>
3479
</tabular>
3480
<caption>
3481
JPEG driver options
3482
</caption>
3483
</table>
3484
3485
<p>
3486
3487
<table loc="htbp">
3488
<tabular ca="ll">
3489
<hline>
3490
Command | Description @
3491
<hline>
3492
interlaced:on | make interlaced image @
3493
interlaced:off | don't make interlaced image @
3494
transparent:on | produce transparent image @
3495
transparent:off | don't produce transparent image @
3496
compression:value | set compression level (0 - 9) @
3497
<hline>
3498
</tabular>
3499
<caption>
3500
PNG driver options
3501
</caption>
3502
</table>
3503
3504
<p>
3505
3506
3507
<sect1>Dates in Grace <label id="dates">
3508
3509
<p>
3510
We use two calendars in Grace: the one that was established in
3511
532 by Denys and lasted until 1582, and the one that was created
3512
by Luigi Lilio (Alyosius Lilius) and Christoph Klau
3513
(Christophorus Clavius) for pope Gregorius XIII. Both use the
3514
same months (they were introduced under emperor Augustus, a few
3515
years after Julian calendar introduction, both Julius and
3516
Augustus were honored by a month being named after each one).
3517
3518
The leap years occurred regularly in Denys's calendar: once
3519
every four years, there is no year 0 in this calendar (the leap
3520
year -1 was just before year 1). This calendar was not compliant
3521
with earth motion and the dates were slowly shifting with regard
3522
to astronomical events.
3523
3524
This was corrected in 1582 by introducing Gregorian
3525
calendar. First a ten days shift was introduced to reset correct
3526
dates (Thursday October the 4th was followed by Friday October
3527
the 15th). The rules for leap years were also changed: three
3528
leap years are removed every four centuries. These years are
3529
those that are multiple of 100 but not multiple of 400: 1700,
3530
1800, and 1900 were not leap years, but 1600 and 2000 were (will
3531
be) leap years.
3532
3533
We still use Gregorian calendar today, but we now have several
3534
time scales for increased accuracy. The International Atomic
3535
Time (TAI) is a linear scale: the best scale to use for
3536
scientific reference. The Coordinated Universal Time (UTC, often
3537
confused with Greenwich Mean Time) is a legal time that is
3538
almost synchronized with earth motion. However, since the earth
3539
is slightly slowing down, leap seconds are introduced from time
3540
to time in UTC (about one second every 18 months). UTC is not a
3541
continuous scale ! When a leap second is introduced by
3542
International Earth Rotation Service, this is published in
3543
advance and the legal time sequence is as follows: 23:59:59
3544
followed one second later by 23:59:60 followed one second later
3545
by 00:00:00. At the time of this writing (1999-01-05) the
3546
difference between TAI and UTC was 32 seconds, and the last leap
3547
second was introduced in 1998-12-31.
3548
3549
These calendars allow to represent any date from the mist of the
3550
past to the fog of the future, but they are not convenient for
3551
computation. Another time scale is possible: counting only the
3552
days from a reference. Such a time scale was introduced by
3553
Joseph-Juste Scaliger (Josephus Justus Scaliger) in 1583. He
3554
decided to use "-4713-01-01T12:00:00" as a reference date
3555
because it was at the same time a Monday, first of January of a
3556
leap year, there was an exact number of 19 years Meton cycle
3557
between this date and year 1 (for Easter computation), and it
3558
was at the beginning of a 15 years <it>Roman indiction</it>
3559
cycle. The day number counted from this reference is
3560
traditionally called <it>Julian day</it>, but it has really
3561
nothing to do with the Julian calendar.
3562
3563
Grace stores dates internally as reals numbers counted from a
3564
reference date. The default reference date is the one chosen by
3565
Scaliger, it is a classical reference for astronomical
3566
events. It can modified for a single session using the <ref
3567
name="Edit->Preferences" id="preferences"> popup of the GUI. If
3568
you often work with a specific reference date you can set it for
3569
every sessions with a REFERENCE DATE command in your
3570
configuration file (see <ref name="Default template"
3571
id="default-template">).
3572
3573
The following date formats are supported (hour, minutes and
3574
seconds are always optional):
3575
3576
<enum>
3577
<item>iso8601 : 1999-12-31T23:59:59.999
3578
<item>european : 31/12/1999 23:59:59.999 or 31/12/99 23:59:59.999
3579
<item>us : 12/31/1999 23:59:59.999 or 12/31/99 23:59:59.999
3580
<item>Julian : 123456.789
3581
</enum>
3582
3583
One should be aware that Grace does not allow to put a space in
3584
one data column as spaces are used to separate fields. You
3585
should always use another separator (:/.- or better T) between
3586
date and time in data files. The GUI, the batch language and the
3587
command line flags do not have this limitation, you can use
3588
spaces there without any problem. The T separator comes from the
3589
ISO8601 standard. Grace support its use also in european and us
3590
formats.
3591
3592
You can also provide a hint about the format ("ISO8601",
3593
"european", "us") using the -datehint command line flag or the
3594
ref name="Edit->Preferences" id="preferences"> popup of the GUI.
3595
The formats are tried in the following order: first the hint
3596
given by the user, then iso, european and us (there is no
3597
ambiguity between calendar formats and numerical formats and
3598
therefore no order is specified for them). The separators
3599
between various fields can be any characters in the set: " :/.-T"
3600
(one or more spaces act as one separator, other characters can
3601
not be repeated, the T separator is allowed only between date and time,
3602
mainly for iso8601), so the string "1999-12 31:23/59" is allowed
3603
(but not recommended). The '-' character is used both as a
3604
separator (it is traditionally used in iso8601 format) and as
3605
the unary minus (for dates in the far past or for numerical
3606
dates). By default years are left untouched, so 99 is a date far
3607
away in the past. This behavior can be changed with the <ref
3608
name="Edit->preferences" id="preferences"> popup, or with the
3609
<tt>DATE WRAP on</tt> and <tt>DATE WRAP YEAR year</tt>
3610
commands. Suppose for example that the wrap year is chosen as
3611
1950, if the year is between 0 and 99 and is written with two or
3612
less digits, it is mapped to the present era as follows:
3613
3614
range [00 ; 49] is mapped to [2000 ; 2049]
3615
3616
range [50 ; 99] is mapped to [1950 ; 1999]
3617
3618
with a wrap year set to 1970, the mapping would have been:
3619
3620
range [00 ; 69] is mapped to [2000 ; 2069]
3621
3622
range [70 ; 99] is mapped to [1970 ; 1999]
3623
3624
this is reasonably Y2K compliant and is consistent with current
3625
use. Specifying year 1 is still possible using more than two
3626
digits as follows: "0001-03-04" is unambiguously March the 4th,
3627
year 1. The inverse transform is applied for dates written by
3628
Grace, for example as tick labels. Using two digits only for
3629
years is not recommended, we introduce a <it>wrap year +
3630
100</it> bug here so this feature should be removed at some
3631
point in the future ...
3632
3633
The date scanner can be used either for Denys's and Gregorian
3634
calendars. Inexistent dates are detected, they include year 0,
3635
dates between 1582-10-05 and 1582-10-14, February 29th of non
3636
leap years, months below 1 or above 12, ... the scanner does
3637
not take into account leap seconds: you can think it works only
3638
in International Atomic Time (TAI) and not in Coordinated
3639
Unified Time (UTC). If you find yourself in a situation were you
3640
need UTC, a very precise scale, and should take into account
3641
leap seconds ... you should convert your data yourself (for
3642
example using International Atomic Time). But if you bother with
3643
that you probably already know what to do.
3644
3645
3646
<sect1>Xmgr to Grace migration guide
3647
3648
<p>
3649
3650
This is a very brief guide describing problems and workarounds for
3651
reading in project files saved with Xmgr. You should read the docs or
3652
just play with Grace to test new features and controls.
3653
3654
<enum>
3655
<item> Grace must be explicitly told the version number of the software
3656
used to create a file. You can manually put "@version VERSIONID"
3657
string at the beginning of the file. The VERSIONID is built as
3658
MAJOR_REV*10000 + MINOR_REV*100 + PATCHLEVEL; so 40101 corresponds
3659
to xmgr-4.1.1. Projects saved with Xmgr-4.1.2 do NOT need the above,
3660
since they already have the version string in them. If you have no
3661
idea what version of Xmgr your file was created with, try some.
3662
In most cases, 40102 would do the trick.
3663
3664
<item> The above relates to the ASCII projects only. The old binary
3665
projects (saved with xmgr-4.0.*) are not automatically converted
3666
anymore. An input filter must be defined to make the conversion
3667
work on-the-fly. Add the following line to ~/.gracerc or the
3668
system-wide $GRACE_HOME/gracerc resource file: DEFINE IFILTER
3669
"grconvert %s -" MAGIC "00000031" See docs for more info on the
3670
I/O filters.
3671
3672
<item> Documentation on the script language is severely lacking still.
3673
3674
<item> Grace is WYSIWYG. Xmgr was not. Many changes required to achieve the
3675
WYSIWYG'ness led to the situation when graphs with objects carefully
3676
aligned under Xmgr may not look so under Grace. Grace tries its best
3677
to compensate for the differences, but sometimes you may have to
3678
adjust such graphs manually.
3679
3680
<item> A lot of symbol types (all except *real* symbols) are removed.
3681
"Location *" types can be replaced (with much higher comfort) by
3682
A(nnotating)values. "Impulse *", "Histogram *" and "Stair steps *"
3683
effects can be achieved using the connecting line parameters (Type,
3684
Drop lines). "Dot" symbol is removed as well; use the filled circle
3685
symbol of the zero size with no outline to get the same effect.
3686
3687
<item> Default page layout switched from free (allowing to resize canvas
3688
with mouse) to fixed. For the old behavior, put "PAGE LAYOUT FREE"
3689
in the Grace resource file or use the "-free" command line switch.
3690
<bf>The use of the "free" page layout is in general deprecated,
3691
though.</bf>
3692
3693
<item> System (shell) variables GR_* renamed to GRACE_*
3694
3695
<item> Smith plots don't work now. They'll be put back soon.
3696
3697
</enum>
3698
3699
3700
</article>
3701
3702
<!-- End of UsersGuide.sgml -->
Loggerhead is a web-based interface for Breezy
Version: 2.0.1