- Introduction
- An ULTRA II Tutorial
- Basics of Data Files and Accessing Them
- ULTRA Curves
- ULTRA II Notes
- Ultra Commands
- ULTRA Variables
- The Default ULTRA II Environment
- Graphical Output in ULTRA II
- Extending ULTRA II
- Configuration/Availability
- Internal Documentation
- Related Documents
Introduction
ULTRA II is a program for the presentation, manipulation, and analysis of 1D data sets, i.e. (x,y) pairs. Presentation refers to the capability to display, and make hard copies of data plots. Manipulation refers to the capability to excerpt, shift, and scale data sets. Analysis refers to the capability to combine data sets in various ways to create new data sets. An example of this is the Fast Fourier Transform (FFT) capability in ULTRA II.The principal object with which ULTRA II works is the curve. A curve is an object which consists of an array of x values, an array of y values, a number of points (the length of the x and y arrays), and an ASCII label. ULTRA II operates on curves.
ULTRA II is a portable tool. It runs on machines from supercomputers to PCs. It runs under UNIX and MAC OS. Its portability derives from the PACT libraries which provide the portable graphics and the SCHEME interpreter engine which are the main foundation of ULTRA II.
ULTRA II can read and write ASCII data files or PDB files with ULTRA curves in them. PDBLib is another PACT tool which provides portable, self-describing, binary data files. PDBLib has specific functionality to write ULTRA curves. This provides an easy and convenient way for applications to produce ULTRA files. The advantage of PDB files over ASCII files is that PDB files are about 1/3 the size of a corresponding ASCII file and can be written or read about 10 times faster. Interested readers will find references to PACT documentation later in this manual.
Before plunging into descriptions of the commands and variables for ULTRA II, a brief tutorial is given.
An ULTRA II Tutorial
This section gives a tutorial introduction to ULTRA II. A sample session is run which highlights the basic ULTRA commands.NOTE: In ULTRA commands, spaces are used to delimit items on the input line. More precisely items on a command line are either space delimited, are preceded by a left parenthesis if the first item in a list, or terminated by a right parenthesis if the last item in a list. Semicolons may be used to stack multiple commands on a single interactive input line. In interactive mode, ranges of curve numbers or data-id’s may be indicated using colon notation. For example,
a:for
5:9This notation is shorthand for the thru procedure.
To start up ULTRA II either type “ultra” at a command line prompt or double click on the ULTRA II application icon. ULTRA II will start up and print a banner. (Before using ULTRA II on UNIX systems, you must define an ULTRA environment variable. This variable tells ULTRA II to look in the specified directory or directories for various configuration and extension files. See the Installation/Availability section for details.)
ULTRA II - 11.22.91
Create a curve consisting of a straight line y=x over the interval (0, 6.28).
- U-> span 0 6.28
- U-> lst
A Straight line 0.00e+00 6.28e+00 0.00e+00 6.28e+00Take the sin of curve A.
- U-> sin a
- U-> cos (span 0 6.28)
- U-> * a b
-
U-> lst
A Straight line 0.00e+00 6.28e+00 -1.00e+00 1.00e+00 B Straight line 0.00e+00 6.28e+00 -1.00e+00 1.00e+00 C * A B 0.00e+00 6.28e+00 -5.00e-01 5.00e-01Write all of these curves to a file called foo.pdb which is in PDB format.
- U-> save foo.pdb a:c
- U-> era
- U-> lst
- U-> rd foo.pdb
U-> menu
MENU ULTRA II - 11.22.91
1 Straight line 0.00e+00 6.28e+00 -1.00e+00 1.00e+00 foo.pdb
2 Straight line 0.00e+00 6.28e+00 -1.00e+00 1.00e+00 foo.pdb
3 * A B 0.00e+00 6.28e+00 -5.00e-01 5.00e-01 foo.pdb
Select curves number 1 and 3 from the menu to display on the screen.
- U-> cur 1 3
U-> lst A Straight line 0.00e+00 6.28e+00 -1.00e+00 1.00e+00 foo.pdb B * A B 0.00e+00 6.28e+00 -5.00e-01 5.00e-01 foo.pdbShift curve A by one unit to the right.
- U-> dx a 1
- U-> del b
U-> apropos fft
APROPOS ULTRA II - 11.22.91
Apropos: fft
cfft :
Procedure: Compute Complex FFT. Return real and imaginary parts.
Usage: cfft <real-curve> <imaginary-curve>
ifft :
Procedure: Compute Inverse FFT. Return real and imaginary parts.
Usage: ifft <real-curve> <imaginary-curve>
fft :
Procedure: Compute Fast Fourier Transform of real curve. Return real
and imaginary parts.
Usage: fft <curve>
Exit ULTRA II.
- U-> end
Basics of Data Files and Accessing Them
In this section a discussion of input for ULTRA II and a general overview of getting it into a session are given.ULTRA II Input Data Files
ULTRA II accepts two kinds of input files: ASCII and binary ULTRA files.ASCII ULTRA File Format
There are two kinds of ASCII files which ULTRA II can understand. The first contains curve data and the second contains tables which require additional user input in order to obtain curves.
Curves
In ASCII files, data is stored as space delimited X,Y pairs. These pairs may be on individual lines or there may be multiple pairs per line. Identifiers for the curves begin the line with a # which is followed by whatever identification label you like. For example:
# data set 1
0.0 100.0
1.0 200.0
2.0 250.0
3.0 275.0
4.0 287.5
#data set 2
0.0 100.0 1.0 200.0 2.0 250.0
3.0 275.0 4.0 287.5
This file has two curves which incidentally contain the same data.
Tables
Tables of ASCII data are blocks of tabular data which conform to the following rules:
- table rows must contain one or more numbers.
- all rows in a given table must have the same number of items.
- the first item in all rows of a given table may optionally be a
row heading.Tables are accessed in ULTRA II via the read-table and
table-curve commands.
The following example illustrates a file with three tables:
indx pos vel rho 5 1.6313e+00 1.872e-01 2.8419e+00 4 1.5002e+00 1.644e-01 2.9671e+00 3 1.3487e+00 1.475e-01 3.2012e+00 2 1.1692e+00 1.447e-01 3.4873e+00 1 9.3365e-01 1.487e-01 3.3681e+00 c random comments c just stuff id 1 2 3 4 5 ab 5.774e+15 5.187e+15 1.469e+14 1.549e+14 1.154e+14 cd 8.652e+16 7.627e+16 2.514e+15 2.870e+15 2.338e+15 ef 6.529e+16 5.507e+16 1.753e+15 1.943e+15 1.525e+15 xy 9.978e+16 9.009e+16 2.855e+15 3.164e+15 2.508e+15 xx 7.537e+16 8.296e+16 2.579e+15 2.775e+15 2.227e+15 lb 7.061e+16 1.123e+15 3.051e+15 2.837e+15 2.207e+15 rf 1.204e+15 2.894e+15 6.902e+15 5.295e+15 3.738e+15 c some other data 1 5.854 1.900 1.684 2.267 2 1.669 4.895 4.182 5.647 3 1.138 3.060 2.533 3.430 4 1.910 5.190 4.192 5.621 5 1.616 4.603 3.501 4.824 6 1.346 4.426 3.028 3.883 7 1.543 6.971 3.883 4.279 8 2.545 2.180 1.021 7.488 9 2.852 4.150 2.047 1.093
Binary ULTRA File Format
ULTRA uses PDBLib (another PACT tool) to read and write portable binary data files. It also uses PDBLib’s capabilities to organize the binary curve data in a particular way so that it is correct to speak of a binary ULTRA file instead of a generic PDB file. PDBLib provides functions for both C and FORTRAN programs to write ULTRA curves into a PDB file.For C programs the functions are:
PD_wrt_pdb_curve(PDBfile *fp, char *labl, int n, double *px, double *py, int icurve)
The arguments are: fp, a pointer to the PDBfile structure corresponding to the file into which the curve is to be written; labl, the ASCII string containing the curve label; n, the number of points in the curve; px, the array of x values; py, the array of y values; and icurve a counter which must start at 0 and count the number of curves in the file. NOTE: there may be several files into which curves are to be written and in each one the count must start from 0 and proceed to the maximum number of curves in the file.
PD_wrt_pdb_curve_y(PDBfile *fp, char *labl, int n, int ix, double *py, int icurve)
The arguments are: fp, a pointer to the PDBfile structure corresponding to the file into which the curve is to be written; labl, the ASCII string containing the curve label; n, the number of points in the curve; ix, the curve index for the x values; py, the array of y values; and icurve a counter which must start at 0 and count the number of curves in the file. The curve index for the x values refers to the icurve value for a prior PD_wrt_pdb_curve call in which the desired x values were written out to the file. This function is supplied to avoid having unnecessary duplication of x data in a file (the space savings can be quite large). NOTE: there may be several files into which curves are to be written and in each one the count must start from 0 and proceed to the maximum number of curves in the file.
For FORTRAN programs the function to use is:
PFWULC(fileid, nchr, labl, n, px, py, icurve)
The arguments are: fileid, an integer id for the PDB file into which the curve is to be written; nchr; an integer number of characters in the label; labl, a left justified ASCII character string containing nchr meaningful characters; n, an integer number of points in the curve; px the array of x values (the type should be REAL*8); py the array of y values (the type should be REAL*8); and icurve, an integer counter for the number of curves in the file. Unlike the C version this function increments icurve and returns its new value through the argument list. Also see the note for the C version above.
PFWULY(fileid, nchr, labl, n, ix, py, icurve)
The arguments are: fileid, an integer id for the PDB file into which the curve is to be written; nchr; an integer number of characters in the label; labl, a left justified ASCII character string containing nchr meaningful characters; n, an integer number of points in the curve; ix the curve index for the x values py the array of y values (the type should be REAL*8); and icurve, an integer counter for the number of curves in the file. The curve index for the x values refers to the icurve value for a prior PFWULC call in which the desired x values were written out to the file. This function is supplied to avoid having unnecessary duplication of x data in a file (the space savings can be quite large). NOTE: there may be several files into which curves are to be written and in each one the count must start from 0 and proceed to the maximum number of curves in the file. Unlike the C version this function increments icurve and returns its new value through the argument list.
The reader should obtain and read a copy of the PDBLib User’s Manual to fully understand how to prepare a binary ULTRA file.
Getting Input Data into ULTRA II
A data file can be read by placing it on the command line. For example
- ultra test.dat
- rd file-name
To see the menu of curves which are currently available to be plotted type
- menu
- print-menu file-name
The data is plotted by selecting curves from the menu by number. To look at curves 1 and 3 you would type
- select 1 3
- select 1:4
The list of curves in a file is referred to as the curve menu or menu. The menu can be viewed at any time by typing
- menu
- lst
ULTRA Curves
In the previous sections we have seen how to get data into ULTRA II and had a brief glimpse of an ULTRA II session. Before proceeding further, it will be useful to have a brief discussion of how ULTRA II works with its data.The essential data object in ULTRA II is the curve. The aim of almost every input operation is to get data from somewhere (a file or the console) put into the form of a curve. A curve is a structure whose principal members are an array of x values and an array of y values. Internally ULTRA II can support an arbitrary number of curves (limited only by the memory of your machine and disk). Once curves are displayed they are referred to by a single alphabetic character. This limits one to having only 26 curves visible on the display at a time. This limitation may be removed in future versions of ULTRA II.
ULTRA II defines 26 variables whose names are the single alphabetic characters. It reserves these to use in referring to curves. These variables should NOT be used in your own functions when extending ULTRA II. In addition, the following rules apply:
- on input “a” and “A” are equivalent
- on output ULTRA prints “a” if there is
no curve associated with the variable a - on output ULTRA prints “A” if there is
a curve associated with the variable a
The excerpt from a session illustrates the above points.
U-> span 0 1Most readers do not need to be concerned with this fine point of ULTRA II. They may wish to come back to it in the event that they want to write some functions to extend ULTRA II. The reason for bringing it up at this point is that some readers will have noticed ULTRA II’s behavior and be wondering about it.U-> printf nil “%s\n” (curve? a)
#t
U-> printf nil “%s\n” (curve? A)
#t
U-> printf nil “%s\n” (curve? b)
#f
U-> printf nil “%s\n” (curve? B)
#f
U-> printf nil “%s\n” a
A
U-> printf nil “%s\n” b
b
Curves in ULTRA II behave like functions. They take a single numeric argument and return a numeric value. Because of the treatment of curves discussed above it is very easy to denote this sort of operation as the following examples show:
U-> sin (span 0 6.28)
U-> a 1.57
Curve A
1.57 0.999622
U-> printf nil "%6f\n" (a 1.57)
Curve A
1.57 0.999622
0.999622
U-> printf nil "%6f\n" (sin 1.57)
1.000000
As the above example shows, curves do get one bit of exceptional treatment
as far as functions go in ULTRA II. When you ask for the value of a curve
at a certain point from the console, ULTRA II explicitly prints the result.
In your own procedures this behavior can be modified so that the extra
message is suppressed in which case the evaluation of a curve at a point
becomes indistinguishable from any other function call.NOTE: the printf function is a SCHEME level function which is used here only for illustrating the points to be made as concisely as possible. If you are using ULTRA II as is and are not writing your own function, you will not need to worry about it. If you are writing your own procedures, you should obtain a copy of the SX User’s Manual which documents all of the SCHEME functions.
Curve labels as seen by the lst command are too short to record the history of a curve. A curve may be read in or created, and then it may be operated on by such functions as dx in arbitrary ways. Even a long label may not be able to contain a sensible description of all of the operations which have been performed on a curve. In acknowledgment of this limitation and in order to inform the user that a curve has been changed since it was read in, the lst command prints a “*” in front of curves which have been changed.
ULTRA II Notes
In this section we present some notes about various features of ULTRA which need more explanation than can accompany a command description, or which span many commands.
ULTRA II supports several plotting modes including linear-linear Cartesian, log-linear Cartesian, etc. Drawing good-looking axes for all the different possibilities is something of an art. Space is usually an important constraint. To help the user there are several controls on the detailed appearance of the axes.
When the difference in the limits of the axis label values approaches or falls below the precision with which the label values are printed, the resulting axis would be less informative than you would like. PGS divides this problem into two cases:
i) the axis labels are printed with an E format (e.g. %10.2e)
In this case PGS selects one label value (usually the minimum) as a reference value and prints it with a '~' character. All other label values on that axis are printed relative to the reference value. For example, suppose the axis limits were 1000.0 to 1001.0, the precision 2 decimal places, and three label to be printed. The labels would be printed as:
~1.00e+03 5.00e-01 1.00e-00ii) the axis labels are printed with an F or G format (e.g. %10.2g)
In this case PGS selects one label value (usually the minimum) as a reference value and prints it with a '>' character. All other label values on that axis are printed relative to the reference value. For example, suppose the axis limits were 1000.0 to 1001.0, the precision 2 decimal places, and three label to be printed. The labels would be printed as:
>1000.00 0.50 1.00This scheme was chosen keeping the space limitations in mind. Putting a separate label for the overall base or scale has serious ramifications for plotting space.
NOTE: this does not currently apply to log axes.
The standard option for cartesian plots is to draw the axes around the viewport where the curves are drawn. For polar plots the standard option is to draw axes through the point (0,0). Now users can select either axis option with either plot type. The variable axis-type can be set to select the option desired. The axis-type options are the same as the plot-type options. ULTRA does some consistency checking of the plot type and axis type. For example, it will not let you attempt CARTESIAN or POLAR axes with an INSEL plot. The plot type always wins if there is a problem.
ULTRA supports users in selecting the colors which they want to have available in plots. By default ULTRA supplies a standard palette with 15 colors. Different users find some colors easier to see than others and some find that certain colors are either invisible or indistinguishable from other colors.
The mk-pal command lets users build up a palette of colors from a set of available colors. When invoked, a new window is created which shows the available colors and at the top is a number of empty boxes corresponding to the number of colors requested. Clicking with the left mouse button on one of the available colors fills the next empty box with that color. If you select more colors than requested, previously selected colors are overwritten. When you have filled up the empty boxes and are satisfied with the colors you have chosen, click the right mouse button. The new window goes away and the palette you created becomes the current palette for the window. An ASCII file is created with “.pal” appended to the name which you selected for the palette. You may edit this file if you choose.
For subsequent sessions you may read in your palette with the rd-pal command. If successful this palette becomes the current palette for the window. By adding a rd-pal command to your .ultrarc file you can have your favorite colors in every ULTRA session.
The format of a palette file is very simple. The first line contains the name of the palette and the number of colors in the palette, nc. This must be followed by nc lines, each specifying a single entry in the palette. Each line contains the red, green, and blue fractions (i.e. values from 0.0 to 1.0) of the color in that order.
Ultra Commands
The Ultra commands are grouped according to a rough functional similarity which is also somewhat reflected in their usages. In each group the commands are listed alphabetically. The groups are:
I/O Commands
Math Operations Which Do Not Generate a New Curve
Math Operations Which Do Generate a New Curve
Environmental Inquiry Commands
Curve Inquiry Commands
Environmental Control Commands
Plot Control Commands
Curve Control Commands
Commands Useful for Writing Extensions
A brief description of each group is given with the functions.NOTE: If both macro and procedure versions of a command are provided, the name of the procedure will end with an asterisk. In most cases you will want to use the macro version of a particular command. See the section, Extending ULTRA II, for information on the distinction between macros and procedures.
I/O Commands
These commands access disk files either for reading or writing.
autoloadMacro: Causes the file which defines the named procedure to be loaded upon the first invocation of the procedure. The first invocation of the function causes file- name to be read and the definition of procedure-name to be replaced by the one in the file, but it always has the same calling sequence. This can save lots of space by not filling memory with functions that are not used. Once an autoloaded procedure has been invoked it remains in memory until explicitly removed.Usage: autoload procedure-name file-name
command-logMacro: If no argument is supplied or the argument is on, begin logging to file ultra.log. If a file name is supplied, begin logging to that file. Append to existing files. If the argument is off, terminate logging. Logging is initially off.Usage: command-log [on | off | file-name]
Default: off
compareProcedure: Compare the curves from two ULTRA files. This function expects the names of two files which should have comparable curves. The function diff-measure is mapped over each pair of curves (one from each file) with the following result. For the nth curve from each file a fractional difference measure is computed and if the average value of the fractional difference exceeds the error tolerance, the pair of curves is displayed along with the fractional difference and its integral along with a prompt consisting of the curve number, the label of the first curve and the value of the average fractional difference. The user can respond with “y” to indicate acceptance of the result or “n” to indicate non-acceptance of the result. At the completion of the process, a log file ending with “.chk” is written summarizing the curves which differed and were not accepted. This can be used to automate the comparison of simulation code results from one run to another. The optional error tolerance defaults to 10-8. Note: compare has the side-effect of erasing all curves from the screen and killing any curves on the menu.Usage: compare file-name1 file-name2 [tolerance]
hardcopyMacro: Send the current plot or the specified list of curves to all active hardcopy output devices. If a list is given, send out the specified curves, one curve per plot. Lists refer to the curve numbers displayed by the menu command. The list must be space delimited. In interactive mode, ranges may be indicated with a colon. For example, 2:6 will generate 2 3 4 5 6. (The colon notation is shorthand for the thru procedure.) If no list is given, send out the current plot. If the argument is all, send out all curves in the menu, one curve per plot. The current options for hardcopy output device are: a PostScript file; or a CGM file. The default name for the PostScript file is plots.ps, and the ps-name command can be used to set the root part of the file name. The default name for the CGM file is plots.cgm, and the cgm-name command can be used to set the root part of the file name. Any open files remain open until closed by the close-device command or until ULTRA terminates. Note: No printing is actually accomplished until you send the file to the actual printing device.Usage: hardcopy [all | number-list]
hc1Macro: Send the current plot or the specified list of curves to all active hardcopy output devices. If a list is given, send out the specified curves, one plot per file. Lists refer to the curve numbers displayed by the menu command. The list must be space delimited. (Colon notation and thru procedure do not work in this context.) The current options for hardcopy output device are: a PostScript file; or a CGM file. The hc1 command creates a family of files; the default name for the PostScript file family is plots.ps, producing files called plots1.ps, plots2.ps, etc. The ps-name command can be used to set the root part of the file name. The default name for the CGM file family is plots.cgm, producing files called lots1.cgm, plots2.cgm, etc. The cgm-name command can be used to set the root part of the file name. Note: No printing is actually accomplished until you send the file(s) to the actual printing device.Usage: hc1 [all | number-list]
ldMacro: Read SCHEME forms from the specified ASCII disk file. The ’-l’ execute line option can be used to cause ULTRA to read a file of SCHEME forms at start- up.Usage: ld file-name
mergeMacro: Merge the curves from a list of ULTRA files into a new ULTRA file.Usage: merge target-file-name source-file-name-list
npMacro: Invoke commands in non-printing mode. This permits the menu and lst commands to be invoke from within other commands to get curve number or data-id lists without the usual terminal output. For example, to remove all curves on the menu that were read in from file “foo.u” without output to the terminal, type: np kill (menu * foo.u). Also see the interactive command.Usage: np command [arguments]
print-menuMacro: Print the current menu of curves available for plotting to the specified file. The default file name is ultra.menu. Note: No printing is actually accomplished until you send the file to the actual printing device.Usage: print-menu [file-name]
rdMacro: Read curves from the specified ASCII or binary disk file. The next available prefix (see the prefix command) is automatically assigned the menu index of the first curve in each data file read.Usage: rd file-name
read-tableMacro: Read the nth table that begins at or after the indicated line in the specified ASCII disk file. Display the mth line of text before the table if m > 0 or display the |m|th line of text after the table if m < 0.Usage: read-table file-name [n [m [line]]]
resumeProcedure: Resume reading SCHEME forms from an ASCII disk file. See stop.Usage: resume
saveMacro: Save currently plotted curves and/or curves from the menu in the specified disk file. An optional format may be specified: ascii or pdb (machine independent binary). The default is pdb. The file remains open until curves are saved to a different file with the same format or until the end command closes all open files. Once closed a file may not be appended to.Usage: save [ascii | pdb] file-name curve-and/or-number-list
stopProcedure: Return control to the terminal. See resume.Usage: stop
Math Operations Which Do Not Generate a New Curve
These functions all take as arguments a list of curves (some take an additional argument - most often a number). The specified operation is performed on the curves without creating new ones; that is, they modify existing curves.The trigonometric functions (sin, cos, tan) use radians by default. If a user wants to have the trigonometric functions use degrees instead of radians (or to be able to switch between the two), the file trig.scm should be loaded using the ld command. The use-radians variable determines whether the units are radians or degrees.
abs
Procedure: Take the absolute value of the y values of the curves.Usage: abs curve-list
absx
Procedure: Take the absolute value of the x values of the curves.Usage: absx curve-list
acos
Procedure: Take the cos-1 of the y values of the curves.Usage: acos curve-list
acosx
Procedure: Take the cos-1 of the x values of the curves.Usage: acosx curve-list
asin
Procedure: Take the sin-1 of the y values of the curves.Usage: asin curve-list
asinx
Procedure: Take the sin-1 of the x values of the curves.Usage: asinx curve-list
atan
Procedure: Take the tan-1 of the y values of the curves.Usage: atan curve-list
atanx
Procedure: Take the tan-1 of the x values of the curves.Usage: atanx curve-list
cos
Procedure: Take the cosine of the y values of the curves.Usage: cos curve-list
cosh
Procedure: Take the hyperbolic cosine of the y values of the curves.Usage: cosh curve-list
coshx
Procedure: Take the hyperbolic cosine of the x values of the curves.Usage: coshx curve-list
cosx
Procedure: Take the cosine of the x values of the curves.Usage: cosx curve-list
dx
Procedure: Shift the x values of the curves by a fixed value.Usage: dx curve-list value
dy
Procedure: Shift the y values of the curves by a fixed value.Usage: dy curve-list value
divx
Procedure: Divide the x values of the curves by a fixed value.Usage: divx curve-list value
divy
Procedure: Divide the y values of the curves by a fixed value.Usage: divy curve-list value
error-bar
Procedure: Draw error bars on the points of the specified curve. The positive and negative going errors for the data must be given as curves and combined together as shown in the usage below. NOTE: for this first cut if you delete the curves with the error information, the error-bars will be scrambled. You should use the hide command to obtain uncluttered plots with error bars. See error-bar-cap-size for some control over the appearance of the error bars.Usage: error-bar curve pos-dy-curve [neg-dy-curve [pos-dx-curve [neg-dx-curve]]]
exp
Procedure: Take the exponential of the y values of the curves, i.e., y = ey.Usage: exp curve-list
expx
Procedure: Take the exponential of the x values of the curves, i.e., x = ex.Usage: expx curve-list
filter
Procedure: Remove points from the curves that fail the specified domain predicate or range predicate. The predicates must be procedures that return true or false when applied to elements of a domain or range.Usage: filter curve-list domain-predicate range-predicate
filter-coef
Procedure: Return a curve filtered through coefficients. coeff-array is an array of filter coefficients set up using the make-filter routine.Usage: filter-coef curve-list coeff-array ntimes
j0
Procedure: Take the zeroth order Bessel function of the first kind of the y values of the curves.Usage: j0 curve-list
j0x
Procedure: Take the zeroth order Bessel function of the first kind of the x values of the curves.Usage: j0x curve-list
j1
Procedure: Take the first order Bessel function of the first kind of the y values of the curves.Usage: j1 curve-list
j1x
Procedure: Take the first order Bessel function of the first kind of the x values of the curves.Usage: j1x curve-list
jn
Procedure: Take the nth order Bessel function of the first kind of the y values of the curves.Usage: jn curve-list n
jnx
Procedure: Take the nth order Bessel function of the first kind of the x values of the curves.Usage: jnx curve-list n
ln
Procedure: Take the natural logarithm of the y values of the curves.Usage: ln curve-list
lnx
Procedure: Take the natural logarithm of the x values of the curves.Usage: lnx curve-list
log10
Procedure: Take the base 10 logarithm of the y values of the curves.Usage: log10 curve-list
log10x
Procedure: Take the base 10 logarithm of the x values of the curves.Usage: log10x curve-list
mx
Procedure: Scale the x values of the curves by a fixed value.Usage: mx curve-list value
my
Procedure: Scale the y values of the curves by a fixed value.Usage: my curve-list value
powa
Procedure: Raise a fixed value, a, to the power of the y values of the curves, i.e., y = ay.Usage: powa curve-list a
powax
Procedure: Raise a fixed value, a, to the power of the x values of the curves, i.e., x = ax.Usage: powax curve-list a
powr
Procedure: Raise the y values of the curves to a fixed power, i.e., y = ya.Usage: powr curve-list a
powrx
Procedure: Raise the x values of the curves to a fixed power, i.e., x = xa.Usage: powrx curve-list a
recip
Procedure: Take the reciprocal of the y values of the curves.Usage: recip curve-list
recipx
Procedure: Take the reciprocal of the x values of the curves.Usage: recipx curve-list
sin
Procedure: Take the sine of the y values of the curves.Usage: sin curve-list
sinh
Procedure: Take the hyperbolic sine of the y values of the curves.Usage: sinh curve-list
sinhx
Procedure: Take the hyperbolic sine of the x values of the curves.Usage: sinhx curve-list
sinx
Procedure: Take the sine of the x values of the curves.Usage: sinx curve-list
smo
Procedure: Smooth the curves the specified number of times using a method specified by the variable smooth-method. For, “averaging” this does an n point integral average smooth, and for “fft” this uses a Lorentzian filter with coefficient (n/number_points).Usage: smo curve-list n [ntimes]
smooth3
Procedure: Smooth the curves the specified number of times using a method specified by the variable smooth-method. For, “averaging” this does a 3 point integral average smooth, and for “fft” this uses a Lorentzian filter with coefficient (3/number_points).Usage: smooth3 curve-list [ntimes]
smooth5
Procedure: Smooth the curves the specified number of times using a method specified by the variable smooth-method. For, “averaging” this does a 5 point integral average smooth, and for “fft” this uses a Lorentzian filter with coefficient (5/number_points).Usage: smooth5 curve-list [ntimes]
sqr
Procedure: Take the square of the y values of the curves.Usage: sqr curve-list
sqrt
Procedure: Take the square root of the y values of the curves.Usage: sqrt curve-list
sqrtx
Procedure: Take the square root of the x values of the curves.Usage: sqrtx curve-list
sqrx
Procedure: Take the square of the x values of the curves.Usage: sqrx curve-list
tan
Procedure: Take the tangent of the y values of the curves.Usage: tan curve-list
tanh
Procedure: Take the hyperbolic tangent of the y values of the curves.Usage: tanh curve-list
tanhx
Procedure: Take the hyperbolic tangent of the x values of the curves.Usage: tanhx curve-list
tanx
Procedure: Take the tangent of the x values of the curves.Usage: tanx curve-list
xmax
Procedure: Filter out points in curves whose x-values > limit.Usage: xmax curve-list limit
xmin
Procedure: Filter out points in curves whose x-values < limit.Usage: xmin curve-list limit
y0
Procedure: Take the zeroth order Bessel function of the second kind of the y values of the curves.Usage: y0 curve-list
y0x
Procedure: Take the zeroth order Bessel function of the second kind of the x values of the curves.Usage: y0x curve-list
y1
Procedure: Take the first order Bessel function of the second kind of the y values of the curves.Usage: y1 curve-list
y1x
Procedure: Take the first order Bessel function of the second kind of the x values of the curves.Usage: y1x curve-list
ymax
Procedure: Filter out points in curves whose y-values > limit.Usage: ymax curve-list limit
ymin
Procedure: Filter out points in curves whose y-values < limit.Usage: ymin curve-list limit
yn
Procedure: Take the nth order Bessel function of the second kind of the y values of the curves.Usage: yn curve-list n
ynx
Procedure: Take the nth order Bessel function of the second kind of the x values of the curves.Usage: ynx curve-list n
Math Operations Which Do Generate a New Curve
Most of these functions take as arguments a list of the curves (some take an additional argument, others take just two curves). The specified operation is performed using the curves to create new ones. The original curves are not modified.
+
Procedure: Take the sum of the curves, i.e., a + b + ... + n.Usage: + curve-list
-
Procedure: Take the difference of the curves, i.e., a - b - ... - n.Usage: - curve-list
*
Procedure: Take the product of the curves, i.e., a x b x ... x n.Usage: * curve-list
/
Procedure: Take the quotient of the curves, i.e., a / b / ... / n.Usage: / curve-list
append-curves
Procedure: Merge a list of curves over the union of their domains. Where domains overlap, take the average of the curves’ y values. Use simple-append to control behaviour in overlap regions.Usage: append-curves curve-list
average
Procedure: Average the specified curves over the intersection of their domains.Usage: average curve-list
cfft
Procedure: Compute the Complex Fast Fourier Transform of a complex curve. Return the real and imaginary parts.Usage: cfft real-curve imaginary-curve
compose
Procedure: Compute the functional composition of two curves, i.e., f(g(x)).Usage: compose curve-f curve-g
convol
Procedure: Compute the convolution of the two curves, i.e.
This fast method uses FFT’s and the interpolations involved may result in some loss of accuracy.Usage: convol curve-f curve-g
convolb
Procedure: Compute the convolution of the two curves, i.e.
This slower method uses direct integration and minimal interpolations.Usage: convol curve-f curve-g
correl
Procedure: Compute the correlation function of the two curves, i.e.
Usage: correl curve-f curve-g
delta
Procedure: Create a reasonable approximation to a Dirac delta function from xmin to xmax with the singularity at x0 where
This is computed so that:
Usage: delta xmin x0 xmax [n-points]
derivative
Procedure: Take the derivative of the curves.Usage: derivative curve-list
diff-measure
Procedure: Compare two curves. For the given curves a fractional difference measure and its average is computed, i.e.
The first optional argument controls printing and color selection. The second optional argument specifies the error tolerance and defaults to 10-8
Usage: diff-measure curve-a curve-b [#t|#f] [tolerance]
diffraction
Procedure: Compute a diffraction pattern corresponding to a circular aperture of radius r.Usage: diffraction r [n-points]
edit
Procedure: Graphically edit a curve on the screen. This command takes a curve to be edited. A copy of the curve is made and drawn as a scatter plot. The markers of points to be retained are colored green and the points to be removed are colored red. By holding down the left mouse button and moving the cursor, the user can select points for removal. Points can be toggled back to green by holding down the shift key and the left mouse button and moving the cursor. When the all points are selected, clicking the right mouse button returns to ULTRA where the new curve is cleaned up and replotted as a line plot.Usage: edit curve
extract
Procedure: Derive a new curve from an existing one by interpolating values from the existing curve. You may specify either the number of points desired or sets of triples xmin, xmax, dx which specify sub-domains of the given curve.Usage: extract curve npoints | x1min x1max dx1 [x2min x2max dx2 ...]
fft
Procedure: Compute the Fast Fourier Transform of a real curve. Return the real and imaginary parts.Usage: fft curve
fit
Procedure: Find least-squares fits to the specified curves for a polynomial of order n. Enter <carriage-return> to continue.Usage: fit curve-list n
fitcurve
Procedure: Using all the curves in the argument list except the first, compute a fit to the first curve in the list using the least squares method. The result is a new curve which is a linear combination of all of the given curves but the first.Usage: fitcurve curve-to-fit curves-for-fit
fode
Procedure: Compute the solution to the first order differential equation:
in the range xmin to xmax where a and b are given by curve-a and curve-b respectively. The homogenous and particular solutions to the equation are plotted and returned.
Usage: fode curve-a curve-b xmin xmax
gaussian
Procedure: Generate a gaussian function:
Usage: gaussian a w x0 [n-points]
hypot
Procedure: Take the harmonic average of two curves, i.e.,
Usage: hypot curve-a curve-b
ifft
Procedure: Compute the Inverse Fast Fourier Transform of the curve. Return the real and imaginary parts.Usage: ifft real-curve imaginary-curve
integrate
Procedure: Compute the definite integral of each curve in the list over the specified domain.Usage: integrate curve-list low-lim high-lim
max
Procedure: Construct a curve from the maximum y values at each point.Usage: max curve-list
min
Procedure: Construct a curve from the minimum y values at each point.Usage: min curve-list
normalize
Procedure: Construct a new curve with unit area in its domain.Usage: normalize curve
span
Procedure: Generate a curve of unit slope and zero y intercept in the given domain.Usage: span xmin xmax [n-points]
theta
Procedure: Create a reasonable approximation to a step function from xmin to xmax with the step at x0.Usage: theta xmin x0 xmax [n-points]
thin
Procedure: Construct new curves which retains the information content of the given curves but with fewer points.Usage: thin curve-list “int” n-points | “dif” tolerance
vs
Procedure: Plot the range of the first curve against the range of the second curve.Usage: vs curve-a curve-b
Environmental Inquiry Commands
These functions are provided to gain access to information about the state of the Ultra session. Information such as the state of global variables and system help packages is made available through these functions.
apropos
Macro: List all functions or variables containing the designated substring. See the help command.Usage: apropos string
display
Procedure: Print an ULTRA II object to the terminal.Usage: display expression
file-info
Macro: Print the descriptive information for a PDB ULTRA file to the terminal.Usage: file-info file-name
help
Macro: Return information about the specified command, variable, or command category. If no argument is supplied, return a list of command categories. See the apropos command.Usage: help [command | variable | category]
lst
Macro: Return a list of the curves currently displayed. Print the list to the terminal if terminal output is on. See the interactive and np commands. A regular expression may be supplied for matching against the curve label to be listed. An additional expression may be specified to restrict listings to curves from particular files.Usage: lst [label-pattern [file-pattern]]
menu
Macro: Return a list of the curves available for plotting. Print the list to the terminal if terminal output is on. See the interactive and np commands. A regular expression may be supplied for matching against the curve label to be listed. An additional expression may be specified to restrict menu listings to curves from particular files.Usage: menu [label-pattern [file-pattern]]
menui
Macro: Return a selection of the curves available for plotting. Print the list to the terminal if terminal output is on. See the interactive and np commands. In the interactive mode, ranges may be indicated with a colon. For example, 2:6 will generate 2 3 4 5 6.Usage: menui number-list
table-attributes
Procedure: Return a list containing the attributes of the current table - (n-rows n-cols table-number).Usage: table-attributes
Curve Inquiry Commands
These functions provide a mechanism for obtaining information about specified curves. Some of the information is used internally in Ultra but can also be useful in SCHEME procedures.
disp
Procedure: Display (to the terminal) the actual values in the specified curves in the specified domain. One or both domain arguments may be omitted and will default to the extrema for the first curve.Usage: disp curve-list [xmin [xmax]]
get-attributes
Procedure: Return (to the terminal) the given curve’s attributes: (color width style).Usage: get-attributes curve
get-domain
Procedure: Return (to the terminal) the given curve’s domain.Usage: get-domain curve
get-label
Procedure: Return (to the terminal) the given curve’s label.Usage: get-label curve
get-number-points
Procedure: Return (to the terminal) the given curve’s number of points.Usage: get-number-points curve
get-range
Procedure: Return (to the terminal) the given curve’s range.Usage: get-range curve
getx
Procedure: Return (to the terminal) the x values for a given y. Enter <carriage-return> to continue.Usage: getx curve-list value
gety
Procedure: Return (to the terminal) the y values for a given x. Enter <carriage-return> to continue.Usage: gety curve-list value
stats
Procedure: Calculate the mean and standard deviation for the curves and display the results on the terminal.Usage: stats curve-list
Environmental Control Commands
These functions allow you to manipulate the environment of Ultra on a global level. They are useful to avoid repeated use of other commands or to change the state of Ultra in dramatic ways.
close-device
Macro: Causes the specified graphics device to be closed appropriately. The legal values for device are: window or an X server and screen (host:display.screen), for screen windows; ps, for PostScript output; and cgm for CGM output.Usage: close-device device
end
Procedure: Exit Ultra gracefully.Usage: end
erase
Procedure: Erase all curves on the screen but leave the limits untouched.Usage: erase
kill
Procedure: Delete the specified entries from the menu. Once gone, the curves must be read in from the file to be used again. The image of curves (the plot) is not changed. The menu is renumbered.Usage: kill all | number-list
open-device
Macro: Causes the specified graphics device to be opened appropriately. The legal values for device are: window or an X server and screen (host:display.screen), for screen windows; ps, for PostScript output; and cgm for CGM output. The legal values for type are: monochrome, for black and white graphics; and color, for color graphics. The title is used in the title bar on windows and as the base of the file name for PostScript and CGM output.Usage: open-device device type title
plots
Procedure: Turn plotting of curves to the screen on or off. Even when plotting is off the curves still exist and may be manipulated. The ‘-s’ execute line option causes ULTRA to start-up with plotting turned off. The ‘-u’ execute line option causes ULTRA to start-up with plotting turned on. This is the default.Usage: plots on | off
prefix
Macro: Assign or list menu prefixes. If both a prefix and menu index (curve number) are supplied, the prefix is assigned to the specified index. If the command is invoked with a prefix and no index, the prefix and its assigned index and file name, if any, are displayed. If invoked without arguments, information on all active prefixes is listed. In interactive mode, in commands requiring a menu index, any integer prefaced by an active prefix and a period ‘.’, is interpreted as an index with value one less than the sum of the integer and the index assigned to the prefix. For example, if prefix ‘b’ is associated with menu index 10, then the command ‘select b.2’ would cause curve 11 in the menu to be plotted. The next available prefix is automatically associated with the menu index of the first curve in each data file read in. Also see the pre procedure.Usage: prefix [a | b | ... | z [menu-index | off]]
replot
Procedure: Replot all curves in the list. A plain carriage-return also forces a replot.Usage: replot
screen
Macro: Begin plotting graphics on the specified display in a window with the specified title. display-name is either the literal string window or an X server and device on which to display plots. display-title is a string displayed in the title bar of the plot window.Usage: screen [display-name [display-title]]
system
Procedure: Pass commands through Ultra to the operating system. (This depends on the operating system having this capability - not available on Macintosh machines.) Enclose literal command strings in double quotes. For example, type: system “ls”Usage: system command
Plot Control Commands
These functions control the plotting characteristics of ULTRA II which affect all displayed curves.
annot
Procedure: Annotate a plot, writing text at a point specified in normalized (i.e. between 0.0 and 1.0) coordinates. Enclose text in double quotes. If the xmin, etc. are not specified, ULTRA will wait for you to drag a rectangle in the screen window where you want the text to go. To move an annotation around the screen, grab the annotation with the left mouse button and drag it where you want it to go. To remove an annotation, click on it with the right mouse button. To edit the text of the annotation, put the mouse close enough to the text of the annotation that the text cursor is activated and use EMACS editing commands to change the text.Usage: annot text [color [xmin xmax ymin ymax]]
autoplot
Procedure: Set the state of automatic replotting.Usage: autoplot on | off
Default: on
axis
Procedure: Set whether or not to draw axes on graphs.Usage: axis on | off
Default: on
data-id
Procedure: Set whether or not to plot curve identifiers. This was formerly the marker command.Usage: data-id on | off
Default: on
domain
Procedure: Set the domain for plotting. Typing de (for default) will let the curves determine the domain.Usage: domain low-lim high-lim
Usage: domain de
Default: de
grid
Procedure: Set whether or not to draw grid lines on graphs.Usage: grid on | off
Default: off
marker-scale
Procedure: Set the marker character scale.Usage: marker-scale real
Default: 0.01
mk-pal
Procedure: Graphically create a new palette of line colors. The palette name and number of colors must be supplied. The resulting palette will be written into an ASCII file name.pal and can be read in in subsequent session with the command, rd-pal.Usage: mk-pal name integer
range
Procedure: Set the range for plotting. Typing de (for default) will let the curves determine the range.Usage: range low-lim high-lim
Usage: range de
Default: de
rd-pal
Procedure: Read in an ASCII palette file and make it the current palette. The palette file may have been created by the mk-pal command or with an ASCII text editor.Usage: rd-pal filename
x-log-scale
Procedure: Set log scale on or off for the x axis.Usage: x-log-scale on | off
Default: off
y-log-scale
Procedure: Set log scale on or off for the y axis.Usage: y-log-scale on | off
Default: off
Curve Control Commands
These functions control the individual curves that are currently being displayed. They range in type from controlling the appearance of the curve to deleting it. They also include the “non-mathematical” mechanisms which may generate curves.
color
Procedure: Set the color of the specified curves. Color-number may be an integer or any of the color constants, e.g. black, red, blue.Usage: color curve-list color-number
copy
Procedure: Copy the specified curves.Usage: copy curve-list
copy-curve
Procedure: Make a “copy” of the specified curve with an optionally specified number of evenly spaced points (default is 100). This could be done using extract but not as quickly or conveniently.Usage: copy-curve curve [num-points]
del
Procedure: Delete the specified curves.Usage: del curve-list
dupx
Procedure: Duplicate x values so that y = x for each of the specified curves.Usage: dupx curve-list
hide
Procedure: Hide the specified curves from view (opposite of show).Usage: hide curve-list
histogram
Procedure: Plot the specified curves as histograms. left, right, and center determine how to obtain the central bin values for the histograms.Usage: histogram curve-list off | left | right | center
label
Procedure: Change the label displayed for a curve by lst. Enclose literal label strings in double quotes. NOTE: A label is not to be confused with the curve identifier which is the character that identifies the curve on the plot.Usage: label curve new-label-string
line
Procedure: Generate a curve with y = mx + b.Usage: line m b low-lim high-lim [no.-pts]
lnstyle
Procedure: Set the line styles of specified curves.Usage: lnstyle curve-list solid | dotted | dashed | dotdashed
Default: solid
lnwidth
Procedure: Set the line widths of specified curves. A line width of 0 will always give the thinnest line which the host graphics system supports.Usage: lnwidth curve-list width
Default: 0
make-curve
Macro: Make a curve from two lists of numbers. Each list must be delimited by parentheses.Usage: make-curve (x-values) (y-values)
make-filter
Procedure: Make an array of filter coefficients.Usage: make-filter val1 val2 val3 ...
marker
Procedure: Set the marker characters of specified curves.Usage: marker curve-list plus | star | triangle
Default: plus
random
Procedure: Generate random y values between -1 and 1 for the specified curves.Usage: random curve-list
re-color
Procedure: Reset curve colors to preset sequence.Usage: re-color
re-id
Procedure: Reset data-id’s to A, B, C, ... (no skipping).Usage: re-id
rev
Procedure: Swap x and y values for the specified curves. You may want to sort after this one.Usage: rev curve-list
scatter
Procedure: Plot the specified curves as scatter diagrams or connected lines.Usage: scatter curve-list on | off
Default: off
select
Procedure: Select curves from the menu for plotting. The list must be space delimited. In interactive mode, ranges may be indicated with a colon. For example, 2:6 will generate 2 3 4 5 6. (The colon notation is shorthand for the thru procedure.)Usage: select number-list
set-id
Procedure: Change the data-id of the specified curve.Usage: set-id curve a | b | ... | z
show
Procedure: Reveal the specified curves (opposite of hide).Usage: show curve-list
sort
Procedure: Sort the specified curves so that their points are plotted in order of ascending x values.Usage: sort curve-list
table-curve
Procedure: Build a curve from data in the current table. Tables are regarded simply as contiguous blocks of numbers and you may specify how the x and y values are to be gathered from the table. Tables are read row-wise and the offsets are reckoned accordingly. The number of points must be specified. The zero based offset from the beginning of the table and the stride to be used in gathering the values may be given. The default offset and stride for the y values are zero and one, respectively. If no offset for the x values is specified, the y values are plotted versus index.Usage: table-curve num-points [y-offset [y-stride [x-offset [x-stride]]]]
xindex
Procedure: Create curves with y values vs. integer index values.Usage: xindex curve-list
xmm
Procedure: Excerpt a part of the specified curves.Usage: xmm curve-list low-lim high-lim
Commands Useful for Writing Extensions
These functions are provided to help users who wish to write their own functions for ULTRA II. They can be used at the command level, but they are really oriented for use in procedures to gain access about curves or otherwise control ULTRA II in ways that are not appropriate at the command level.
autoload*
Procedure: Causes the file which defines the named procedure to be loaded upon the first invocation of the procedure. The first invocation of the function causes file-name to be read and the definition of procedure-name to be replaced by the one in the file, but it always has the same calling sequence. This can save lots of space by not filling memory with functions that are not used. Once an autoloaded procedure has been invoked it remains in memory until explicitly removed.Usage: autoload* procedure-name file-name
close-device*
Procedure: Causes the specified graphics device to be closed appropriately. The legal values for device are: window or an X server and screen (host:display.screen), for screen windows; ps, for PostScript output; and cgm for CGM output.Usage: close-device* device
curve?
Procedure: Return #t (true) iff the argument is an Ultra curve object. Otherwise return #f (false). Print returned value only if print-flag is on.Usage: curve? object
curve->list
Procedure: Return a list containing the list of x values and the list of y values for the specified curve. This function is the inverse of make-curveUsage: curve->list curve
file-info*
Procedure: Print the descriptive information for a PDB ULTRA file to the terminal.Usage: file-info* file-name
interactive
Procedure: Turn terminal output on or off in functions only.Usage: interactive on | off
ld*
Procedure: Read SCHEME forms from the specified ASCII disk file. The argument must be a SCHEME expression which evaluates to a file name.Usage: ld* file-name-expression
lst*
Procedure: Return a list of the curves currently displayed. Print the list to the terminal if terminal output is on. See the interactive and np commands. A regular expression may be supplied for matching against the curve label to be listed. An additional expression may be specified to restrict listings to curves from particular files.Usage: lst* [label-pattern [file-pattern]]
make-curve*
Procedure: Make a curve. The arguments must be SCHEME expressions that evaluate to lists of numbers.Usage: make-curve* x-values-expression y-values-expression
menu*
Procedure: Return a list of the curves available for plotting. Print the list to the terminal if terminal output is on. See the interactive and np commands. A regular expression may be supplied for matching against the curve label to be listed. An additional expression may be specified to restrict menu listings to curves from particular files.Usage: menu* [label-pattern [file-pattern]]
merge*
Procedure: Merge the curves from a list of ULTRA files into a new ULTRA file.Usage: merge* target-file-name source-file-name-list
open-device*
Procedure: Causes the specified graphics device to be opened appropriately. The legal values for device are: window or an X server and screen (host:display.screen), for screen windows; ps, for PostScript output; and cgm for CGM output. The legal values for type are: monochrome, for black and white graphics; and color, for color graphics. The title is used in the title bar on windows and as the base of the file name for PostScript and CGM output.Usage: open-device* device type title
pre
Procedure: Given a prefix and an index, return a curve number. In interactive mode only, the shorthand notation prefix.index may be used. See the prefix command.Usage: pre prefix index
prefix*
Procedure: Assign or list menu prefixes. If both a prefix and menu index (curve number) are supplied, the prefix is assigned to the specified index. If the command is invoked with a prefix and no index, the prefix and its assigned index and file name, if any, are displayed. If invoked without arguments, information on all active prefixes is listed. In interactive mode, in commands requiring a menu index, any integer prefaced by an active prefix and a period ‘.’, is interpreted as an index with value one less than the sum of the integer and the index assigned to the prefix. For example, if prefix ‘b’ is associated with menu index 10, then the command ‘select b.2’ would cause curve 11 in the menu to be plotted. The next available prefix is automatically associated with the menu index of the first curve in each data file read in. Also see the pre procedure.Usage: prefix* [a | b | ... | z [menu-index | off]]
rd*
Procedure: Read curves from the specified ASCII or binary disk file. The argument must be a SCHEME expression which evaluates to a file name.Usage: rd* file-name-expression
read-table*
Procedure: Read the nth table that begins at or after the indicated line in the specified ASCII disk file. The first argument must be a SCHEME expression which evaluates to a file name.Usage: read-table* file-name-expression [n [line]]
save*
Procedure: Save currently plotted curves and/or curves from the menu in the specified disk file. An optional format may be specified: ascii or pdb (machine independent binary). The default is pdb. The file remains open until curves are saved to a different file with the same format or until the end command closes all open files. Once closed a file may not be appended to.Usage: save* [‘ascii | ‘pdb] file-name-expression curve-and/or-number-list
synonym
Macro: Install the name(s) in the hash table as synonyms for the given function.Usage: synonym func syn1 ... synn
thru
Procedure: Given the first and last elements, return a range of curve numbers or data- id’s that are currently active. In interactive mode only, the shorthand notation first:last may be used.Usage: thru first-curve-number last-curve-number
Usage: thru first-data-id last-data-id
ultra-file?
Procedure: Returns #t if the named file is a valid ULTRA II file, either ASCII or binary. This is mainly intended for use in ULTRA functions.Usage: ultra-file? file-name
ULTRA Variables
ULTRA has many internal variables which control its actions. You may set some of these variables to customize ULTRA to taste. All of the ULTRA variables behave as functions. With no arguments, the current value of the variable is returned. With arguments, the value of the variable is set to the value of the first argument. The default values given reflect the defaults of ULTRA using the standard resource (environment) files. You may customize the defaults of ULTRA by customizing the resource files.To examine the value of an ULTRA variable, just give the name of the variable. For example,
U-> label-length
25
To change a variable’s value, give the variable name and the new value.
For example,
U-> label-length 40
answer-prompt
STRING - string printed before return value. Enclose literal strings in double quotes.Usage: answer-prompt string
Default: “(0):”
ascii-output-format
STRING - string containing the C language style output format for floating point numbers (used by save command with the ascii option and other commands printing to terminal). Enclose literal format strings in double quotes.Usage: ascii-output-format string
Default: “%13.6”
axis-grid-style
INTEGER - line style of axis grid lines.Usage: axis-grid-style solid | dotted | dashed | dotdashed
Default: dotted
axis-line-style
INTEGER - line style of axis lines.Usage: axis-line-style solid | dotted | dashed | dotdashed
Default: solid
axis-line-width
REAL - line width of axis lines.Usage: axis-line-width real
Default: .1
axis-max-major-ticks
INTEGER - maximum number of major tick marks on the axes.Usage: axis-max-major-ticks integer
Default: 10
axis-n-decades
INTEGER - maximum number of log axis decades.Usage: axis-n-decades integer
Default: 8
axis-number-minor-ticks
INTEGER - number of minor tick spaces between major ticks on the axes.Usage: axis-number-minor-ticks integer
Default: -1 (select the number automatically)
axis-number-minor-x-ticks
INTEGER - number of minor tick spaces between major ticks on the x axis. This overrides axis-number-minor-ticks when greater than -1.Usage: axis-number-minor-x-ticks integer
Default: -1 (use axis-number-minor-ticks)
axis-number-minor-y-ticks
INTEGER - number of minor tick spaces between major ticks on the y axis. This overrides axis-number-minor-ticks when greater than -1.Usage: axis-number-minor-y-ticks integer
Default: -1 (use axis-number-minor-ticks)
axis-tick-size
REAL - fractional size of major tick marks on the axes.Usage: axis-tick-size real
Default: .018
axis-tick-type
INTEGER - placement of tick marks relative to axis.Usage: axis-tick-type right-of-axis | left-of-axis | straddle-axis
Default: right-of-axis
axis-type
INTEGER - axis type.Usage: axis-type cartesian | polar | insel
Default: cartesian
axis-x-format
STRING - C language style format of the x axis labels. Enclose literal format strings in double quotes.Usage: axis-x-format format-string
Default: “%10.2g”
axis-y-format
STRING - C language style format of the y axis labels. Enclose literal format strings in double quotes.Usage: axis-y-format format-string
Default: “%10.2g”
background-color-flag
INTEGER - background color on display. Takes effect when screen is invoked.Usage: background-color-flag white | black
Default: white
border-width
INTEGER - window border width in pixels. Takes effect when screen is invoked.Usage: border-width integer
Default: 2
botspace
REAL - fractional space at bottom of plot, i.e. between curves and axes.Usage: botspace real
Default: .01
cgm-background-color-flag
INTEGER - CGM device background color. If auto specified, use display background color as specified by background-color-flag.Usage: cgm-background-color-flag white | black | auto
Default: white
cgm-flag
INTEGER - when on, hardcopy will generate a plot in the CGM file. See the cgm- name command to control file name.Usage: cgm-flag on | off
Default: off
cgm-name
STRING - the root part of the name ULTRA II uses when creating a CGM for output. The extension .cgm is always used. Enclose literal strings in double quotes.Usage: cgm-name string
Default: “plots”
cgm-type
STRING - the type ULTRA II uses when creating a CGM for output. Enclose literal strings in double quotes.Usage: cgm-type “monochrome” | “color”
Default: “monochrome”
console-height
REAL - console window height in fraction of screen height.Usage: console-height real
Default: 1.0
console-origin-x
REAL - x component of console window origin (fraction of screen width).Usage: console-origin-x real
Default: 0.0
console-origin-y
REAL - y component of console window origin (fraction of screen height).Usage: console-origin-y real
Default: 0.0
console-width
REAL - console window width in fraction of screen width.Usage: console-width real
Default: 1.0
console-type
STRING - console window type. Enclose literal strings in double quotes.Usage: console-type “monochrome” | “color”
Default: “monochrome”
default-color
INTEGER - the default line color. With a value of -1 ULTRA rotates sequentially through the available colors of the current palette. The argument may be an integer or any of the color constants, e.g. black, red, blue.Usage: default-color integer
Default: -1
default-npts
INTEGER - the default number of points used to make new curves (used by span, line, etc.). Takes effect for the next curve creation.Usage: default-npts integer
Default: 100
display-name
STRING - display name - either the literal string window or the X server and screen (host: display. screen) on which to display plots. Enclose literal strings in double quotes.Usage: display-name string
Default: “window”
display-title
STRING - display title - string to display in title bar of plot window. Enclose literal strings in double quotes. Takes effect when screen is invoked.Usage: display-title string
Default: “ULTRA II”
display-type
STRING - display type. Enclose literal strings in double quotes.Usage: display-type “color” | “monochrome”
Default: “color”
error-bar-cap-size
REAL - size of the error bar caps in normalized coordinates.Usage: error-bar-cap-size 0.0
Default: 0.018
graphical-interface
INTEGER - turn on the graphical control panel for ULTRAUsage: graphical-interface on | off
Default: off
hide-rescale
INTEGER - turn rescaling after hide command on or off.Usage: hide-rescale on | off
Default: off
label-color-flag
INTEGER - turn printing of labels in same color as corresponding curves on or off.Usage: label-color-flag on | off
Default: off
label-length
INTEGER - character length of the label shown by lst et al. If label-length is greater than or equal to 40, the extrema of the curves will not be printed for the lst or menu commands or in curve labels below plots. The extrema are not suppressed in curve labels on plots if the squeeze-labels option is on.Usage: label-length integer
Default: 25
label-space
REAL- fraction of screen window height to add to screen window height for the display of curve labels. If label-space is 0 (the default) no curve labels are shown in screen windowsUsage: label-space real
Default: 0.0
label-type-size
INTEGER - point size for curve labels printed at the bottom of the plotUsage: label-type-size integer
Default: 8
leftspace
REAL - fractional space at left of plot, i.e. between curves and axes.Usage: leftspace real
Default: .01
lines-page
INTEGER - the number of effective lines per page used by commands such as menu. The default value is 40. A value of 0 is used to imply an infinite number of lines per page; and any other value less than 26 implies a minimum page length of 26 (this is chosen so as not to interfere with the lst command).Usage: lines-page integer
Default: 40
n-curves
INTEGER - total number of curves in the system (returned only, not set).Usage: n-curves
Default: 100
n-curves-read
INTEGER - total number of curves read from files (returned only, not set).Usage: n-curves-read
plot-date
INTEGER - plot the date, time, and host (if available) on hardcopy devices (PS or CGM).Usage: plot-date on | off
Default: on
plot-labels
INTEGER - plot the curve labels on output devices (PS or CGM).Usage: plot-labels on | off
Default: on
plot-type
INTEGER - plot type.Usage: plot-type cartesian | polar | insel
Default: cartesian
print-flag
INTEGER - turn printing of output values on or off.Usage: print-flag on | off
Default: off
print-stats
INTEGER - turn printing of Ultra control statistics on or off.Usage: print-stats on | off
Default: off
prompt
STRING - the prompt. Enclose literal strings in double quotes.Usage: prompt string
Default: “U->”
ps-flag
INTEGER - when on, hardcopy will generate a plot in the PostScript file. See the ps- name command to control file name.Usage: ps-flag on | off
Default: on
ps-name
STRING - the root part of the name ULTRA II uses when creating a PostScript file for output. The extension.ps is always used. Enclose literal strings in double quotes.Usage: ps-name string
Default: “plots”
ps-type
STRING - the type ULTRA II uses when creating a PostScript file for output. Enclose literal strings in double quotes.Usage: ps-type “monochrome” | “color”
Default: “monochrome”
rightspace
REAL - fractional space at right of plot.Usage: rightspace real
Default: .01
save-intermediate
INTEGER - control whether intermediate curves are kept when top level expressions are evaluatedUsage: save-intermediate off
Default: on
simple-append
INTEGER - if on the append-curves command sorts and averages curves in any region of overlap, otherwise a simple concatenation is done.Usage: simple-append on
Default: off
smooth-method
STRING - the smoothing method to use for the smo, smooth, smooth3, and, smooth5 commands. Enclose literal strings in double quotes.Usage: smooth-method “fft” | “averaging” | “tchebyshev” | “least-sqr”
Default: “averaging”
squeeze-labels
INTEGER - when on, replace contiguous blanks in curve labels on plots with a single blank and remove leading and trailing blanks. See the label-length command.Usage: squeeze-labels on | off
Default: off
topspace
REAL - fractional space at top of plot.Usage: topspace real
Default: 0.01
type-face
STRING - the font type face to be used in plots. Enclose literal strings in double quotes.Usage: type-face helvetica | times | courier | string
Default: helvetica
type-size
INTEGER - the font type size in points to be used in plots.Usage: type-size integer
Default: 12
type-style
STRING - the font type style to be used in plots. Enclose literal strings in double quotes.Usage: type-style medium | italic | bold | bold-italic | string
Default: medium
use-radians
INTEGER - use radians as the unit of input to the trigonmetric functions if on and use degrees otherwise. WARNING: this only work when trig.scm has been loadedUsage: use-radians on
Default: off
view-height
REAL - viewport height in fraction of window height. Takes effect when screen is invoked.Usage: view-height real
Default: 0.75
view-origin-x
REAL - x component of viewport origin (fraction of window width). Takes effect when screen is invoked.Usage: view-origin-x real
Default: 0.18
view-origin-y
REAL - y component of viewport origin (fraction of window height). Takes effect when screen is invoked.Usage: view-origin-y real
Default: 0.2
view-width
REAL - viewport width in fraction of window width. Takes effect when screen is invoked.Usage: view-width real
Default: 0.75
window-height
REAL - plot window height in fraction of screen width. Takes effect when screen is invoked.Usage: window-height real
Default: 0.48
window-height-CGM
REAL - CGM window height in fraction of “page” width.Usage: window-height-CGM real
Default: 0.0
window-height-PS
REAL - PostScript window height in fraction of “page” width.Usage: window-height-PS real
Default: 0.0
window-origin-x
REAL - x component of plot window origin (fraction of screen width). Takes effect when screen is invoked.Usage: window-origin-x real
Default: 0.5
window-origin-x-CGM
REAL - x component of CGM window origin (fraction of page width).Usage: window-origin-x-CGM real
Default: 0.0
window-origin-x-PS
REAL - x component of PostScript window origin (fraction of page width).Usage: window-origin-x-PS real
Default: 0.0
window-origin-y
REAL - y component of plot window origin (fraction of screen height). Takes effect when screen is invoked.Usage: window-origin-y real
Default: 0.15
window-origin-y-CGM
REAL - y component of CGM window origin (fraction of page height).Usage: window-origin-y-CGM real
Default: 0.0
window-origin-y-PS
REAL - y component of PostScript window origin (fraction of page height).Usage: window-origin-y-PS real
Default: 0.0
window-width
REAL - plot window width in fraction of screen width. Takes effect when screen is invoked.Usage: window-width real
Default: 0.48
window-width-CGM
REAL - CGM window width in fraction of page width.Usage: window-width-CGM real
Default: 0.0
window-width-PS
REAL - PostScript window width in fraction of page width.Usage: window-width-PS real
Default: 0.0
The Default ULTRA II Environment
ULTRA II functions and variables are defined at two levels. At the C level are the most primitive objects or ones whose run time efficiency is critical. These functions are compiled into the code. At the SCHEME (interpreter) level are a collection of functions which can be derived from the primitive C level functions. These functions are loaded at run time. The user of ULTRA II has no direct control over the C level functionality; however, the user can change the SCHEME level functionality simply by editing certain files and restarting ULTRA II.When ULTRA II starts up it loads in the SCHEME level functions and variables and then loads in the user’s configuration file. The environment defined by theseo two parts makes ULTRA II easier to use for most people. This mechanism also gives sites a convenient way of extending and customizing their environment. The part of the environment created by the SCHEME level functions and variables can be examined by any user, especially those seeking examples of how to extend ULTRA with their own functions. The part of the environment controlled by the user’s configuration file has more to do with arranging the display and setting up of each users personal environment.
This section documents the SCHEME level functions and variables as well as the default environment created by the configuration file distributed with ULTRA II.
Constants and Values
The following local constants are defined mainly to make ULTRA II easier to use. These provide mnemonic names for quantities that you would otherwise have to remember or avoid having to type unwanted characters (e.g. “). They are a part of the SCHEME environment.
Color Constants: these are the default colors for ULTRA II and on black and white systems they are all logically white (the background is logically black). These may be used with the color command and the default-color command. ULTRA II will not return the color names but only the values as a result of the get-attributes command.
cartesian (-1) value for plot-type or axis-type variable polar (-2) value for plot-type or axis-type variable insel (-3) value for plot-type or axis-type variable left (-10) value for histogram plot control right (-11) value for histogram plot control center (-12) value for histogram plot control all (-9) value for kill command on (1) value for variables which toggle off and on off (0) value for variables which toggle off and on white (7) value for background color control black (0) value for background color control auto (-1) value for background color control right-of-axis (9) value for axis control left-of-axis (10) value for axis control straddle-axis (11) value for axis control solid (1) value for lnstyle command dashed (2) value for lnstyle command dotted (3) value for lnstyle command dotdashed (4) value for lnstyle command plus (0) value for marker command star (1) value for marker command triangle (2) value for marker command %pi (3.141592654) value for pi to be used in expressions %e (2.718281828) value for e to be used in expressions helvetica “helvetica” value for type-face command times “times” value for type-face command courier “courier” value for type-face command medium “medium” value for type-style command italic “italic” value for type-style command bold “bold” value for type-style command bold-italic “bold-italic” value for type-style command
black (0) white (1) gray (2) dark-gray (3) blue (4) green (5) cyan (6) red (7) magenta (8) brown (9) dark-blue (10) dark-green (11) dark-cyan (12) dark-red (13) yellow (14) purple (15)
Functions
The following functions are defined at the SCHEME level. Their descriptions are found back with the other ULTRA II functions. This list is given for completeness and to help users to see what kinds of functions can be written at the SCHEME level. The hope is that this will enable new users of ULTRA II to see how to extend ULTRA II to meet the needs of their particular application. The user may look at the coding for these functions by looking in the directory pointed to by their SCHEME environment variable for the files func.scm or help.scm
append-na
autoload
autoload*
compare
convol
convolb
copy-curve
correl
delta
diff-measure
diffraction
extract
fode
gaussian
hardcopy
hc1
help
normalize
np
plots
print-menu
re-color
re-id
resume
screen
smo
smooth3
smooth5
span
theta
vs
xmax
xmin
ymax
ymin
Synonyms
The following are the default synonyms for ULTRA II functions. In the list, the native ULTRA II function is given as the heading for its set of synonyms. These are defined as a part of the SCHEME environment.
+ sum - dif * prod / quot, ratio, div compose comp derivative der domain dom erase era integrate int hardcopy hc kill expunge log10x logx powr pow powrx powx range ran select # cur show unhide smooth3 smooth
Display and I/O Environment
The remainder of the set up has to do with the display and appearance of ULTRA II at run time. This comes from the user’s configuration file which sets up the graphics display window and sets some of the variables mentioned in the section on ULTRA II variables. The actual commands are given here including the values (which are taken from the UNIX configuration) as a further set of examples of the ULTRA II variables involved. NOTE: the viewport variable setting commands are commented out because the values given are the built-in C level defaults.
(background-color-flag white) (border-width 2) (window-origin-x 0.5) (window-origin-y 0.15) (window-width 0.48) (window-height 0.48)
; (view-origin-x 0.18) ; (view-origin-y 0.2) ; (view-width 0.75) ; (view-height 0.75)
(open-device “WINDOW” “COLOR” “ULTRA II”) (ps-flag on) (print-flag off)
Graphical Output in ULTRA II
ULTRA II supports two forms of graphical output apart from the screen display. The first and recommended form is PostScript. The second form is CGM (Computer Graphics Metafile).PostScript
ULTRA II produces a compact (by ASCII text file standards) PostScript file which conforms to the requirements for Encapsulated PostScript (EPS). These files have been successfully imported into several desktop publishing systems (DTP). Because different DTP’s look for different levels of EPS conformance and specification, ULTRA II cannot write a single canned DSC header for its PostScript files. Users can specify the header that their target DTP requires with the ps-name command. To do this they must ascertain the PostScript level and the EPSF conformance level which their target DTP requires. These two numbers are then added to the PostScript file name (separated by spaces). For example, if a particular DTP requires Level 2 PostScript and Level 2 EPSF conformance, then set the PostScript file name as follows:ps-name “foobar 2.0 2.0”The resulting PostScript file, foobar.ps, would have the following header:
%!PS-Adobe-2.0 EPSF-2.0An alternate way of importing the PostScript file into your DTP system, is to edit the first line in the PostScript file to reflect the appropriate level. For example if your favorite DTP program requires level 2 conformance you would change the first line of the PostScript file from
%!PS-Adobe-3.0to
%!PS-Adobe-3.0 EPSF-2.0ULTRA II does not write its PostScript files to conform to the EPSI (Encapsulated PostScript Interchange) standard. EPSI files contain a raster image of the page in their header and DTP systems will display this raster image in the bounding box when an EPSI file is imported into a document. With plain EPS files, the bounding box indicating the placement of an imported PostScript file is typically shown as a featureless (perhaps gray) region on the page.
The authority for PostScript conformance is: PostScript Language Reference Manual, 2nd edition, by Adobe Systems Incorporated and published by Addison Wesley.
CGM
ULTRA II also will write a binary CGM file. It is our opinion that PostScript is a superior standard for graphical output by virtue of its more complete and unambiguous definition. Presumably, you might chose to write a binary CGM file instead of a PostScript file because it is somewhat faster and produces a smaller file. It makes no sense whatsoever to write a clear text CGM file which is larger than a PostScript file, and compressing a PostScript file will result in a file that is comparable to a binary CGM file in size.Every effort has been made to conform to the CGM standard, but because of certain ambiguities and outright bugs in some popular CGM viewers, we discourage you from using CGM as your graphical output medium of choice.
The authority for CGM conformance is: ANSI X3.122-1986, Computer Graphics Metafile for the Storage and Transfer of Picture Description Information.
Extending ULTRA II
ULTRA II has a facility that allows you to build your own extensions to the code. This is accomplished through a SCHEME interpreter. SCHEME is a dialect of the LISP programming language. ULTRA II can be viewed as an extended SCHEME dialect since you are talking to the interpreter when you talk to ULTRA II. It is ideal for the sort of controlling capacity and extensibility it gives to ULTRA II. It also permits you to customize ULTRA to suit your own tastes.For many of the purely presentation and manipulation functions that are done with ULTRA II the discussion below may suffice. If you want to take full advantage of the power of the SCHEME interpreter, see the SX User’s Manual listed in the documentation section and/or consult any book on LISP for a grounding in the principles involved. You may also study the examples provided with the distribution of ULTRA II.
A rough analogy of the ability to customize ULTRA II is the facility for customizing a UNIX environment which the C or Bourne shells give to their users. Not only can new commands be made but old ones may be given additional or alternate names with the synonym command. This allows you to define synonyms for other functions so that you may create a set of commands with names which are more mnemonic.
For example, in the file synon.scm included with this release the following synonyms are defined:
(synonym erase era)
(synonym select # cur)
The first example defines era as a synonym for the erase procedure while
the second defines both # and cur as synonyms for the select procedure.The most important advantage of having the SCHEME interpreter in ULTRA II is that you can write your own procedures and add any new capability to the system. Furthermore, new capabilities happen right away, not whenever we (the maintainers of ULTRA II) get around to it.
Another benefit that accompanies the presence of the SCHEME interpreter is the view of curves and commands. In SCHEME everything is an object including curves and commands. Variables are objects, numbers are objects, and procedures are objects. Furthermore all objects are treated the same way. This property, which is shared with all LISP dialects, gives SCHEME the ability to manipulate programs as data and data as programs. The fundamental function of the SCHEME interpreter is to read in objects, evaluate them in some way which depends on the object, and print out the result of that evaluation. The process of evaluating an object results in another object being returned. This is the crucial point: evaluating an object (especially a procedure object) yields another object! The following table will demonstrate some of the object types and how they evaluate (==> means evaluates to):
integer ==> integer (self evaluating)
float ==> float (self evaluating)
string ==> string (self evaluating)
variable ==> some assigned value
procedure ==> result of the procedure
A quick word on SCHEME syntax. Function calls are expressed as lists with the
procedure first and the arguments next (i.e., in prefix or Polish notation).
A SCHEME list begins with a left parenthesis, has space delimited entries,
and ends with a right parenthesis.
(foo 1 “this is a string” variable (list a b c) 3.14159)
Here is the point of all this talk about objects. All commands in ULTRA II now
return objects. The power of this can be hinted at with an example. Without the
SCHEME interpreter in ULTRA II if you wanted to read a curve in from a file,
take the sin of it and shift the result by 5 you would do the following:
cur 1
sin a
dx a 5
With the SCHEME interpreter, you would do the following:
dx (sin (cur 1)) 5
This is because the command cur returns a curve object which the sin command
takes as an argument just as the old version required. In turn the sin command
returns a curve object which the dx command requires. Ultimately, the dx command
returns a curve object as the final result of evaluating the expression in the
example. Notice that all of these things were done in a single command, but more
importantly we did not have to know whether it was curve A on the display or
curve N!There are two types of functions in ULTRA. The first type which will be referred to as a procedure has all of its arguments evaluated before being passed to the function. The second type called a macro does NOT evaluate its arguments but passes them straight to the function. An example will illustrate the difference. Consider two versions of a function which simply returns its argument, proc-return which is a procedure and macro-return which is a macro.
(proc-return (+ 1 2 3)) ==> 6
(macro-return (+ 1 2 3)) ==> (+ 1 2 3)
In the first case the argument, (+ 1 2 3), is evaluated (the result is 6) and 6
is handed to the function proc-return, while in the second case, the argument,
(+ 1 2 3), is not evaluated and (+ 1 2 3) is handed to the function
macro-return.Another example of immediate importance is:
rd testdata
rd* testdata
These two commands rd and rd* open a file named by the argument and read the
curves in it. rd is a macro and the variable, testdata, is passed to it without
having been evaluated. rd will attempt to find a file with the same name as the
variable, i.e., “testdata”. On the other hand, rd* is a procedure and
will attempt to evaluate the variable, testdata. If the variable, testdata has
not been assigned a value SCHEME will complain about it and do nothing, and if
testdata has been assigned a value, unless the value is the string
“testdata” the desired result of opening the file named,
“testdata” will not happen. To use rd* from the keyboard you would
have to do:
rd* “testdata”
This can be a very confusing point especially since if you want to write a
procedure which opens up a data file whose name has been passed in as an
argument you will need to use rd* because it evaluates its argument!In ULTRA II, commands are expressed as lists as above except that the parentheses around commands typed at the keyboard are assumed. For example the command cited above:
dx (sin (cur 1)) 5
is transformed into
(dx (sin (cur 1)) 5)
before it is handed to the interpreter.Cookbook Examples
In this section two examples of extending ULTRA II are given and discussed.In the source listing given you should note that the “;” character means treat the remainder of the line as a comment. In these examples all opening parentheses have a matching closing parenthesis and you should pay very close attention to which pairs match up!
These examples can be typed into a text file, for example test.scm, and loaded into an ULTRA II session with the ld command by typing
ld test.scm
Gaussian Curve Generator
Suppose you want ULTRA II to generate a gaussian function given an amplitude, a half-width, and a center point (this is in fact the code for the gaussian command and can be found in func.scm in the directory pointed to by the SCHEME environment variable). The following function accomplishes this:
;
; Usage: gaussian <amplitude> <FWHM> <x position of peak> <optional # points>
;
; Note: # of points defaults to 100
;
(define (gaussian amp wid center . npts)
(letrec ((crv-min (- center (* 3 wid)))
(crv-max (+ center (* 3 wid)))
(num (if npts (car npts) 100))
(c (span crv-min crv-max num))
(d (- c center)))
(del c)
(set! c (* d d -1))
(del d)
(set! d (exp (/ c (* wid wid))))
(del c)
(set! c (* d amp))
(del d)
(label c "Gaussian")))
The first line of this function definition specifies that the function is
named gaussian and has three required arguments (amp, wid, and center) and
one optional argument, npts.The next line begins a block of local variable declarations (crv-min, crv-max, num, c, and d). In this example all of the local variables are given initial values. So, for example, crv-min is assigned to the result of evaluating the expression (- center (* 3 wid)). The values given to the local variables are: crv-min, the minimum x value for the resulting gaussian curve; crv-max, the maximum x value of the resulting curve; num, the number of points in the curve; c, a linear curve with num points from crv-min to crv-max; and d, a curve built from the curve c and the value center.
The next commands alternate between generating intermediate results and removing results that are no longer needed (you probably don’t care to see these results when everything is finished). The set! command is a part of SCHEME and assigns to the first argument the value of its second argument.
The last step in this function is to use the label command to label the resulting curve.
First Order Differential Equation Solver
In this example, the equation y’ + ay = b is solved over the domain from xmin to xmax, where a and b are two curves currently displayed and xmin and xmax are two scalar values. The result is two curves containing the homogeneous and particular solutions to the equation. This example is also taken from the file func.scm and shows the ULTRA II fode command.In contrast to the last example there are no optional arguments to this function.
Notice how curves and scalars mix in algebraic expressions.
;
; first order line ode solver
;
(define (fode a b xmin xmax)
(letrec ((integrand-a (copy a))
(particular-y (copy a))
(homogeneous-y (copy a))
(integral-a (integrate integrand-a xmin xmax))
(expia (exp (copy integral-a)))
(expmia (exp (my (copy integral-a) -1)))
(integrand (* b expia)))
;
; compute the homogeneous solution
;
(del expia integral-a homogeneous-y integrand-a)
(set! homogeneous-y (copy expmia))
(label homogeneous-y "Homogeneous solution")
;
; compute the particular solution
;
(set! expia (integrate integrand xmin xmax))
(del particular-y)
(set! particular-y (* expmia expia))
(label particular-y "Particular solution")
(del expia expmia integrand)
(list homogeneous-y particular-y)))
Configuration/Availability
ULTRA II runs on a variety of platforms. For the present purposes those platforms are characterized as UNIX platforms and Apple Macintosh platforms. The following sections tell how to configure ULTRA II to your needs.UNIX
ULTRA II is built as a part of the PACT distribution and installation process. The PACT User’s Guide (see the Related Documentation section) describes how to build and install the entire PACT distribution. When the distribution is built, ULTRA II users must configure their environment to run ULTRA II. In the following steps you will need to know where the default configuration file is kept (see your system administrator or the person who installed the PACT distribution). For the sake of example, suppose that the default configuration file is kept in the directory, /usr/local/scheme. It is assumed that you have put the directory containing the ULTRA II executable on your path variable. You will also need to know how to use a text editor to modify your configuration file, ultra.ini or .ultrarc.1. Go to your home directory.
- cd ~
- cp /usr/local/scheme/ultra.ini .ultrarc
4. Add the ULTRA environment variable to your .cshrc file.
- setenv ULTRA /usr/local/scheme
6. Run ULTRA II.
- ultra
If the custom configuration file, .ultrarc, exists in your home directory, ULTRA will load its contents; otherwise, ULTRA will load the contents of the default configuration file, ultra.ini, located in the directory indicated by the ULTRA environment variable. If you wish to use the default configuration file, omit steps 2 and 3.
MAC
The steps for installing ULTRA II on a Macintosh system with a hard disk are:
2. Make desired changes, if any, to configuration file ultra.ini.
3. Run ULTRA
1. Copy the contents of the distribution disk to a folder named ULTRA.
Internal Documentation
There are two facilities for obtaining on-line help, help and apropos. help gives you the description of a command, a variable, a category, or a general overview of the help system. Some examples of the usage of help are:
help range
help ps-name
help sy
help
If you don’t know the name of a command, then apropos is the command of
choice. It searches the names of the commands and their descriptions for the
string that you give it. If you wanted to know how to take the logarithm of
a curve but weren’t sure of the command, you might type
apropos log
you would get a listing of all the commands that had anything to do with
“log”. You may also get a few surprises since any description where
the sequence “log” appears will be shown; nevertheless, you should
find the information you need. In these descriptions, the sequence curve-list means a list of space delimited letters which are the data-id’s of curves and/or ranges of data-id’s. If you wanted to exponentiate curves a and c you would type
exp a c
If you wanted the logarithm base 10 of curves a through f you would type
log10 a:f
The colon notation is shorthand for the thru procedure.Related Documents
ULTRA II is one part of PACT, a set of tools for portable code development and visualization. Users of ULTRA II may be interested in the other parts of PACT especially since the various aspects of ULTRA II are derived from PACT. That is the graphics is handled by PGS; the binary file handling is done by PDBLib; and the main control and extensibility functionality is provided by the PACT SCHEME interpreter.The list of PACT Documents is:
PACT User’s Guide
SCORE User’s Manual
PPC User’s Manual
PML User’s Manual
PDBLib User’s Manual
PGS User’s Manual
PANACEA User’s Manual
ULTRA II User’s Manual
PDBDiff User’s Manual
PDBView User’s Manual
SX User’s Manual
For questions and comments, please contact the PACT Development Team.
Last Updated: 2/9/2007
