ULTRA User’s Manual

A program for the presentation, manipulation and analysis of one-dimensional data sets, i.e. (x,y) pairs

Stewart A. Brown



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

5:9
This 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).

Print a list of curves on the display.
Take the sin of curve A.
Similarly make a cosine curve. Note that this form doesn’t require you to know that curve B is the one being passed to the cos function.
Take the product of the curves A and B
List the curves currently displayed.
Write all of these curves to a file called foo.pdb which is in PDB format.
Erase all of the curves currently displayed.
List the curves currently displayed.
Read the file foo.pdb in.
Display the menu of curves in all open files.
Select curves number 1 and 3 from the menu to display on the screen.
List the curves currently displayed.
Shift curve A by one unit to the right.
Delete curve B from the display.
Ask ULTRA II about FFT functionality
Exit ULTRA II.
Hopefully this tutorial introduction gave you an orientation which will make the discussions of ULTRA functionality in the following sections clearer.

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:

  1. table rows must contain one or more numbers.

  2. all rows in a given table must have the same number of items.

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

will read the file “test.dat” when ultra starts. Once in the program, if you need data from another file, it can be read by the command

where you insert your file name in place of file-name.


To see the menu of curves which are currently available to be plotted type

or if you have lots of curves you can have the menu sent to a text file by typing

The file file-name can then be sent to a printer.

The data is plotted by selecting curves from the menu by number. To look at curves 1 and 3 you would type

If you want to look at curves 1 through 4 inclusive, you would type

These two types of notation can be mixed to select any combination of curves from the menu for plotting.

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

Similarly, the list of displayed curves is referred to as the curve list or list. The list can be seen by typing

The numbers shown to the right of the label are the number of points in the curve, the minimum x, maximum x, the minimum y, and the maximum y. It is sometimes useful to know these values.

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:

The excerpt from a session illustrates the above points.

U-> span 0 1

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

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

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.

Axis Labels

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

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

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

Axis Types

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.

Color Palettes

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.


autoload
Macro: 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-log
Macro: 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


compare

Procedure: 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]


hardcopy

Macro: 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]


hc1

Macro: 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]


ld

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


merge

Macro: Merge the curves from a list of ULTRA files into a new ULTRA file.

Usage: merge target-file-name source-file-name-list


np

Macro: 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-menu

Macro: 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]


rd

Macro: 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-table

Macro: 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]]]


resume

Procedure: Resume reading SCHEME forms from an ASCII disk file. See stop.

Usage: resume


save

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


stop

Procedure: 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 give incorrect results due to improper padding - use with caution.

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. The curve-g is normalized to unit area before doing the convolution.

Usage: convolb curve-f curve-g


convolc
Procedure: Compute the convolution of the two curves, i.e.


This slower method uses direct integration and minimal interpolations.

Usage: convolc 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


fill
Procedure: Fill the area under curves with the specified color.

Usage: fill curve-list color-number

Default: off


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

Usage: curve->list curve


file-info*
Procedure: Print the descriptive information for a PDB ULTRA file to the terminal.

Usage: file-info* file-name


handle-mouse-event
Macro: User supplied macro called on mouse up/down events if it exists.

Example:

    (define-macro (handle-mouse-event type loc btn qual)
        (let* ((ev  (cond ((eqv? type mouse-up)        "up")
    		          ((eqv? type mouse-down)      "down")
    		          (else                        "unknown")))
	       (mod (cond ((eqv? qual key-shift)       "shift")
    		          ((eqv? qual key-cntl)        "ctl")
    		          ((eqv? qual key-alt)         "alt")
                          ((eqv? qual key-lock)        "lock")
                          (else                        "")))
	       (key (cond ((eqv? btn mouse-left)       "left")
    		          ((eqv? btn mouse-middle)     "middle")
    		          ((eqv? btn mouse-right)      "right")
    		          ((eqv? btn mouse-wheel-up)   "wheel-up")
    		          ((eqv? btn mouse-wheel-down) "wheel-down")
       		          (else                        btn))))
              (printf nil "Mouse %s event %s %s at %s\n" ev mod key loc)))
A mouse up or down event in a graphics window will print out a message detailing the mouse button, qualifiers, and the location.


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 ULTRA

Usage: 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 windows

Usage: label-space real

Default: 0.0


label-type-size
INTEGER - point size for curve labels printed at the bottom of the plot

Usage: 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 evaluated

Usage: 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 loaded

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

cartesian-plotvalue for plot-type variable
polar-plotvalue for plot-type variable
insel-plotvalue for plot-type variable
cartesianvalue for axis-type variable
polarvalue for axis-type variable
inselvalue for axis-type variable
leftvalue for histogram plot control or text alignment
rightvalue for histogram plot control or text alignment
centervalue for histogram plot control or text alignment
allvalue for kill command
onvalue for variables which toggle off and on
offvalue for variables which toggle off and on
whitevalue for background color control
blackvalue for background color control
autovalue for background color control
right-of-axisvalue for axis control
left-of-axisvalue for axis control
straddle-axisvalue for axis control
solidvalue for lnstyle command
dashedvalue for lnstyle command
dottedvalue for lnstyle command
dotdashedvalue for lnstyle command
plusvalue for marker command
starvalue for marker command
trianglevalue for marker command
%pivalue for pi to be used in expressions
%evalue for e to be used in expressions
helveticavalue for type-face command
timesvalue for type-face command
couriervalue for type-face command
mediumvalue for type-style command
italicvalue for type-style command
boldvalue for type-style command
bold-italicvalue for type-style command
key-shiftshift key modifier
key-cntlcontrol key modifier
key-altalt key modifier
key-locklock key modifier
mouse-leftleft mouse button
mouse-middlemiddle mouse button
mouse-rightright mouse button
mouse-upmouse up event
mouse-downmouse down event
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.

blackblack for lines or text
whitewhite for lines or text
graygray in standard palette for lines or text
dark-graydark gray in standard palette for lines or text
blueblue in standard palette for lines or text
greengreen in standard palette for lines or text
cyancyan in standard palette for lines or text
redred in standard palette for lines or text
magentamagenta in standard palette for lines or text
brownbrown in standard palette for lines or text
dark-bluedark blue in standard palette for lines or text
dark-greendark green in standard palette for lines or text
dark-cyandark cyan in standard palette for lines or text
dark-reddark red in standard palette for lines or text
yellowyellow in standard palette for lines or text
purplepurple in standard palette for lines or text
no-fillcolor value to turn off curve fill

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.

Window Controls
 (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)
Viewport Controls
 ; (view-origin-x  0.18)

 ; (view-origin-y  0.2)

 ; (view-width     0.75)

 ; (view-height    0.75)
Miscellaneous
 (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.0
An 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.0
to
%!PS-Adobe-3.0 EPSF-2.0
ULTRA 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.

2. Copy the default configuration file from the source directory into your home directory. 3. Make desired changes to .ultrarc to customize your configuration file.

4. Add the ULTRA environment variable to your .cshrc file.

5. For X Windows sites, verify your DISPLAY environment variable.

6. Run ULTRA II.

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.

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: 10/27/2009
llnl logo  
  LLNL-CODE-422942| Privacy & Legal Notice
Last modified: January 28, 2010   
  
Contact: wci-webteam@llnl.gov