UTILITY PROGRAMS

ANNOTATE,text [,/alignment,/file]

Adds text to a plot using the mouse to choose the text location. It can also save the resulting command in a file (for use as a batch file to reproduce or print the plot, for example.) The text string to add to the plot is held in text. Alignment is the same as for the XYOUTS command. Namely, the default alignment of 0.0 left-justifies the text at the mouse position. Setting the alignment to 0.5 centers the text on the mouse position, and an alignment of 1.0 right-justifies the text. If /file is set to a string, then the command is appended to the end of the file of that name.

CALC_POINTS,filename [,/xrange,/yrange]

Calculate the complex pressure at a point in the xy plane specified by the mouse cursor. Prints the x and y coordinates of the point selected by pressing the left mouse button and the magnitude and phase of the pressure at that point. Filename is the name of the lens system parameter file. The optional keywords /xrange and /yrange describe the region of the ray-trace which will be displayed.

CLOSE_ALL

Closes all open files and frees their LUNs.

CONCAT_RESULTS,/files,/angles,/prefix,/suffix,/outfile Concatenates results of multiple source angle pressure calculations into a single beam pattern. Can be used to create an ideal beam pattern to compare to approximate beam patterns. Either /files or /angles must be set. /files should be set to an array of file names which are the CALC_LENS output files to be processed. If /files is set then /angles, /prefix, and /suffix are ignored. If /angles is set instead of /files, then it should contain an array of source angles corresponding to CALC_LENS output files. The file names to be processed will be formed by /prefix+sangle+/suffix, where sangle is a string version of the angle (i.e. 10, 1, 3.5, 0.2, etc.) If /prefix is not set it will default to 't' and if /suffix is not set it will default to '_20b.out'. The resulting beam pattern will be saved in /outfile, which defaults to 'concat.out' if not set. MAKE_BEAMScan be used to generate the multiple source angle pressure calculations.

CURSORP

Prints the location of the mouse cursor on the screen when the left button is pressed. Pressing the right button exits.

DRAW_LINE,startp,endp [,keyword parameters]

Draws a line from startp to endp, which are (x,y) pairs. Available keyword parameters are /noerase, /xrange, /yrange, /psym, /title, /linestyle, and /color. All work the same as for PLOT.

FIND_ARRAY_MAX,array,xlabels,ylabels

Prints the value and location of the maximum element of an array.

FOCI_CIRC(points [,/origin,/plot,/noerase,/mirror])

Calculates a piecewise-circular fit to data. Returns the origin and radius of a circle fit to each data point and its two neighbors. The parameter points is usually the output of GET_LOG. If /origin is set, then it is used as the origin of the lens system. Otherwise, the smallest x-coordinate is used. The origin is subtracted out in order to increase the accuracy of the fit. If /plot is set, then the data points and curve-fit are plotted. If /noerase is set, then the current plot is not erased. If /mirror is set, then the data is mirrored over the x-axis first. FOCI_CIRC returns an array which is points with four extra columns. The first three extra columns are the x,y,z coordinates of the center of each arc. The final column is the radius of each arc. For example, if points was:

48.1998 0.00000 0.00000 0.00000 0.0171502
48.1888 0.69622 0.00000 1.00000 0.0171280
48.0898 1.73744 0.00000 2.50000 0.0171480
47.7226 3.45114 0.00000 5.00000 0.0172910
46.3198 6.72023 0.00000 10.0000 0.0177150
37.3790 14.1998 0.00000 25.0000 0.0154940

then foci would be:

48.1998 0.00000 0.00000 0.00000 0.0171502 0.00000 0.00000  0.00000 0.00000
48.1888 0.69622 0.00000 1.00000 0.0171280 37.1873 0.174849 0.00000 11.0138
48.0898 1.73744 0.00000 2.50000 0.0171480 36.1563 0.076738 0.00000 12.0484
47.7226 3.45114 0.00000 5.00000 0.0172910 34.5418 -0.26918 0.00000 13.6957
46.3198 6.72023 0.00000 10.0000 0.0177150 31.9396 -1.38579 0.00000 16.5075
37.3790 14.1998 0.00000 25.0000 0.0154940 0.00000 0.00000  0.00000 0.00000

FOCI_CIRC1(points [,/mirror])

Finds the second principal points for data points. Returns the origin and radius of a circle which is equivalent to the source arc. Thus moving an element along the arc is approximately equivalent to moving a point source by the same angle. The parameter points is usually the output of GET_LOG. If /mirror is set, then the data is mirrored over the x-axis first. The output array foci is of the same form as that returned by FOCI_CIRC. For the same points array used in the FOCI_CIRC example, foci would be:

48.1998 0.00000 0.00000 0.00000 0.017150 8.30271 0.00000 0.00000 39.8971
48.1888 0.69622 0.00000 1.00000 0.017128 8.30271 0.00000 0.00000 39.8922
48.0898 1.73744 0.00000 2.50000 0.017148 8.29583 0.00000 0.00000 39.8319
47.7226 3.45114 0.00000 5.00000 0.017291 8.27588 0.00000 0.00000 39.5974
46.3198 6.72023 0.00000 10.0000 0.017715 8.20752 0.00000 0.00000 38.7003
37.3790 14.1998 0.00000 25.0000 0.015494 6.92735 0.00000 0.00000 33.5997

GENERATE_SYSTEM,filename [,keyword parameters]

The program GENERATE_SYSTEM uses the output of BEAM THREE to generate a lens system. It makes parameter files which describe the system for ray-tracing and also generates parameter files which find the focal point(s) of the system. The parameter filename specifies a file which holds the OPTICS table from BEAM3 or the .ZMX file from ZEMAX. The keyword parameters for GENERATE_SYSTEM are:

/angles

A vector of source angles to set up parameter files for. Defaults to [0.0].

/batchfile

The name of the file to which will be saved the commands required to run the generated parameter files. Defaults to 'batch'.

/box

If set, specifies the area within which to search for the focal points of the system generated.

/distance

The distance from the lens origin (see /origin), in cm, at which the point source will be placed. Defaults to 500.0

/freq

The frequency of the sound used in the lens system. This is normally set in the header file specified by /sys_header, but can be overridden here.

/head

The prefix for generated parameter files. Defaults to 't'.

/maxfiles

An array of strings containing the names of the template files to be used when creating the parameter files to find the maximum response of the lens system. This allows finding the maximum for several different types of elements. Defaults to ['template/point'].

/mouse

If set, allows the user to select the focal point search area using the mouse while viewing the ray trace plot.

/nomax

If set, will not generate files to find the focal points.

/origin

The origin of the lens system. Usually the center of the first lens surface. Defaults to [0.0,0.0,0.0].

/sys_header

The header file for the lens system. Specifies the water salinity, depth, and attenuation, the frequency of operation, number of rays to trace, and the view ranges, as well as the command parameters for CALC_LENS. Defaults to './template/system_header'.

/tail

The suffix for generated parameter files. Defaults to '_'+Temperature.

/Temperature

The ambient temperature at which the system will be operating, in degrees C. Defaults to 20 degrees C.

/verbose

If set, reports on progress as it goes.

/wateratten

The sound attenuation rate of water. Defaults to 0.04 db/cm.

If the output of BEAM THREE was stored in the file 'simple.opt':

3 surfaces        SING128.OPT          Units cm

Index     Zvx      F   DX    DY    CX   Curv       Mir/Ls
-------:----------:-:-----:------:----:--.-------:------:
1.00   : 300.     :S: 4.  : 20.0 : 0. :-0.026314 ? Lens :
0.5789 : 301.5    :S: 4.  : 20.0 : 0. : 0.031084 ? Lens :
1.00   : 345.9191 ?S: 4.  : 30.  : 0. :          : Film :
0.5789 : Syntactic Foam : 0.6983 : 2613.5 : -1.25 : 1.0 : 0.0

then GENERATE_SYSTEM would be run by: GENERATE_SYSTEM,'simple.opt'

Alternatively, this same data could be entered as:

header=['Index','Zvx','DX','DY','CX','Curv']
data= [string([1.00,300.0,4.0,20.0,0.0,-0.026314])] $
 ,[string([0.5789,301.5,4.0,20.0,0.0,0.031084])] $
 ,[string([1.00,345.9191,4.0,30.0,0.0,0.0])]]
mdata= ['0.5789 : Syntactic Foam : 0.6983 : 2613.5 : -1.25 : 1.0 : 0.0']

and run by:

GENERATE_SYSTEM,header,data,mdata

In either case, GENERATE_SYSTEM would generate a file called 't0_20':

/logfile        ; Use log file 'batch.log'
/nopressure     ; Do not do pressure calculation, only ray trace.
/trace2d        ; Do ray trace in xy plane only.
/summation      ; Do ray trace for summation method.
/savefile       ; Save results in filename.save
Sal=0           ; Water Salinity, parts per thousand
Depth=1.0       ; Water Depth, meters
freq=900k       ; Frequency, Hz
xrange=[0,65]   ; X range to display
yrange=[-25,25] ; Y range to display
num_rays=301    ; Number of rays to trace
waterdensity=1.0; Water Density, g/cm^3
wateratten=0.0  ; Water Attenuation Rate, dB/cm
Source=point    ; Source Type
-500.0,0.0,0.0  ; Point Source Location, cm
origin=[0,0,0]  ; Lens System Origin, cm
T=20.0          ; System Temperature, degrees C
waterspeed=0.0  ; Calculate Speed of Sound in Water
2               ; Number of Interfaces
aspherical      ; Lens Interface Type
300.0,0,0       ; Interface Vertex, cm
-0.0263140      ; Lens Curvature, 1/cm
1               ; Lens Shape Factor, 1/cm
20.0000         ; Lens Aperture, cm
0.0             ; Use Sound Speed for Water
1.00            ; Water Density, g/cm^3
0.0             ; Water Attenuation Rate, dB/cm

It would also generate a file to find the focal point of the system called 't0_20am':

restorefile=t0_20.save  ; Restore ray trace results.
/logfile        ; Use log file batch.log.
/summation      ; Use summation method of calculation.
line_max        ; Find focal point along line in a plane.
0.00,0.00,0.00  ; Origin of line.
340.75,345.0    ; Range along line to search.
0.00,0          ; Angle of line in xy plane, in xz plane, in degrees.
31,0.05         ; Number of coarse search points, accuracy of search.
point           ; Use a point element

GET_LOG(logfile [,/verbose,/tail])

Searches a log file for focus information. Returns an array containing the focal positions (in x,y,z triples), the angles corresponding to those focal positions (in degrees), and the magnitude of response at each focal position (in absolute units, not dB). The keyword parameter /tail specifies the parameter file suffix to search for. It defaults to 'am'. If /verbose is set, then GET_LOG reports its progress as it runs.

KCLEANPLOT

Resets all plot system variables to their defaults. Identical to CLEANPLOT, but doesn't reset !p.color to 255 (since that messes up Postscript output.)

newstring=

SUFFIX(oldstring)

Returns a string without its suffix. See SUFFIX.

outstring=

KILL_ZEROS(instring [,/all])

Deletes all trailing zeros off of a string. If the resulting string ends in a decimal point ('.'), then one zero is added back on, unless /all is set, in which case the trailing decimal point is deleted. Examples:

outstring=KILL_ZEROS('25.00000') 	; outstring is '25.0'
outstring=KILL_ZEROS('25.00000',/ALL)	; outstring is '25'
outstring=KILL_ZEROS('25.7500')		; outstring is '25.75'
outstring=KILL_ZEROS('25.000,34.5400')	; outstring is '25.0,34.54'
outstring=KILL_ZEROS('25.')		; outstring is '25.'

KLEGEND,labels [,optional parameters] [,keyword parameters]

Adds a legend to a plot. Any of the parameters (labels, plotsyms, linethick, xstart, ystart, linelength, and yspacing) may be specified by a keyword parameter of the same name instead of as a parameter. Keyword parameters are:

/labels

An array of strings which are the labels for each legend item.

/plotsyms

An array of the plot symbols for each item. If /plotsyms is a scalar, then all the plot symbols will be that number. Defaults to an array filled with the system default of !psym (normally a solid line with no marker symbols.)

/symsize

An array of symbol sizes, one for each entry in the legend. If /symsize is a scalar, then all symbol sizes will be that number. Defaults to an array of 1's.

/linethick

An array of the line thickness indices associated with each item. If /linethick is a scalar, then all the line thicknesses will be that number. Defaults to an array filled with the system default of !p.thick (normally 1).

/xstart

The x-coordinate of the left-hand side of the legend. See below for default.

/ystart

The y-coordinate of the top of the legend. See below for default.

/linelength

The amount of space allotted for the legend symbols (and possibly lines). Defaults to 1/20th of the plot width.

/yspacing

The distance between consecutive legend items. Defaults to 1/20th of the plot height.

/title

If set, the legend title.

/box

If set, a box is drawn around the legend.

Either labels or /labels must be specified, but KLEGEND will choose defaults for everything else if not given. /xstart will default to a value which results in the legend being centered in the center of the plot. /ystart will default to a value which results in the legend ending near the bottom of the plot. The other default values are listed with the parameter descriptions.

KPLOT,filename [,keyword parameters]

KPLOT,positions,values [,keyword parameters]

The program KPLOT is designed to display most of the data which CALC_LENS generates. It can plot beam patterns, surface plots, contour plots, and display images. The type of plot generated depends on the character of the data. Beam patterns can be displayed in rectangular or polar coordinates (to emulate a paper chart-recorder). In addition, it can find and display the 3 dB points of beam patterns and help the user to find sidelobe positions and measure sidelobe levels. Beam patterns can be displayed in magnitude or decibels, and if desired, KPLOT will simulate two_way beam patterns by squaring the data before plotting it. Many display options are available, including complete control over tick placement, grid styles, overplots, normalization or offsets, and colors.

There are two ways to invoke KPLOT. The first is with the file name of an output file generated by CALC_LENS. If filename has no tail (any string following a period) then the tail '.out' is appended. The second way to invoke KPLOT is by specifying the actual data which it is to plot. Two parameters must be given. The first, positions, is an Nx3 array holding the xyz coordinates of the data points. The second, values, is either an N element vector or an MxP element array (where N=M*P) which holds the actual complex data points generated by CALC_LENS.

In either case, the available keyword parameters are:

/contour

If the data is a matrix, then contour plot it instead of surface plotting it. If set to 2, display an image. If set to 3, display a smoothed image.

/db

Transform the data to dB (20.0*alog10(abs(data))).

/find3db

Find the 3 dB points on a beam pattern. Sets /db and /normalize . If /find3db is set to 2, also finds the sidelobe heights and positions (formerly /sidelobes.

/force_line

Forces KPLOT to interpret the data as points along a line (as opposed to angles, for example.)

/gridstyle

Line style of grid for plot.

/mirror

Mirror the data over the x-axis (for symmetric data).

/normalize

Normalize the data to magnitude of 1 or 0 dB.

/offset

Amount to offset the data. If set to a scalar, then offset is along the y-axis. If set to a two-element vector, then the first element is the offset along the x-axis and the second is along the y-axis.

/origin

Origin of beam pattern arc.

/shift

Amount to shift the data along the x-axis.

/print

Print the plot rather than displaying it on the screen.

/polar

Plot in polar form instead of rectangular.

/theta_scale

Scaling factor for x-axis values.

/two_way

Transform to two_way beam pattern (i.e. square the data).

/xticki

X tick interval (distance between ticks along x-axis).

/yticki

Y tick interval (distance between ticks along y-axis).

Also available are the standard keywords for plot, contour, and surface: /ax, /az, /charsize, /color, /c_color, /nlevels, /noerase, /psym, /symsize, /thick, /ticklen, /verbose, /title, /subtitle, /xtitle, /ytitle, /ztitle, /xrange, /yrange, /zrange, /xstyle, /ystyle, /zstyle, /xticks, /yticks, /zticks, /xtickv, /ytickv, /ztickv, /xminor, /yminor, and /zminor.

The default action for KPLOT depends on the type of data it is operating on. If the data is a vector, then the program assumes that it represents a beam pattern. It then looks at the vector of sampling positions. If this is simply a vector, then those values are assumed to be angles. If the sampling positions are given as points in 3-space, then POS2RETANG is called to convert them into angles (based on an arc centered at /origin) or points along a line. If the data is an array, then KPLOT will display it as a surface plot, unless /contour is set, in which case it will be displayed as a contour plot. If /contour is set to 2, then the data will be displayed as an image. If /contour is set to 3, then the image will be interpolated to provide a smoother display.

By linking several KPLOT commands together, a contour plot can be overlayed on top of an image:

KPLOT,filename,/db,/contour,nlevels=1
KPLOT,filename,contour=3,/noerase
KPLOT,filename,/db,/contour,/noerase

The magnitude of the data, which is normally complex, will be displayed unless /two_way or /db are set. If /two_way is set, then the data will be squared to simulate a two-way beam pattern. If /db is set, then the data will be converted to decibels, 20*alog10(abs(data)). If both /two_way and /db are set, then the data will be squared, then converted to decibels.

If /normalize is set, then the data will be normalized. If /db is not set, then the maximum magnitude will be set to 1. If /db is set, then the maximum value will be set to 0 dB.

If /offset is set, then the data will be shifted by the value of /offset. This is useful for comparing the attenuation displayed by various beam patterns. /normalize takes precedence over /offset, so if /normalize is set, then any value of /offset will be ignored.

If /theta_scale is set, then the theta (or x) axis will be scaled by /theta_scale.

If /shift is set, then the entire plot will be shifted along the x-axis by /shift.

If /mirror is set, then the data will be mirrored so that data from 0 to max will be extended to the range -max to max. For symmetric situations, this can halve the amount of computations required to be performed when calculating the beam pattern or pressure field.

/xticki and /yticki set the x and y tick intervals. This is useful for forcing the y tick intervals to 3 dB, for example. Normally, the x ticks will start with the minimum value of x (i.e. the left side of the plot) and the y ticks will start with the maximum value of y (i.e. the top of the plot). This can be changed, however, by setting /xticki or /yticki to a two element vector, where the first element is the tick interval and the second is the starting point.

If /gridstyle is set, then a grid will be displayed on the beam pattern plot. The line style of the grid will be set to /gridstyle. Grid lines will be drawn at the positions of the major ticks along both axes. If the tick positions aren't defined in any way, then KPLOT will attempt to choose "good" values for them, rather than let PV-WAVE do it. This is because there is no way to tell what values PV-WAVE has chosen, so the grid lines don't match up with the ticks.

If the data is to be displayed on a contour plot, then the number of contour levels can be set by /nlevels.

If /print is set, then the resulting plot will be sent to the printer instead of to the screen. Note that the plot is sent before the location of the 3 dB points are indicated (see /find3db) or sidelobes are located (see /sidelobes), so the printed plot will not show those extra lines. If a plot with those lines is desired, then set /print to 2 instead of 1 (i.e. print=2 instead of print=1 or /print). Also, for a screen plot without the extra lines, set /print to -1.

If /xtitle is not set, then it defaults to an indication of the type returned by POS2RETANG. If the beam pattern was based on positions along a line parallel to the x- axis, for example, /xtitle will be set to 'Axial distance (x-direction), cm'. If /theta_scale was set, then the string ' (Scaled by: ' and the amount of scaling will be added to /xtitle.

If /ytitle is not set, then it defaults to an indication of the data type. It begins with nmtitle, where nmtitle is 'Normalized' if /normalize was set, '(Relative)' if /offset was set, and '' if neither was set. To nmtitle is added 'Acoustic Pressure', then dbtitle, where dbtitle is ' (dB) (20log(abs))' if /db was set (or ' (dB) (20log(abs^2))' if /two_way was set). If /db was not set, then dbtitle is set to '(abs)' (or '(abs^2)' if /two_way was set).

If /polar is set, then the plot will be made in polar coordinates. A few options work differently when /polar is set. The /gridstyle and /sidelobe options are not available. A grid will always be drawn with /xticks grid lines spaced /xticki degrees apart in the theta direction. The grid in the magnitude (y) direction will be the same as if /polar was not set (although the grid lines will be curves instead of straight lines.) The default value for /xticki will be 1 degree and for /yticki will be 3 dB.

If /find3db is set, then the program will attempt to locate the 3 dB points, display them on the plot, and print the 3 dB beamwidth (the distance between the 3 dB points). This option also sets /db and /normalize. In addition, /dec can be set to fix the number of decimal points that will be displayed for the 3 dB beam width (the distance between the 3 dB points.)

If /sidelobes is set, then the user will be able to find sidelobes or other points of interest using the mouse. Hitting the left button will choose a point for one side of a search range. Hitting it again on another point will complete the search range, whereupon the program will print the maximum value within that range and the position of that maximum. Hitting the center button will choose whichever data point is closest to the cursor position and will print the value and position of that point. Hitting the right button will exit the program.

LASER [,/square,/encapsulated]

Changes the output device to postscript. The default output size is 7x5 inches in portrait mode, with the plot positioned near the top of the page. If /square is set, then the output size is 7x6.729 inches in order to ensure a square aspect ratio. If /encapsulated is set, then an encapsulated postscript file is created (for inclusion into other documents.)

LASER_SEND [,/printer]

After plotting a figure with the output device set to postscript, laser_send will send it to the printer. If /printer is not specified, then laser_send will attempt to get the default printer name from the environment variable PRINTER. If PRINTER isn't set either, then 'lp428' will be used as the default. After sending the plot, LASER_SEND will reset the output device to 'x'.

MAKE_BEAMS,angs [,/batchfile,/position,/head,/tail, /elementfile,/wateratten]

Generates parameter files which will calculate the response of an element at a single point. The results of these calculations can be concatenated together using CONCAT_RESULTS to form beam patterns. angs is an array of source angles which are to be calculated. The optional keyword parameters are:

/batchfile

The name of the file which will hold the batch instructions forrunning the generated parameter files. Defaults to 'batchb'.

/position

The xyz coordinates of the position of the element. Defaults to [5034.65,16.1582,0.0].

/head

The prefix for the output parameter files. Defaults to 't'.

/tail

The suffix for the output parameter files. Defaults to 'a'.

/elementfile

The template file for the element type. Defaults to '/home/kfink/work/template/point'.

/wateratten

The sound attenuation rate of water. Defaults to 0.04 db/cm.

MAKE_BEAMS1,angs,width,focifile,origin [,keyword parameters]

Generates parameter files which will calculate the beam pattern for an element by moving the element along the focal trajectory. angs is an array of source angles which are to be calculated. width is the range of angles in degrees to calculate for each source angle. focifile is the filename of the trajectory file generated by FOCI_CIRC origin is the origin of the lens system. Optional keyword parameters are:

/batchfile

The name of the file which will hold the batch instructions for running the generated parameter files. Defaults to 'batch'.

/head

The prefix for the output parameter files. Defaults to 't'.

/tail

The suffix for the output parameter files. Defaults to 'a'.

/elementfile

The template file for the element type. Defaults to 'template/point'.

/numpos

The number of points to calculate for each source angle. Defaults to 101.

MAKE_BEAMS2,origin,radius,angles,rayfile [,keyword parameters]

Creates parameter files to calculate beam patterns along an arc. The origin of the arc is specified by origin, and may be a 3-element vector, a scalar, an nx1 (nş3) vector, or an nx3 vector. In the first case, the origin is used as-is. In the second case, the origin is expanded to [origin,0.0,0.0]. In the third case, each element is expanded as in the second case. In the fourth case (and the third, after expansion), multiple parameter files are generated, one for each 3-element vector.

Radius may be a scalar, in which case it is used as the radius of curvature of the arc for all origin values. It may also be a vector, in which case each element generates a separate parameter file. If both the origin and radius represent multiple files, then one of two things can happen. If each represents the same number of files, then it is assumed that they are paired. Otherwise, a parameter file is generated for each combination of radius and origin.

Each arc generated must have the same endpoints, which are specified as angles in degrees. The saved ray-trace data is specified in rayfile. Rayfile, without the (optional) trailing '.save', is also used as the base for the parameter file names. Onto the base is added /tail then consecutive numbers starting with /start.

Optional keyword parameters are:

/batchfile

The name of the file which will hold the batch instructions for running the generated parameter files. Defaults to 'batch'.

/head

The prefix for the output parameter files. Defaults to 't'.

/tail

The suffix for the output parameter files. Defaults to 'a'.

/start

The starting number for the output parameter files. Defaults to 1.

/elementfile

The template file for the element. This file is concatenated onto the end of each generated parameter file. Defaults to '/home/kfink/work/template/point'.

/numpos

The number of points to calculate for each beam pattern. Defaults to 101.

MAKE_LINE_MAX,filename [,/savefile,/plot,/afile,/tail,/batchfile]

Generates a parameter file which will find the maximum absolute pressure of a lens system along a line. Filename is the file name of the lens system parameter file. If /savefile is not set to a string, then it will be set to filename with '.save' appended to the end, which matches the default save file name generated by CALC_LENS. /Savefile is used as the name of the PV-WAVE data file which will be restored to provide information about the ray trace results. The parameter file will be saved in filename+/tail, where /tail defaults to 'am'. The template file for the element is /afile, which defaults to '/home/kfink/work/template/point'. If /plot is set, then the line which will be searched for the maximum will be displayed. The command to run the parameter file from PV-WAVE will be saved in the file /batchfile, which defaults to 'batch'.

MAKE_MAX_REGION,file1 [,file2,/overwrite,/batchfile,/box]

This program generates a CALC_LENS parameter file which will find the maximum pressure within a region. The region can be selected by setting the keyword parameter /box to the coordinates of the region's lower-left and upper-right corners, or by using the mouse to select an area of the plot (see MOUSEBOX). If called with one parameter, that parameter is used as the output file name and the current plot is used for input. If called with two parameters, then the first is a CALC_LENS system parameter filename which is used to display the ray trace plot and the second is the output file name. If /overwrite is set, then the output file will be automatically overwritten, if it exists. Otherwise, the program will query the user if the output file already exists. The instructions for MOUSEBOX describe how to choose the region. The command to run the parameter file from PV-WAVE will be saved in the file /batchfile, which defaults to 'batch'.

MAKE_VOLUME,file1 [,file2,/xpts,/ypts,/overwrite,/dec ,/batchfile]

This program works identically to MAKE_MAX_REGION, but generates a parameter file which will calculate an array of pressures within the region. The keyword parameters /xpts and /ypts are the number of points in each direction to specify in the parameter file. The default values are both 25, for a total of 625 points (this takes about 1 minute and 40 seconds to compute). The keyword parameter /overwrite forces MAKE_VOLUME to overwrite file2 if it exists. Otherwise, MAKE_VOLUME will ask the user whether or not to erase the old file. /dec specifies the number of decimal points to round the coordinates of the selected region's boundaries to. MAKE_VOLUME saves the command needed to execute the parameter file it creates in the batch file specified by /batchfile, which defaults to 'batch'.

MAN,program_name

This program gives a brief summary of a PV-WAVE program, including the header line, which shows the parameters and keyword parameters. It displays any comment lines (those starting with a semi-colon) before the header line, plus any comments which immediately follow the header line. Example: MAN,'calc_lens'

point=MOUSEBOX( [file] )

This program allows the user to select a region of a plot using the mouse. It returns the lower-left and upper-right coordinates of the region. If file is not specified, then the current screen plot is used. If file is given as a CALC_LENS system parameter file, then CALC_LENS will be called to display the ray trace for it. This also enables the zoom features of mousebox.

Pressing the left mouse button fixes the first corner of the box. The box will be drawn from that point to the current mouse position until the left button is released, which fixes the opposite corner of the box. This can be repeated until the box covers the desired region. Pressing the right button chooses the current box, returning the coordinates. Zooming: If file is given mousebox can redraw the display to any scale. With the cursor in the plot window, pressing the center button will zoom the display in to the selected region. With the cursor in the PV-WAVE window, there are several options. Pressing the 'r' key will redraw the plot at the present scale. Pressing the '0' key will reset the plot to the original scale. Pressing the 'o' key will zoom out by 50%. Pressing the 'i' key will zoom in by 50%. Pressing a number key from 1 to 9 will zoom out by 10 to 90%.

angles=POS2RETANG(positions ,[/origin,/xy,/force_angle])

Returns the angles or positions associated with the points in 3-space held in positions. The final element of angles holds the type of conversion performed to form angles from positions. If positions is a vector, then it is returned with a final element of 0 (no conversion) added. If /xy is set then POS2RETANG assumes that the first two columns of positions contain the x and y coordinates of data points on an arc, and the type is set to 6. If /force_line is set, then POS2RETANG assumes that positions corresponds to points on a line and returns the data in spatial coordinates rather than angles.

Otherwise, if two columns are constant, then the third is returned with type 1, 2, or 3, depending on whether that column was the first, second, or third. If only one column is constant, then the other two are assumed to be data points on an arc, and the type is set to 4, 5, or 6, depending on which column was constant (x, y, or z, respectively).

If POS2RETANG decides that the data corresponds to points on an arc (or /xy was set), then the data is converted to angles in degrees. The arc is centered at /origin, which defaults to [0,0,0].

outvector=RANGE(min,max,num)

Returns a vector of num elements evenly spaced from min to max. If num is 1, then the average of min and max is returned.

answer=SIGN(value)

Returns the sign (+/- 1) of value.

outstring=SPLIT_STRING(instring [,/separator])

Breaks instring up into an array of strings. The input string is broken at each occurrence of /separator, which defaults to ','. The /separator string is not included in the output array.

answer=STACK(in0 [,in1,in2,in3,in4,in5,in6,in7,in8,in9])

Returns concatenation of input vectors "stacked" next to each other. Each input vector forms a column in the output array. Up to 10 vectors can be stacked per call.

array=STRING2ARRAY(instring [,/len])

Break a string up into an array of floating point numbers. Discards comments at the end of the line and any square brackets (' [' and ']'), then converts the remaining comma or space-delimited string into floats. If /len is set, then the resulting array always has /len elements. If the input string was too long, then the output array is truncated. If it was too short, then the output array is padded with zeros.

out=STRPOSS(string,object [,/pos])

Similar to STRPOS (see PV-WAVE manual), but finds ALL occurrences of the object string rather than just the first. Returns an array containing the indices of each occurrence of object in string starting at position /pos. If /pos is not specified, it defaults to 0 (the first character of the string.)

outstring=SUFFIX(instring)

Returns the suffix of instring (usually a file name.) The suffix is defined as that part which lies after the final period ('.') in a string.

tabstring=TAB(number)

Returns a string containing number tab characters.

tabstring=TAB(string)

Returns a string containing 3-strlen(string)/8 tabs. Used to create parameter files in which the beginnings of the comments line up at 3 tabs over.

outstring=UNQUOTE(instring)

Removes single and double quotes (' and ") from instring.

phase=UNWRAP(data [,/tolerance])

Performs a phase unwrapping operation on a vector. Data should be a complex-valued vector. Returns the unwrapped phase. /Tolerance, which defaults to 0.8, determines how large a phase jump must be to be considered wrap-around.

phase=UNWRAP2D(data [,/tolerance)]

Same as unwrap, but works on an complex-valued array instead of a vector.

answer= VEQ(vec1,vec2)

Returns 1 if two vectors are equal. If one vector is a scalar, then returns 1 if every element of the other vector is equal to that number.

len= VLEN(vector)

Returns Euclidean length of a vector (the dot product of the vector with itself.)

WIN,num [,keyword parameters]

Simple way to open windows. The parameter num can be either 0 or 1. Window 0 is in the lower-right-hand corner of the screen and window 1 is in the upper-right-hand corner. Keyword parameters:

/square

Makes window square instead of rectangular.

/xsize

Number of pixels in x-direction. Default is 565.

/ysize

Number of pixels in y-direction. Default is 454.

X

Resets the output device to 'x' after closing the Postscript device.

Go back to the Description of CALC_LENS

Go to the TROUBLESHOOTING GUIDE