Disclaimer

Introduction

An ULTRA II Tutorial

Basics of Data Files and Accessing Them

ULTRA II Input Data Files

ASCII ULTRA File Format

Binary ULTRA File Format

Getting Input Data into ULTRA II

ULTRA Curves

ULTRA II Notes

Ultra Commands

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

ULTRA Variables

The Default ULTRA II Environment

Constants and Values

Functions

Synonyms

Display and I/O Environment

Graphical Output in ULTRA II

PostScript

CGM

Extending ULTRA II

Cookbook Examples

Gaussian Curve Generator

First Order Differential Equation Solver

Installation/Availability

UNIX

DOS

Using ULTRA II from a floppy disk

Using ULTRA II from a hard disk

MAC

Using ULTRA II from a floppy disk

Using ULTRA II from a hard disk

Internal Documentation

Related Documents

Disclaimer

This document was prepared as an account of work sponsored by an agency of the United States Government. Nneither the United States Government nor the University of California nor any of their employees, makes any warranty, express or implied, including the warranties of merchantability and fitness for a particular purpose, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed, or represents that its use would not infringe privately owned rights. Reference herein to any specific commercial products, process, or service by trade name, trademark, manufacturer, or otherwise, does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or the University of California. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or the University of California, and shall not be used for advertising or product endorsement purposes.

Part of this work performed under the auspices of the U.S. Department of Energy by Lawrence Livermore National Laboratory under Contract W-7405-Eng-48.

Introduction

ULTRA II is a program for the presentation, manipulation, and analysis of 1D data sets (i.e., x, y pairs). Presentation refers to the capability to display, and make hard copies of data plots. Manipulation refers to the capability to excerpt, shift, and scale data sets. Analysis refers to the capability to combine data sets in various ways to create new data sets. An example of this is the Fast Fourier Transform (FFT) capability in ULTRA II.

The principal object with which ULTRA II works is the curve. A curve is an object which consists of an array of x values, an array of y values, a number of points (the length of the x and y arrays), and an ASCII label. ULTRA II operates on curves.

ULTRA II is a portable tool. It runs on machines from supercomputers to PCs. It runs under UNIX, DOS, and MAC OS. Its portability derives from the PACT libraries which provide the portable graphics and the SCHEME interpreter engine which are the main foundation of ULTRA II.

ULTRA II can read and write ASCII data files or PDB files with ULTRA curves in them. PDBLib is another PACT tool which provides portable, self-describing, binary data files. PDBLib has specific functionality to write ULTRA curves. This provides an easy and convenient way for applications to produce ULTRA files. The advantage of PDB files over ASCII files is that PDB files are about 1/3 the size of a corresponding ASCII file and can be written or read about 10 times faster. Interested readers will find references to PACT documentation later in this manual.

Before plunging into descriptions of the commands and variables for ULTRA II, a brief tutorial is given.

An ULTRA II Tutorial

This section gives a tutorial introduction to ULTRA II. A sample session is run which highlights the basic ULTRA commands.

NOTE: In ULTRA commands, spaces are used to delimit items on the input line. More precisely items on a command line are either space delimited, are preceded by a left parenthesis if the first item in a list, or terminated by a right parenthesis if the last item in a list. Semicolons may be used to stack multiple commands on a single interactive input line. In interactive mode, ranges of curve numbers or data-id’s may be indicated using colon notation. For example,

a: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).

 U-> span 0 6.28

Print a list of curves on the display.

 U-> lst

  A Straight line               0.00e+00   6.28e+00  0.00e+00   6.28e+00 

Take the sin of curve A.

 U-> sin 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.

 U-> cos (span 0 6.28)

Take the product of the curves A and B

 U-> * a b

List the curves currently displayed.

 U-> lst

  A Straight line               0.00e+00   6.28e+00 -1.00e+00   1.00e+00 

  B Straight line               0.00e+00   6.28e+00 -1.00e+00   1.00e+00 

  C * A B                       0.00e+00   6.28e+00 -5.00e-01   5.00e-01 

Write all of these curves to a file called foo.pdb which is in PDB format.

 U-> save foo.pdb a:c

Erase all of the curves currently displayed.

 U-> era

List the curves currently displayed.

 U-> lst

Read the file foo.pdb in.

 U-> rd foo.pdb

Display the menu of curves in all open files.

 U-> menu

      MENU      ULTRA II - 11.22.91

 1 Straight line       0.00e+00   6.28e+00 -1.00e+00   1.00e+00 foo.pdb

 2 Straight line       0.00e+00   6.28e+00 -1.00e+00   1.00e+00 foo.pdb

 3 * A B               0.00e+00   6.28e+00 -5.00e-01   5.00e-01 foo.pdb

Select curves number 1 and 3 from the menu to display on the screen.

 U-> cur 1 3

List the curves currently displayed.

 U-> lst

 A Straight line       0.00e+00   6.28e+00 -1.00e+00   1.00e+00 foo.pdb

 B * A B               0.00e+00   6.28e+00 -5.00e-01   5.00e-01 foo.pdb

Shift curve A by one unit to the right.

 U-> dx a 1

Delete curve B from the display.

 U-> del b

Ask ULTRA II about FFT functionality

 U-> apropos fft

      APROPOS      ULTRA II - 11.22.91

 Apropos: fft

 cfft :

 Procedure: Compute Complex FFT. Return real and imaginary parts.

 Usage: cfft <real-curve> <imaginary-curve>

 ifft :

 Procedure: Compute Inverse FFT. Return real and imaginary parts.

 Usage: ifft <real-curve> <imaginary-curve>

 fft :

 Procedure: Compute Fast Fourier Transform of real curve. Return real 
and imaginary parts.

 Usage: fft <curve>

Exit ULTRA II.

 U-> end

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

          ultra test.dat

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

          rd file-name

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

          menu

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

          print-menu file-name

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

          select 1 3

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

          select 1:4

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

          menu

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

          lst

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:

• on input “a” and “A” are equivalent

• on output ULTRA prints “a” if there is
  no curve associated with the variable a

• on output ULTRA prints “A” if there is
  a curve associated with the variable a

The excerpt from a session illustrates the above points.

 U-> span 0 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.

One special case requires specific explanation. When the relative range on a linear axis drops below 0.001 the axis tick marks are labeled in a different way. The minimum axis value is printed with a “>” in front of it and the remaining ticks are labeled by the value minus the minimum value. For example, suppose the domain of a plot goes from 1.0 to 1.000003; the label sequence would appear as:

>1.00e+00 1.00e-6 2.00e-6 3.00e-6

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 preAyou would type

          select 1 3

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

          select 1:4

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

          menu

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

          lst

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:

• on input “a” and “A” are equivalent

• on output ULTRA prints “a” if there is
  no curve associated with the variable a

• on output ULTRA prints “A” if there is
  a curve associated with the variable a

The excerpt from a session illustrates the above points.

 U-> span 0 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.

One special case requires specific explanation. When the relative range on a linear axis drops below 0.001 the axis tick marks are labeled in a different way. The minimum axis value is printed with a “>” in front of it and the remaining ticks are labeled by the value minus the minimum value. For example, suppose the domain of a plot goes from 1.0 to 1.000003; the label sequence would appear as:

>1.00e+00 1.00e-6 2.00e-6 3.00e-6

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 preAyou would type

          select 1 3

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

          select 1:4

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

          menu

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

          lst

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:

• on input “a” and “A” are equivalent

• on output ULTRA prints “a” if there is
  no curve associated with the variable a

• on output ULTRA prints “A” if there is
  a curve associated with the variable a

The excerpt from a session illustrates the above points.

 U-> span 0 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.

One special case requires specific explanation. When the relative range on a linear axis drops below 0.001 the axis tick marks are labeled in a different way. The minimum axis value is printed with a “>” in front of it and the remaining ticks are labeled by the value minus the minimum value. For example, suppose the domain of a plot goes from 1.0 to 1.000003; the label sequence would appear as:

>1.00e+00 1.00e-6 2.00e-6 3.00e-6

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 preAyou would type

          select 1 3

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

          select 1:4

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

          menu

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

          lst

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:

• on input “a” and “A” are equivalent

• on output ULTRA prints “a” if there is
  no curve associated with the variable a

• on output ULTRA prints “A” if there is
  a curve associated with the variable a

The excerpt from a session illustrates the above points.

 U-> span 0 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.

One special case requires specific explanation. When the relative range on a linear axis drops below 0.001 the axis tick marks are labeled in a different way. The minimum axis value is printed with a “>” in front of it and the remaining ticks are labeled by the value minus the minimum value. For example, suppose the domain of a plot goes from 1.0 to 1.000003; the label sequence would appear as:

>1.00e+00 1.00e-6 2.00e-6 3.00e-6

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 preAyou would type

          select 1 3

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

          select 1:4

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

          menu

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

          lst

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:

• on input “a” and “A” are equivalent

• on output ULTRA prints “a” if there is
  no curve associated with the variable a

• on output ULTRA prints “A” if there is
  a curve associated with the variable a

The excerpt from a session illustrates the above points.

 U-> span 0 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.

One special case requires specific explanation. When the relative range on a linear axis drops below 0.001 the axis tick marks are labeled in a different way. The minimum axis value is printed with a “>” in front of it and the remaining ticks are labeled by the value minus the minimum value. For example, suppose the domain of a plot goes from 1.0 to 1.000003; the label sequence would appear as:

>1.00e+00 1.00e-6 2.00e-6 3.00e-6

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 print