This page was created by the IDL library routine
mk_html_help. For more information on
this routine, refer to the IDL Online Help Navigator
or type:
? mk_html_help
at the IDL command line prompt.
Last modified: Thu Sep 12 17:21:28 1996.
NAME:
ABGRAD
PURPOSE:
Calculates the absolute value of the gradient of a function represented
as an array of values. Works for 1-7 dimensions.
CATEGORY:
Array Manipulation
CALLING SEQUENCE:
Result = ABGRAD( ARR [, DELTA])
INPUTS:
ARR
Array, numeric, number of dimensions can be 1 through 7
OPTIONAL INPUT PARAMETERS:
DELTA
Size of step used to calculate the numeric derivatives. The approx.
partial derivative in the i-th direction is calculated as
(ARR(...,I + DELTA,...) - ARR(...,I - DELTA,...))/(2*DELTA).
The default value of DELTA is 1l. If provided, it is rounded to a long
integer on input.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Returns the absolute value of the gradient as an array of the same size
and type as ARR. If ARR is not an array, returns 0.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
Due to current limitations of the MAKE_ARRAY system routine, 8
dimensions are not allowed.
PROCEDURE:
Creates an 7-dimensional array, with dummy leading dimensions,
containing the original array. Generates the differences using the
SHIFT system routine and strips the dummy dimensions at the end.
Uses the function DEFAULT from MIDL.
MODIFICATION HISTORY:
Created 15-NOV-1991 by Mati Meron.
(See IDL_USER:[MERON]ABGRAD.PRO;1)
NAME:
ARC
PURPOSE:
Draws a circular arc in the currently defined plot area. DATA
coordinates are used. The method of drawing depends on the number of
input parameters provided (see details in CALLING SEQUENCE below).
CATEGORY:
General Graphics.
CALLING SEQUENCE:
There are two possible modes of operation, and accordingly two
different calling sequences:
Mode 1:
ARC, R1, CENTER = CENT, ANGLE = ANG [, optional keywords]
In this mode an arc with angular measure ANG is drawn around the point
CENT, in the mathematical-positive direction, starting from point R1.
Mode 2:
ARC, R1, R2, {RADIUS = RAD, ANGLE = ANG} [, optional keywords]
In this mode the arc is drawn in the mathematical-positive direction,
from point R1 to point R2. The arc is either drawn with radius RAD, or
corresponding to an angle ANG (both RAD and ANG cannot be specified).
INPUTS:
R1, R2
2-dimensional vectors in the [x,y] format, representing points in the
plotting area. R1 is mandatory. The presence of R2 indicates that
Mode 2 is being used.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
CENTER
2 dimensional vector, arc center location, format [x,y].
Mandatory in Mode 1, forbidden in Mode 2.
RADIUS
Scalar, the radius of the arc. |
Forbidden in Mode 1, allowed in Mode 2. | In Mode 2
ANGLE | one and only one
Scalar, the angle measure of the arc. | needs to be provided.
Mandatory in Mode 1, allowed in Mode 2. |
/DEGREES
Switch. Indicates that the angle ANG is given in degrees (default is
radians).
/BIGARC
Switch. When drawing in Mode 2, with the radius provided, there are two
possible arcs that can be drawn, corresponding to angles smaller and
bigger than 180 degrees (the sum of both angles is 360 degrees). By
default the smaller arc is drawn. Setting BIGARC selects the bigger arc.
/SYMMETRIC
Switch. In Mode 1 causes the arc to be drawn symmetrically on both
sides of R1. Forbidden in Mode 2.
_EXTRA
A formal keyword used to pass all plotting keywords. Not to be used
directly.
OUTPUTS:
None.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
The arc will appear as a true circular arc only if the aspect ratio of
the X to Y axes is 1:1.
The keywords passed through _EXTRA are transferred to the PLOTS
routine. No keyword verification is performed by ARC.
PROCEDURE:
Uses calls to ONE_OF and SHAPE_COCON from MIDL.
Generates a (2,N) array containing a sufficient number of the arc
points to yield a smooth curve. N is variable, depending both on the
arc size and on the pixel size of the current output device.
MODIFICATION HISTORY:
Created 15-DEC-1991 by Mati Meron.
Modified 15-DEC-1993 by Mati Meron. Now ARC takes advantage of the
keyword inheritance property and accepts all PLOTS keywords.
Modified 15-JUN-1995 by Mati Meron. Removed the ALT_EXT keyword which
is no longer needed (_EXTRA has been fixed).
(See IDL_USER:[MERON]ARC.PRO;1)
NAME:
ARREQ
PURPOSE:
Compares arrays for equality. The arrays qualify as equal if:
1) They are of the same general type (num., char., or struct.).
2) Number of dimensions is the same.
3) Size of each dimension is the same.
4) Respective elements are equal.
CATEGORY:
Mathematical Function (general).
CALLING SEQUENCE:
Result = ARREQ( ARR1, ARR2 [, keywords])
INPUTS:
ARR1, ARR2
Arrays, type and number of dimensions arbitrary.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
/WARN
Switch. If set, a warning message is issued for incompatible data types.
/NOVALUE
Switch. If set, only number of elements and structure are compared.
OUTPUTS:
Returns 1 if the arrays are equal, 0 otherwise.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Uses the SIZE function to obtain information about the arrays.
Compares, in order, data types, number of dimensions, size of each
dimension and (unless NOVALUE is set) individual elements.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
(See IDL_USER:[MERON]ARREQ.PRO;1)
NAME:
ARRLOC
PURPOSE:
Converts array indices from expanded (multi dimensional) form to
contracted (one dimensional) form and vice versa.
CATEGORY:
Array Function.
CALLING SEQUENCE:
Result = ARRLOC( INDS, SIZ [, keywords])
INPUTS:
INDS
Numeric, converted to long integer on input. Structure depends on
usage mode (EXPAND versus CONTRACT) and on the input parameter SIZ, as
follows:
EXPAND mode : INDS can be a scalar or a vector (1-dim array).
CONTRACT mode: If SIZ(0) = 0 then INDS arbitrary. Else INDS can
be a scalar, vector or a 2-dim array, subject to the following
restrictions:
INDS is scalar: SIZ(0) must be 1.
INDS is vector: SIZ(0) must equal the length of INDS.
INDS is M*N array: SIZ(0) must equal M (first array dimension).
SIZ
Vector in the form of the standard output of the system function SIZE.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
/EXPAND
Switch, specifies expansion mode. This is the default.
/CONTRACT
Switch, specifies contraction mode.
OUTPUTS:
Depending on mode, as follows:
EXPAND mode: Returns an M*N array, where M is the number of dimensions
of the object charactarized by SIZ (i.e. SIZ(0)) and N is the
number of elements in INDS. For example, if S = [2,3,8,4,24]
(corresponding to a 3*8 real array) then ARRLOC(5,S) will return
the vector [2,1] (the indices of the 5th element) while
ARRLOC([2,5,22]) will return: 2 0
2 1
1 7
CONTRACT mode: Reverses the action of expand. When fed an array in
the form of the output of ARRLOC with EXPAND, returns a vector of
1-dimensional indices. For example a call to ARRLOC using S and
the output array from the example above will return: 2
5
22
In either mode, if any of the resulting indices is out of bounds for the
array specified by SIZ, it is replaced by -1.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None other than those specified in the description of INDS, above.
PROCEDURE:
Straightforward. Calls ONE_OF from MIDL.
MODIFICATION HISTORY:
Created 30-MARCH-1994 by Mati Meron.
(See IDL_USER:[MERON]ARRLOC.PRO;1)
NAME:
ARRO.
PURPOSE:
Draws an arrow in the current plot area, from the FROM to the TO
location. DATA coordinates are used, unless one of the keywords
/DEVICE or /NORMAL is set.
CATEGORY:
General Graphics.
CALLING SEQUENCE:
ARRO, FROM = tail, TO = head [, keywords]
INPUTS:
None.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
FROM
Two dimensional vector, start location, mandatory.
TO
Two dimensional vector, end location, mandatory.
SIZE
Scalar, specifies size of head [and tail], default is 1.
/TAIL
Switch. Puts a tail on the arrow.
/TWOSIDED
Switch. Draws a twosided arrow (heads on both ends).
/DEVICE
Standard IDL plotting interpretation.
/NORMAL
Ditto.
_EXTRA
A formal keyword used to pass all plotting keywords. Not to be used
directly.
OUTPUTS:
None.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
The keywords passed through _EXTRA are transferred to the PLOTS
routine. No keyword verification is performed by ARRO.
PROCEDURE:
Uses DEFAULT, ONE_OF, SHAPE_COCON, SHAPE_TRANS and WHERINSTRUCT
from MIDL. All the coordinates are converted to DEVICE coordinates for
shape generation and plotting purposes.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
Modified 15-DEC-1991 by Mati Meron. Added keywords COLOR and TWOSIDED.
Modified 15-DEC-1993 by Mati Meron. Now ARROW takes advantage of the
keyword inheritance property and accepts all IDL plotting keywords.
Modified 5-OCT-1994 by Mati Meron. Name changed to ARRO to avoid
conflicts with library routines.
Modified 15-JUN-1995 by Mati Meron. Utilizes WHERINSTRUCT for improved
keyword inheritance.
(See IDL_USER:[MERON]ARRO.PRO;1)
NAME:
ASP_CORR
PURPOSE:
Corrects the aspect ratio of a 2-dimensional shape, in order to make up
for for different scaling in the x and y dimensions.
CATEGORY:
Array Manipulation /General Graphics.
CALLING SEQUENCE:
Result = ASP_CORR( SHAPE, REFERENCE = reflin)
INPUTS:
SHAPE
(2,*) numeric array, mandatory.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
REFERENCE
Defines the scaling procedure, according to the provided character
value. Accepts one of the following six values (only the first two
characters matter):
'XLO' : Scale x, keeping lowest x-value constant.
'XCEN': Scale x, keeping center x-value constant.
'XHI' : Scale x, keeping highest x-value constant.
'YLO' : Scale y, keeping lowest y-value constant.
'YCEN': Scale y, keeping center y-value constant.
'YHI' : Scale y, keeping highest y-value constant.
OUTPUTS:
0 in case of failure (bad or missing shape or keyword value), otherwise
the transformed shape is returned as a floating array (double if the
input is of type double)
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
Three dimensional shapes aren't currently accepted.
PROCEDURE:
Uses calls to CAST, DEFAULT, SHAPE_VER and STRMATCH from MIDL. The
scaling is done using the sizes of the plotting area in device
coordinates, provided by the system variables !d.x_vsize and
!d.y_vsize. Therefore the scaling is always proper for the current
output device.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
(See IDL_USER:[MERON]ASP_CORR.PRO;1)
NAME:
BESELK
PURPOSE:
Calculates an approximation to Bessel K functions or their integrals.
CATEGORY:
Mathemetical Function (General).
CALLING SEQUENCE:
Result = BESELK (X, NI [, /INTEGRAL ])
INPUTS:
X
Numerical, otherwise arbitrary.
NI
Scalar, the order of the function.
OPTIONAL INPUT PARAMETERS:
EPS
Allowed relative error. Default is ~ 1e-7.
KEYWORD PARAMETERS:
/INTEGRAL
Switch, if set the integral of the K function from X to infinity is
calculated.
OUTPUTS:
Returns the value(s) of K_ni(X) or, if INTEGRAL is set, of the integral
of K_ni(t) from X to infinity.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Uses the Kostroun approximation, see NIM 172, 371-374 (1980).
Calls DEFAULT, ISNUM and TOLER from MIDL.
MODIFICATION HISTORY:
Created 1-MARCH-1993 by Mati Meron.
(See IDL_USER:[MERON]BESELK.PRO;1)
NAME:
BOX
PURPOSE:
Creates an empty plot area, with boundaries defined by XLIMS and YLIMS.
CATEGORY:
General Graphics.
CALLING SEQUENCE:
BOX, XLIMS, YLIMS [, keywords]
INPUTS:
XLIMS, YLIMS
2 dimensional vectors, format: [xmin,xmax] and [ymin,ymax] respectively.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
/BORDER
Switch. Draws a border around the plot area. Default - no border.
/OVER
Switch. Creates the plot area over an existing plot. Default - new
plot area.
TRUASP
Corrects the XLIMS or YLIMS values to yield a 1:1 aspect ratio.
Accepts six possible character values (only first 2 characters matter):
'XLO' : Scale x, keeping lowest x-value constant.
'XCEN': Scale x, keeping center x-value constant.
'XHI' : Scale x, keeping highest x-value constant.
'YLO' : Scale y, keeping lowest y-value constant.
'YCEN': Scale y, keeping center y-value constant.
'YHI' : Scale y, keeping highest y-value constant.
_EXTRA
A formal keyword used to pass all plotting keywords. Not to be used
directly. See comment in RESTRICTIONS.
OUTPUTS:
None.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
The keywords passed through _EXTRA are transferred to the PLOTS
routine. No keyword verification is performed by BOX.
PROCEDURE:
Uses calls to CAST, and STRMATCH from MIDL. The scaling is done using
the sizes of the plotting area in device coordinates, provided by the
system variables !d.x_vsize and !d.y_vsize. Therefore the scaling is
always proper for the current output device.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
Modified 15-DEC-1991 by Mati Meron. Added keyword COLOR.
Modified 15-DEC-1993 by Mati Meron. Now BOX takes advantage of the
keyword inheritance property and accepts all IDL plotting keywords.
Modified 1-MAY-1995 by Mati Meron. Improved aspect ratio correction.
(See IDL_USER:[MERON]BOX.PRO;1)
NAME:
CAST
PURPOSE:
Generalized type casting. Converts all variables whose type code is
out of the range [LOW,HIGH] into this range.
CATEGORY:
Type conversion
CALLING SEQUENCE:
Result = CAST( X, [LOW [,HIGH]])
INPUTS:
X
Numerical, arbitrary, or a character representation of a number(s).
LOW
Number representing a type code, range (1:9). If greater than 9, it is
set to 9. If less then 1, or not given, it is set to 1.
OPTIONAL INPUT PARAMETERS:
HIGH
Type code, same as LOW. Default value is 9. If provided and less then
LOW, it is set to LOW.
KEYWORD PARAMETERS:
None.
OUTPUTS:
If the type of X is < LOW, CAST returns X converted to type LOW.
If the type of X is > HIGH, CAST returns X converted to type HIGH.
Otherwise CAST returns X.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
1) An attempt to convert a string which is NOT a character
representation of a number into a numeric type will yield error.
2) X cannot be a structure (but can be a structure element).
3) The value 8 for either LOW or HIGH is not allowed (since it
corresponds to structure type).
PROCEDURE:
Identifies the type of X, and if out of the range given by [LOW,HIGH]
calls the proper conversion routine using the system routine
CALL_FUNCTION. Also uses TYPE from MIDL.
MODIFICATION HISTORY:
Created 25-DEC-1991 by Mati Meron.
Modified 15-JUN-1995 by Mati Meron to accept the new DOUBLECOMPLEX type.
(See IDL_USER:[MERON]CAST.PRO;1)
NAME:
CHEBYSHEV_POL
PURPOSE:
Calculates Chebyshev polynomials Tn and associated functions.
CATEGORY:
Mathematical function.
CALLING SEQUENCE:
Result = CHEBYSHEV_POL( X, N, [ /ASSOCIATED])
INPUTS:
X
Numeric, absolute values must be <= 1, otherwise arbitrary.
N
Nonnegative scalar, rounded to integer on input. Defaults to 0.
OPTIONAL INPUT PARAMETERS:
None
KEYWORD PARAMETERS:
/ASSOCIATED
Switch. When set, an associated function, SIN(N*ARCCOS(X)) is returned.
OUTPUTS:
Returns the values of the Chebyshev polynomial T(n,x), defined as
COS(N*ARCCOS(X)) or (when ASSOCIATED is set), the values of the
associated Chebyshev function, SIN(N*ARCCOS(X)).
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None other then the restrictions on X, and N as mentioned above.
PROCEDURE:
Using the mathematical definition. Calling DEFAULT from MIDL.
MODIFICATION HISTORY:
Created 20-DEC-1994 by Mati Meron.
(See IDL_USER:[MERON]CHEBYSHEV_POL.PRO;1)
NAME:
CIRCLE
PURPOSE:
Draws a circle, around CENTER, with radius given by RADIUS, X_RADIUS,
or Y_RADIUS. The drawing is done in the currently defined plot area.
One and ONLY ONE of the three radius values MUST be provided. RADIUS
and X_RADIUS are equivalent. DATA coordinates are used unless one of
the keywords /DEVICE or /NORMAL is set. The circle is drawn so as to
appear visually as a circle, regardless of the coordinates used.
CATEGORY:
General Graphics.
CALLING SEQUENCE:
CIRCLE, CENTER = C, {RADIUS=R, X_RADIUS=XR, Y_RADIUS = YR} [, keywords]
INPUTS:
None.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
CENTER
Two dimensional vector, circle center location, mandatory.
RADIUS |
Scalar, value of radius (measured in the X direction). | One
X_RADIUS | and only one
Scalar, value of radius (measured in the X direction). | must be
Y_RADIUS | provided.
Scalar, value of radius (measured in the Y direction). |
/FILL
Switch. causes the circle to be filled with a solid pattern.
/DEVICE
Standard IDL plotting interpretation.
/NORMAL
Ditto.
_EXTRA
A formal keyword used to pass all plotting keywords. Not to be used
directly. See comment in RESTRICTIONS.
OUTPUTS:
None.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
While nominally all graphics keywords can be passed (through _EXTRA),
care should be exercised to use only the applicable ones (ELLIPSE and
PLOTS keywords usually, POLYFILL keywords when /FILL is used.
PROCEDURE:
Uses calls to COO_CONV and ONE_OF from MIDL. Converts all parameters
to device coordinates and calls ELLIPSE (also from MIDL) to do the
actual plotting.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
Modified 15-DEC-1993 by Mati Meron. Now CIRCLE takes advantage of the
keyword inheritance property and accepts all IDL plotting keywords.
(See IDL_USER:[MERON]CIRCLE.PRO;1)
NAME:
CONFRAC
PURPOSE:
Performs continued fraction evaluation.
CATEGORY:
Mathematical function (general).
CALLING SEQUENCE:
Result = CONFRAC( A, B [,X [, keywords]])
INPUTS:
A
A numeric scalar, vector or a 2-D array. A(i,*) contains the i-th
A coefficient(s) of the continued fraction.
B
Same as A for the B coefficient(s). A and B must agree in their first
dimension, i.e. if A is an (N,M) array (including the possibility of
M = 1) then B must be an (N,M') array, with an arbitrary M'.
OPTIONAL INPUT PARAMETERS:
X
Numeric, otherwise arbitrary. When provided, X is used together with
A and B to determine the continued fraction coefficients.
KEYWORD PARAMETERS:
AFUNCTION
Name of a function to be used (with the CALL_FUNCTION routine) to
determine the A coefficients. Optional.
BFUNCTION
Same as AFUNCTION for the B coefficients. Optional.
EPSILON
Smallness parameter, determining the allowed evaluation error.
Optional. Default values are around 1.2e-7 for single precision and
4.4e-16 for double.
/RELATIVE
Switch. If set, EPS represent the allowed relative evaluation error.
ERROR
Optional output, see below.
STATUS
Optional output, see below.
OUTPUTS:
Returns the value(s) of the continued fraction. The result is of the
same format as X (a scalar if X is not given). The type of the result
is the highest of the types of A, B, and X, but no lower than 4 (float).
OPTIONAL OUTPUT PARAMETERS:
ERROR
The name of the variable to receive the estimated evaluation error.
Given in the same format as X (scalar if X isn't provided). If
RELATIVE is set the error returned is relative.
STATUS
The name of the variable to receive evaluation status information.
Same format as ERROR. Possible values are:
0 - evaluation didn't converge.
1 - OK.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None other then the restrictions on A, B, as mentioned above.
PROCEDURE:
CONFRAC evaluates continued fractions of the form
res = a(0)/(b(0) + a(1)/(b(1) + a(2)/(b(2) + ......
Using the recurrence relation from Numerical Recipies, Sec 5.2. The
designation of the coefficients a(i), b(i) depends on the data
provided, as follows:
1) If X isn't provided then a(i) = A(i) (or A(i,0) if A is a 2-dim
array) and same is true for b(i) (using B)
2) If X is provided then a(i) = Sum_j(A(i,j)*X^j) and the same for b(i)
using B. In other words the fraction coefficients are polynomials
in X, using columns of A, B, as polynomial coefficients. Note that
if A and/or B are one dimensional arrays then only X^0 is used i.e.
we are back to case 1.
3) If AFUN and/or BFUN are provided then a(i) = afun(x,A(i,*),i) and
same for b(i) with BFUN and B. the functions can be arbitrary but
they must accept at least three parameters.
CONFRAC uses CAST, DEFAULT, POLEVAL, TOLER and TYPE from MIDL.
MODIFICATION HISTORY:
Created 20-DEC-94 by Mati Meron.
(See IDL_USER:[MERON]CONFRAC.PRO;1)
NAME:
CONSTANTS
PURPOSE:
Creates or updates a system variable named !PCON. !PCON is a structure
the fields of which contain values of physical constants as follows:
!PCON
USYS - Unit System. Either 'MKS' or CGS'.
C - Speed of light.
E - Electron charge.
H - Planck constant.
ME - Electron mass.
K - Boltzman constant.
NA - Avogadro constant.
ECONV - Used internally for unit conversion.
HBAR - Planck constant divided by 2*pi.
ALPHA - Fine structure constant.
AMU - Atomic mass unit.
SIGMA - Stefan-Boltzman radiation constant.
All the values are given in a double precision format. Of course, the
actual accuracy depends on how precisely they can be measured.
CATEGORY:
Utility.
CALLING SEQUENCE:
CONSTANTS [,/MKS or /CGS]
INPUTS:
None
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
/MKS
Switch. Sets the units system to MKS. This is also the default.
/CGS
Switch. Sets the units system to CGS. Default is MKS.
OUTPUTS:
None
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
M_CONS. Contains a single parameter, EXISTS.
SIDE EFFECTS:
None.
RESTRICTIONS:
Can't use both MKS and CGS at the same time.
PROCEDURE:
Either creates or, if EXISTS is defined, updates the system variable
!PCONS. Uses ONE_OF from MIDL.
MODIFICATION HISTORY:
Created 30-MAR-1994 by Mati Meron.
(See IDL_USER:[MERON]CONSTANTS.PRO;1)
NAME:
COO_CONV
PURPOSE:
Transforms values between the coordinate systems supported by IDL.
Allowed coord systems are DATA, DEVICE (only for X, Y axes) and NORMAL.
Functionally similar to the IDL function CONVERT_COORD, COO_CONV is
maintained for historical reasons.
CATEGORY:
Plotting /General Graphics.
CALLING SEQUENCE:
Result = COO_CONV( R, AXIS = AX [, keywords])
INPUTS:
R
numeric, otherwise arbitrary, assumed to be a coordinate(s) in the
direction specified by AXIS.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
AXIS
Sets the transformation axis. Accepts either a numeric value, one of
(0, 1, 2) or a character value (only first character matters), one of
('X', 'Y', 'Z'). Mandatory.
FROM
Character value (only first 3 characters matter), specifies input
coord. system. One of ('DATA','DEVICE','NORMAL'). Defaults to 'DATA'.
TO
Same as FROM. Specifies output coord. system.
OUTPUTS:
'' (0 length string) in case of failure (bad keyword value), otherwise
returns the transformed value as floating (or double if the input is
of type double)
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Uses calls to CAST, DEFAULT, ISNUM, STREQ, STRMATCH and TYPE from MIDL.
Converts coordinates using values provided by relevant system variables.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
(See IDL_USER:[MERON]COO_CONV.PRO;1)
NAME:
DEFAULT
PURPOSE:
Provides an automatic default value for nondefined parameters.
CATEGORY:
Programming.
CALLING SEQUENCE:
Result = DEFAULT( X, Y [, keywords])
INPUTS:
X, Y
Arbitrary, at least one needs to be defined.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
/STRICT
Switch. If set, X is considered defined only if it is of the same type
as Y.
/DTYPE
Switch. If set, the result will be typecast into the type of Y.
Explicit settings for LOW and/or HIGH (see below) override DTYPE.
LOW
Numeric value between 1 to 9 (8 is excluded). If given, the result is
of type >= LOW.
HIGH
Numeric value between 1 to 9 (8 is excluded). If given, the result is
of type <= HIGH.
OUTPUTS:
X if it is defined, otherwise Y.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
All type casting is bypassed if the result is of type 8 (STRUCTURE).
PROCEDURE:
Uses the functions CAST and TYPE from MIDL.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
Modified 15-NOV-1993 by Mati Meron. The keyword TYPE has been replaced
by STRICT. Added keywords DTYPE, LOW and HIGH.
(See IDL_USER:[MERON]DEFAULT.PRO;1)
NAME:
DEGLITCH
PURPOSE:
Replaces exceptional array elements by the average of their neighbors.
CATEGORY:
Array Function.
CALLING SEQUENCE:
Result = DEGLITCH( ARR, THRESH [, keywords])
INPUTS:
ARR
Array, numeric, otherwise arbitrary.
THRESH
Threshold value for element replacement. Must be > 1.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
/DOWN
Switch. If set the correction is downward, i.e. elements which are too
big (in absolute value) are replaced. This is the default.
/UP
Switch. If set the correction is upward, i.e. elements which are too
small (in absolute value) are replaced.
COUNT
Optional output, see below.
OUTPUTS:
Returns the corrected array, i.e. an array of the same format as ARR,
in which all the exceptional element have been replaced by the average
of their neighbors.
OPTIONAL OUTPUT PARAMETERS:
COUNT
The name of the variable to receive the number of exceptional elements.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Compares the absolute values of the original array and the one obtained
by neighborhood averaging. Locates exceptions and replaces them by
neighborhood average. Uses ONE_OF and NEIGHBORS from MIDL.
MODIFICATION HISTORY:
Created 30-MARCH-1994 by Mati Meron.
(See IDL_USER:[MERON]DEGLITCH.PRO;1)
NAME:
DIAGOARR
PURPOSE:
Creates a diagonal square matrix with the elements of a given vector on
the diagonal.
CATEGORY:
Array Manipulation.
CALLING SEQUENCE:
Result = DIAGOARR(VEC)
INPUTS:
VEC
Vector.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Return a square N*N (N is the vector's dimension) matrix, with the
elements of VEC on the diagonal and zeroes elsewhere.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward. Calls TYPE from MIDL.
MODIFICATION HISTORY:
Created 20-MAY-1993 by Mati Meron.
(See IDL_USER:[MERON]DIAGOARR.PRO;1)
NAME:
DIAGOVEC
PURPOSE:
Extracts the diagonal of a square matrix as a vector.
CATEGORY:
Array Manipulation.
CALLING SEQUENCE:
Result = DIAGOVEC(ARR)
INPUTS:
ARR
Array, 2-dimensional, square.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
If ARR is a square matrix, returns the diagonal as a vector, else
generates an error message.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward.
MODIFICATION HISTORY:
Created 20-DEC-1991 by Mati Meron.
(See IDL_USER:[MERON]DIAGOVEC.PRO;1)
NAME:
ELLIPSE
PURPOSE:
Draws an ellipse, around CENTER, with radii given by RADII, optionally
rotating it by angle ROT. The drawing is done in the currently
defined plot area. DATA coordinate system is assumed unless specified
otherwise by one of the keywords /DEVICE or /NORMAL.
CATEGORY:
General Graphics.
CALLING SEQUENCE:
ELLIPSE, CENTER = CENT, RADII = RD, [, optional keywords]
INPUTS:
None
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
CENTER
2 dimensional vector, ellipse center location, format [x,y], mandatory.
RADII
2 dimensional vector, contains the x and y radii (in order), mandatory.
ARC
Optional. Allows to draw an elliptical arc. Accepts a vector of
length 2 containing the start and end angles for the arc. If only one
value is provided, the arc is drown from angle 0 to this value if it is
positive, or from this value to 0 if it is negative. The angles are
assumed to be in radians unless DEGREES is set.
/DEGREES
Switch. Specifies that the rotation (and arc) angles are given in
degrees.
ROTATE
Optional. Angle of rotation in the mathematical positive direction.
Assumed in radians, unless DEGREES is set.
ROTATION_CENTER
Optional. Accepts a two element vector specifying the center of
rotation. Ignored if ROTATE is not given. Defaults to center of shape.
/FILL
Switch. Causes the ellipse to be filled with a solid pattern.
/DEVICE
Standard IDL plotting interpretation.
/NORMAL
Ditto.
_EXTRA
A formal keyword used to pass all plotting keywords. Not to be used
directly. See comment in RESTRICTIONS.
OUTPUTS:
None.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
If the DATA coordinate system is used and the plot area is defined with
nonlinear (logarithmic) axes, the shape won't look like an ellipse.
ELLIPSE calls either PLOTS or (when /FILL is used) POLYFILL. Since
some graphics keywords work only with PLOTS, or only with POLYFILL,
some care must be exercised.
PROCEDURE:
Uses calls to DEFAULT, ONE_OF, SHAPE_COCON and SHAPE_TRANS from MIDL.
Generates a (2,N) array containing a sufficient number of ellipse
points to yield a smooth curve. N is variable, depending both on the
ellipse size and on the pixel size of the current output device.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
Modified 15-DEC-1991 by Mati Meron. Added size and device dependence
of the number of plot points.
Modified 15-OCT-1992 by Mati Meron. Added rotation.
Modified 15-DEC-1993 by Mati Meron. Now ELLIPSE takes advantage of the
keyword inheritance property and accepts all IDL plotting keywords.
Modified 1-MAY-1995 by Mati Meron. Added capability to draw an
elliptical arc.
(See IDL_USER:[MERON]ELLIPSE.PRO;1)
NAME:
ERRBARS
PURPOSE:
Overplots error bars over an existing plot. More general than the
library routines ERRPLOT and PLOTERR, since it allows to independently
vary both X and Y errors, and allows for nonsymmetric error bars.
CATEGORY:
Plotting.
CALLING SEQUENCE:
ERRBARS, [X,] Y [, XERR = XER, YERR = YER]
INPUTS:
X, Y
Vectors containing the data points' coordinates. If only one is given
it is taken to be Y, same as in the PLOT command.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
XERR
Either a vector or a (2,N) array where N is the number of the data
points. Contains the X-errors. If given as a 2 dimensional array, the
entries XERR(0,i) and XERR(1,i) are taken as the errors of X(i) in the
negative and positive directions, respectively. If given as a vector,
the entry XERR(i) serves as both the negative and positive error of
X(i) and therefore symmetric error bars are drawn. If not provided,
the default is no X-errors.
YERR
Same as above, for the Y-errors.
_EXTRA
A formal keyword used to pass all plotting keywords. Not to be used
directly. See comment in RESTRICTIONS.
OUTPUTS:
None.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
If either XERR or YERR is given as a vector, it is converted to a (2,N)
array.
RESTRICTIONS:
The keywords passed through _EXTRA are transferred to the PLOTS
routine. No keyword verification is performed by ERRBARS.
PROCEDURE:
Straightforward. Uses DEFAULT from MIDL.
MODIFICATION HISTORY:
Created 10-DEC-1991 by Mati Meron.
Modified 15-DEC-1993 by Mati Meron. Now ERRBARS takes advantage of the
keyword inheritance property and accepts most of IDL plotting keywords.
(See IDL_USER:[MERON]ERRBARS.PRO;1)
NAME:
EXTREMA
PURPOSE:
Finding all local minima and maxima in a vector.
CATEGORY:
Mathematical Function (array).
CALLING SEQUENCE:
Result = EXTREMA( X [, keywords])
INPUTS:
X
Numerical vector, at least three elements.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
/MIN_ONLY
Switch. If set, EXTREMA finds only local minima.
/MAX_ONLY
Switch. If set, EXTREMA finds only local maxima.
/CEILING
Switch. Determines how results for extended extrema (few consecutive
elements with the same value) are returned. See explanation in OUTPUTS.
SIGNATURE
Optional output, see below.
NUMBER
Optional output, see below.
OUTPUTS:
Returns the indices of the elements corresponding to local maxima
and/or minima. If no extrema are found returns -1. In case of
extended extrema returns midpoint index. For example, if
X = [3,7,7,7,4,2,2,5] then EXTREMA(X) = [2,5]. Note that for the
second extremum the result was rounded downwards since (5 + 6)/2 = 5 in
integer division. This can be changed using the keyword CEILING which
forces upward rounding, i.e. EXTREMA(X, /CEILING) = [2,6] for X above.
OPTIONAL OUTPUT PARAMETERS:
SIGNATURE
The name of the variable to receive the signature of the extrema, i.e.
+1 for each maximum and -1 for each minimum.
NUMBER
The name of the variable to receive the number of extrema found. Note
that if MIN_ONLY or MAX_ONLY is set, only the minima or maxima,
respectively, are counted.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward. Calls ARREQ and ONE_OF from MIDL.
MODIFICATION HISTORY:
Created 15-FEB-1995 by Mati Meron.
(See IDL_USER:[MERON]EXTREMA.PRO;1)
NAME:
FRESNEL_INT
PURPOSE:
Calculates the Fresnel Integrals, C(x) or S(X).
CATEGORY:
Mathematical, general.
CALLING SEQUENCE:
Result = FRESNEL_INT (X [, keywords])
INPUTS:
X
Numeric, otherwise arbitrary.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
/SINE
Switch. If set, the Fresnel sine integral, S(X), is returned.
/COMPLEMENTARY
Switch. If set, 1/2 - C(X) (or S(X)) is returned.
OUTPUTS:
Returns the Fresnel Cosine integral C(X) or, if /COMPLEMENTARY is set,
the sine integral S(X). If /COMPLEMENTARY is set, the output is
1/2 (the value at infinity) - C(X) (or S(X)).
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
While the function is defined also for complex values of X, large
complex values may cause calculational instabilities. A warning is
issued in this case.
PROCEDURE:
Uses the function M_ERRORF from MIDL, as well as CAST and TYPE, also
from MIDL.
MODIFICATION HISTORY:
Created 20-MAR-1996 by Mati Meron.
(See IDL_USER:[MERON]FRESNEL_INT.PRO;1)
NAME:
HOW_MANY
PURPOSE:
Called with up to 8 keyword parameters, HOW_MANY checks how many and
which of the corresponding variables are defined and (optionally)
within given type limits.
CATEGORY:
Programming.
CALLING SEQUENCE:
Result = HOW_MANY ([FIRST ... ] [LOW =LO] [HIGH = HI] [/NOZERO] $
[WHICH_ONES = BCOD])
INPUTS:
None.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
FIRST |
SECOND |
THIRD |
FORTH | Each of these keywords accept an arbitrary input,
FIFTH | including no input or undefined input.
SIXTH |
SEVENTH |
EIGHTH |
/NOZERO
Switch. If set, specifies that only non zero (or non null string)
values are to be recognized as existing.
LOW
Optional numeric input, specifying the lowest limit of type code that
is recognized. For example, if LOW is set to 3, variables of type BYTE
and INTEGER will not be recognized as defined. Default value is 1,
i.e. everything is recognized.
HIGH
Same as LOW for the upper limit. Default value is 9, i.e. everything
is recognized.
WHICH_ONES
Optional output, see below.
OUTPUTS:
Returns the number of defined keyword variables, regardless of their
types and values.
OPTIONAL OUTPUT PARAMETERS:
WHICH_ONES
The name of a variable to receive a a binary representation of the
defined variables, as a long integer. For example, if the variables
corresponding to FIRST, FIFTH and SIXTH are defined, the result is
2^0 + 2^4 + 2^5 = 49.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
Currently HOW_MANY is restricted to a maximum of 8 variables. If
needed, the number can be increased.
PROCEDURE:
Straightforward. Calls DEFAULT and TYPE from MIDL.
MODIFICATION HISTORY:
Created 15-AUG-1994 by Mati Meron, as a more general version of ONE_OF.
(See IDL_USER:[MERON]HOW_MANY.PRO;1)
NAME:
INTEG
PURPOSE:
Integrates a function provided as an array of points.
CATEGORY:
Mathematical Function (array)
CALLING SEQUENCE:
Result = INTEG([X,] Y [, keywords])
INPUTS:
Y
A vector containing the Y coordinates of the data.
OPTIONAL INPUT PARAMETERS:
X
A vector containing the X coordinates of the data. If not provided,
it is assumed that the X coordinates are equally spaced, with a default
default spacing of 1. (unless changed by the DELTA keyword).
KEYWORD PARAMETERS:
DELTA
Sets the spacing of the X coordinates of the data. If the X coord.
are explicitly provided (see X input above) DELTA is ignored.
/VALUE_ONLY
Switch. Normally INTEG returns the integral function of Y, as a vector
(see OUTPUTS below). If VALUE_ONLY is set, only the full value of the
integral is returned as scalar. This makes the execution faster.
OUTPUTS:
Normally returns the integral function of Y, i.e. a vector whose i-th
entry is the integral of Y from X(0) to X(i) (and therefore the last
entry is the full integral of Y. If the optional keyword VALUE_ONLY is
set, only the full integral is returned, as a scalar.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
The Y vector (and the X vector, if provided) must be of length >= 3.
PROCEDURE:
Simpson integration, where the mid-interval points are obtained from
cubic interpolation using Neville's algorithm.
Uses DEFAULT and TYPE from MIDL.
MODIFICATION HISTORY:
Created 20-FEB-1992 by Mati Meron.
(See IDL_USER:[MERON]INTEG.PRO;1)
NAME:
ISNUM
PURPOSE:
Checks whether the input is a number.
CATEGORY:
Programming.
CALLING SEQUENCE:
Result = ISNUM(X)
INPUTS:
X
Arbitrary, doesn't even have to exist.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
/DOUBLE
Switch. If set the result is 1 only if X is DOUBLE or DCOMPLEX.
/COMPLEX
Switch. If set the result is 1 only if X is COMPLEX or DCOMPLEX.
TYPE
Optional output. See below
OUTPUTS:
Returns 1 if X is number, 0 otherwise. Output type is byte.
OPTIONAL OUTPUT PARAMETERS:
TYPE
The name of the variable to receive the numeric code of the type of X.
Included for convenience to save an additional call to TYPE.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward. Using TYPE from MIDL.
MODIFICATION HISTORY:
Created 15-JUN-1995 by Mati Meron.
Modified 5-MAY-1996 by Mati Meron. Added keywords DOUBLE, COMPLEX and
TYPE.
(See IDL_USER:[MERON]ISNUM.PRO;1)
NAME:
LABELS
PURPOSE:
Multiple XYOUTS interface.
CATEGORY:
General Graphics.
CALLING SEQUENCE:
LABELS, X, Y, LABS [ ,ALIGN = ALN] [, optional keywords]
INPUTS:
X
The X coordinates of the labels. Can be given either as a scalar (in
which case all the labels will have the same x coordinate) or as a
vector of the same length as the LABS vector.
Y
Same as above for the Y coordinates.
LABS
A character vector containing the labels to be drawn.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
ALIGN
The allignment parameter for LABS (see ALIGN graphics keyword in the
IDL manual. Can be given as a vector, thus providing individual
allignment parameter to each string in LABS.
_EXTRA
A formal keyword used to pass all plotting keywords. Not to be used
directly. See comment in RESTRICTIONS.
OUTPUTS:
None.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
If any of X, Y or ALIGN is given as a scalar variable, it is converted
to a vector of the same length as LABS.
RESTRICTIONS:
None.
PROCEDURE:
Straigtforward. Calls DEFAULT from MIDL.
MODIFICATION HISTORY:
Created 10-DEC-1991 by Mati Meron.
Modified 15-DEC.1993. Incorporated keyword inheritance, allowing for
using all the XYOUTS keywords.
(See IDL_USER:[MERON]LABELS.PRO;1)
NAME:
LAPLACIAN
PURPOSE:
Calculates the Laplacian of a function represented as an array of
values. Works for 1-7 dimensions.
CATEGORY:
Array Manipulation
CALLING SEQUENCE:
Result = LAPLACIAN( ARR [, DELTA])
INPUTS:
ARR
Array, numeric, number of dimensions can be 1 through 7
OPTIONAL INPUT PARAMETERS:
DELTA
Size of step used to calculate the numeric derivatives. The approx.
second partial derivative in the i-th direction is calculated as
(ARR(...,I + DELTA,...) + ARR(...,I - DELTA,...) - 2*ARR(...,I,...)) $
/DELTA^2
The default value of DELTA is 1l. If provided, it is rounded to a long
integer on input.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Returns the absolute value of the gradient as an array of the same size
as ARR. If ARR is not an array, returns 0.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
Due to current limitations of the MAKE_ARRAY system routine, 8
dimensions are not allowed.
PROCEDURE:
Creates an 7-dimensional array, with dummy leading dimensions,
containing the original array. Generates the differences using the
SHIFT system routine and strips the dummy dimensions at the end.
Uses the function DEFAULT from MIDL.
MODIFICATION HISTORY:
Created 15-NOV-1991 by Mati Meron.
(See IDL_USER:[MERON]LAPLACIAN.PRO;1)
NAME:
LEGENDRE_POL
PURPOSE:
Calculates Legendre polynomials Pl and associated polynomials Plm.
CATEGORY:
Mathematical function.
CALLING SEQUENCE:
Result = LEGENDRE_POL( X, L [, M])
INPUTS:
X
Numeric, absolute values must be <= 1, otherwise arbitrary.
L
Nonnegative scalar, rounded to integer on input. Defaults to 0
OPTIONAL INPUT PARAMETERS:
M
Nonnegative scalar, rounded to integer on input. Defaults to 0. Must
be <= L.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Returns the values of the Legendre polynomial P(l,x) or (when M is not
zero) of the associated Legendre polynomial P(l,m,x)
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None other then the restrictions on X, L and M as mentioned above.
PROCEDURE:
Using the recurrence relation from Numerical Recipies, Sec. 6.6.
Calling CAST, DEFAULT and TYPE from MIDL.
MODIFICATION HISTORY:
Created 20-DEC-1994 by Mati Meron.
(See IDL_USER:[MERON]LEGENDRE_POL.PRO;1)
NAME:
LINFIT
PURPOSE:
Linear fitting with an arbitrary number of parameters.
CATEGORY:
Mathematical Function.
CALLING SEQUENCE:
Result = LINFIT( X, Y [,W] [, keywords])
INPUTS:
X
Numeric vector. X coordinates of the data.
Y
Numeric vector. Y coordinates of the data. Same length as X.
OPTIONAL INPUT PARAMETERS:
W
Numeric vector. Weight parameters. Same length as X. Default is
constant weight (1).
KEYWORD PARAMETERS:
ORDER
Specifies the order of the fit, i.e. one less than the number of free
parameters (or base functions). If not given, the order will be read
from the number of entries in the BASE variable (see below). If both
ORDER and BASE are specified, the higher one will determine the order.
Finally, if neither is specified, ORDER is set to 1 (meaning linear fit)
RESIDUAL
Optional output, see below.
BASE
Character array containing names of base functions. Any blank entry
will be replaced by a power of X. For example, if the third entry
(i = 2) is blank (or null string) the third base function will be X^2.
PARAMS
Array containing optional parameters (one per function) to be used in
the function calls.
PARMASK
Parameter mask, specifies which of the parameters are to be used. A
nonzero entry means USE, zero means DON'T USE. Default is USE for all
existing parameters.
OUTPUTS:
Returns a vector containing the fit coefficients.
OPTIONAL OUTPUT PARAMETERS:
RESIDUAL
The name of the variable to receive the residual Chi-Square value,
normalized to the number of degrees of freedom.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Standard linear optimization, using a Singular Value Decomposition
procedure to solve the linear system. Uses DEFAULT, TYPE and
SOLVE_LINSYS from MIDL.
MODIFICATION HISTORY:
Created 1-JUN-93 by Mati Meron.
(See IDL_USER:[MERON]LINFIT.PRO;1)
NAME:
MAKE_GRID
PURPOSE:
Generates a 1-6 dimensional grid of points within a specified range.
CATEGORY:
Array manipulation.
CALLING SEQUENCE:
Result = MAKE_GRID( SPAN, [ NPOINTS] [keywords])
INPUTS:
SPAN
A (2,N) numeric array, where N <= 6 is the number of grid dimensions.
The pair of entries in SPAN(*,i) represents the coordinate minimum and
maximum in the i-th dimension of the grid.
OPTIONAL INPUT PARAMETERS:
NPOINTS
A numeric vector containing the number of points along each dimension.
If not provided, the same number of points will be assigned to each
dimension. This default number depends on the number of dimensions, as
follows:
dimensions | points per dimension
1 2^20
2 2^10
3 2^6
4 2^4
5 2^3
6 2^3
If NPOINTS has less entries then the number of dimensions, the missing
entries will be assigned the value of the last existing one. If some
of the entries (but not the first) are 0 or 1, they'll be replaced by
the value of the preceding non-zero entry.
The meaning of NPOINTS changes if the optional keyword STEPSIZE is set.
In this case the entries in NPOINTS represent the step sizes along each
dimension (if not provided, stepsizes are set so as to yield the
default number of points per dimension as mentioned above). If some of
the step sizes are bigger then the corresponding spans, they will be
adjusted to the span size. Again, If some of the entries (but not the
first) are 0 or missing, they'll be replaced by the value of the
preceding non-zero entry.
KEYWORD PARAMETERS:
/STEPSIZE
Switch. Specifies that the entries in NPOINTS are to be treated as
step sizes.
FUNARR
optional output, see below.
OUTPUTS:
Returns an array with the dimensions (NDIM,NPOINTS(0),...) where NDIM
is the number of dimensions of the grid, such that Result(*,i0,i1,...)
is a vector containing the cartesian coordinates of the point at
location (i0,i1,...) within the grid. The output type is FLOAT (or
DOUBLE if SPAN is of type DOUBLE).
OPTIONAL OUTPUT PARAMETERS:
FUNARR
The name of the variable to receive a blank array of dimensions
(NPOINTS(0),NPOINTS(1),...). This array can be used to receive the
values of a function evaluated over the grid. The output type is FLOAT
(or DOUBLE if SPAN is of type DOUBLE).
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
The number of dimensions must not exceed 6.
PROCEDURE:
Straightforward. Uses CAST, DEFAULT and TYPE from MIDL.
MODIFICATION HISTORY:
Created 15-JAN-1992 by Mati Meron.
Modified 15-AUG-1994 by Mati Meron. Added the STEPSIZE option. Also,
from now on, if SPAN is of type DOUBLE, the outputs are of type DOUBLE.
(See IDL_USER:[MERON]MAKE_GRID.PRO;1)
NAME:
M_ABS
PURPOSE:
Calculates absolute values. A temporary fix needed since the IDL ABS
function fails with very large or very small complex numbers.
CATEGORY:
Mathematical, general.
CALLING SEQUENCE:
Result = M_ABS (X)
INPUTS:
X
Numerical, otherwise arbitrary.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Returns the absolute value of the input.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward. Calling ISNUM from MIDL.
MODIFICATION HISTORY:
Created 15_MAR_1996 by Mati Meron.
(See IDL_USER:[MERON]M_ABS.PRO;1)
NAME:
M_ERRORF
PURPOSE:
Calculates the error function. Replacement for the IDL ERRORF function
which accepts only real input.
CATEGORY:
Mathematical, general.
CALLING SEQUENCE:
Result = M_ERRORF (X [, /COMPLEMENTARY)]
INPUTS:
X
Numeric, otherwise arbitrary.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
/COMPLEMENTARY
Switch. If set, 1 - ERRORF(X) is returned.
OUTPUTS:
Returns the error function of X or, if /COMPLEMENTARY is set,
1 - error_function.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
For very large (in absolute value) complex values of x, with
pi/4 < |abs(phase(x))| < 3*pi/4
the results may be meaningless. A warning will be issued in this case.
PROCEDURE:
Uses the function M_IGAMMA.
MODIFICATION HISTORY:
Created 20-MAR-1996 by Mati Meron.
(See IDL_USER:[MERON]M_ERRORF.PRO;1)
NAME:
M_GAMMA
PURPOSE:
Calculates the gamma function. Replacement for the IDL GAMMA function
which accepts only real input.
CATEGORY:
Mathematical, general.
CALLING SEQUENCE:
Result = GAMMA (X)
INPUTS:
X
Numeric, otherwise arbitrary.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Returns the gamma function of X. Output type is same as input (but no
lower than FLOAT), form is same as input.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
The real part of X should be greater than 0.
PROCEDURE:
Calls M_LNGAMMA.
MODIFICATION HISTORY:
Created 30-MAR-1996 by Mati Meron.
(See IDL_USER:[MERON]M_GAMMA.PRO;1)
NAME:
M_IGAMMA
PURPOSE:
Calculates the incomplete gamma function. Replacement for the IDL
IGAMMA function which accepts only real input.
CATEGORY:
Mathematical, general.
CALLING SEQUENCE:
Result = M_IGAMMA (X, A [,EPS ] [,/COMPLEMENTARY ])
INPUTS:
X
Numeric, otherwise arbitrary.
A
Numeric scalar, non-complex, positive.
OPTIONAL INPUT PARAMETERS:
EPS
Specifies precision level. Default is machine precision.
KEYWORD PARAMETERS:
/COMPLEMENTARY
Switch. If set, 1 - IGAMMA(X) is returned.
OUTPUTS:
Returns the incomplete gamma function of x, unless /COMPLEMENTARY is
set in which case returns 1 - the incomplete gamma function.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
For reasons having to do with machine limits on sizes of numbers, the
parameter A cannot be too big. The limit is roughly given by
A < P + (Ln(2*P))/2
Where P is the (natural) logarithm of the largest number the machine
can process. On the VAX this limit is around 90.
Also, for values of X with large negative real part the calculation
cannot converge and the result is replaced with a very large number
(machine limit). A warning is displayed in this case.
PROCEDURE:
Uses series expansion for small ABS(X) and continued fraction
expansion for larger values. Calls CAST, CONFRAC, DEFAULT, M_ABS,
M_LNGAMMA, TOLER and TYPE, from MIDL.
MODIFICATION HISTORY:
Created 15-MAR-1996 by Mati Meron.
(See IDL_USER:[MERON]M_IGAMMA.PRO;1)
NAME:
M_IMAGINARY
PURPOSE:
Returns imaginary values.
CATEGORY:
Mathematical, general.
CALLING SEQUENCE:
Result = M_IMAGINARY (X)
INPUTS:
X
Numerical, otherwise arbitrary.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Returns the imaginary part of the input, i.e. 0 if the input is real
the imaginary part in FLOAT format for COMPLEX and the imaginary part
in DOUBLE format for DCOMPLEX.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward. Calling ISNUM from MIDL.
MODIFICATION HISTORY:
Created 5_MAY_1996 by Mati Meron.
(See IDL_USER:[MERON]M_IMAGINARY.PRO;1)
NAME:
M_LINFIT
PURPOSE:
Linear fitting with an arbitrary number of parameters.
CATEGORY:
Mathematical Function.
CALLING SEQUENCE:
Result = M_LINFIT( X, Y [,W] [, keywords])
INPUTS:
X
Numeric vector. X coordinates of the data.
Y
Numeric vector. Y coordinates of the data. Same length as X.
OPTIONAL INPUT PARAMETERS:
W
Numeric vector. Weight parameters. Same length as X. Default is
constant weight (1).
KEYWORD PARAMETERS:
ORDER
Specifies the order of the fit, i.e. one less than the number of free
parameters (or base functions). If not given, the order will be read
from the number of entries in the BASE variable (see below). If both
ORDER and BASE are specified, the higher one will determine the order.
Finally, if neither is specified, ORDER is set to 1 (meaning linear fit)
RESIDUAL
Optional output, see below.
BASE
Character array containing names of base functions. Any blank entry
will be replaced by a power of X. For example, if the third entry
(i = 2) is blank (or null string) the third base function will be X^2.
PARAMS
Array containing optional parameters (one per function) to be used in
the function calls.
PARMASK
Parameter mask, specifies which of the parameters are to be used. A
nonzero entry means USE, zero means DON'T USE. Default is USE for all
existing parameters.
OUTPUTS:
Returns a vector containing the fit coefficients.
OPTIONAL OUTPUT PARAMETERS:
RESIDUAL
The name of the variable to receive the residual Chi-Square value,
normalized to the number of degrees of freedom.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Standard linear optimization, using a Singular Value Decomposition
procedure to solve the linear system. Uses DEFAULT, TYPE and
SOLVE_LINSYS from MIDL.
MODIFICATION HISTORY:
Created 1-JUN-93 by Mati Meron.
Renamed fro LINFIT to M_LINFIT to avoid clashes with an IDL library
routine bearing the same name.
(See IDL_USER:[MERON]M_LINFIT.PRO;1)
NAME:
M_LNGAMMA
PURPOSE:
Calculates the natural log of the gamma function. Replacement for the
IDL LNGAMMA function which accepts only real input.
CATEGORY:
Mathematical, general.
CALLING SEQUENCE:
Result = M_LNGAMMA (X, A [,EPS ] [,/COMPLEMENTARY ])
INPUTS:
X
Numeric, otherwise arbitrary.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Returns the natural logarithm of the gamma function of X. Output type
and form are identical to those of the input (but output type is never
lower than FLOAT).
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
The real part of X should be positive.
PROCEDURE:
Uses a continued fraction expansion. Calls CAST, CONFRAC, DEFAULT,
TYPE and TOLER, from MIDL.
MODIFICATION HISTORY:
Created 30-MAR-1996 by Mati Meron.
(See IDL_USER:[MERON]M_LNGAMMA.PRO;1)
NAME:
M_REAL
PURPOSE:
Returns real values.
CATEGORY:
Mathematical, general.
CALLING SEQUENCE:
Result = M_REAL (X)
INPUTS:
X
Numerical, otherwise arbitrary.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Returns the real value of the input, i.e. the input itself if its real
the real part in FLOAT format for COMPLEX and the real part in DOUBLE
format for DCOMPLEX.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward. Calling CAST and ISNUM from MIDL.
MODIFICATION HISTORY:
Created 5_MAY_1996 by Mati Meron.
(See IDL_USER:[MERON]M_REAL.PRO;1)
NAME:
NATAN
PURPOSE:
Calculates the function /int{(1 + x^2)^(-n-1)}, or, optionally,
/int{(1 - x^2)^(-n-1)}
CATEGORY:
Mathematical function.
CALLING SEQUENCE:
Result = NATAN( X [, N [, /HYPER]])
INPUTS:
X
Numerical, otherwise arbitrary.
OPTIONAL INPUT PARAMETERS:
N
Integer scalar, defaults to 0.
KEYWORD PARAMETERS:
/HYPER
Switch, turns on the "hyperbolic" option.
OUTPUTS:
Returns /int{(1 + x^2)^(-n-1)} (for N = 0 it amounts to ATAN(X)), or,
if /HYPER is set, /int{(1 - x^2)^(-n-1)} (for N = 0 this is the
hyperbolic ATAN). The result is of the same form as X, of type FLOAT
or higher (if X is of a higher type).
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
N must be >= 0, otherwise it is taken to be 0.
PROCEDURE:
Exact evaluation in powers of 1/(1 + x^2). Uses CAST, DEFAULT and TYPE
from MIDL.
MODIFICATION HISTORY:
Created 30-MARCH-1994 by Mati Meron.
(See IDL_USER:[MERON]NATAN.PRO;1)
NAME:
NEIGHBORS
PURPOSE:
Finding the nearest neighbors of an array element.
CATEGORY:
Array function.
CALLING SEQUENCE:
Result = NEIGHBORS( IND, SIZ [, COUNT])
INPUTS:
IND
Index of an array element. Provided either in contracted (1-dim) or
expanded version. In the second case IND has to be a vector the length
of which equals the number of dimension of the array (given by SIZ(0)).
SIZ
Vector in the form of the standard output of the system function SIZE.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
COUNT
An optional output parameter. See below.
OUTPUTS:
Returns a vector containing the indices of the nearest neighbors of the
element corresponding to IND. If no neighbors exist returns -1.
OPTIONAL OUTPUT PARAMETERS:
COUNT
The name of the variable to receive the number of neighbors.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward. Calls ARRLOC from MIDL.
MODIFICATION HISTORY:
Created 30-MARCH-1994 by Mati Meron.
(See IDL_USER:[MERON]NEIGHBORS.PRO;1)
NAME:
ONE_OF
PURPOSE:
Called with up to 8 variables V_0 through V_7 , ONE_OF checks which
variable is defined (only one is supposed to be).
CATEGORY:
Programming.
CALLING SEQUENCE:
Result = ONE_OF( V_0 [,V_1, ... V_7] [, VALUE = VAL])
INPUTS:
V_0 through V_7
Arbitrary, all are optional.
OPTIONAL INPUT PARAMETERS:
See above.
KEYWORD PARAMETERS:
VALUE
Optional output, see below.
OUTPUTS:
Returns the serial number (range 0 through 7) of the defined variable,
or -1 if none is defined. If more than one variable is defined, ONE_OF
issues an error message and returns to the main level.
OPTIONAL OUTPUT PARAMETERS:
VALUE
The name of the variable to receive the value of the single defined
variable, or a null string if none is defined.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
Currently ONE_OF is restricted to a maximum of 8 variables. If needed,
the number can be increased.
PROCEDURE:
Straightforward.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
Modified 30-JUL-1991 by Mati Meron. The dependence of the original
code on the EXECUTE system routine has been eliminated in order to
assure compatibility with the OUTPUT routine.
Modified 15-NOV-1993 by Mati Meron. Since IDL now allows for recursive
calls to EXECUTE, the original code has been restored.
(See IDL_USER:[MERON]ONE_OF.PRO;1)
NAME:
OUTPUT
PURPOSE:
Generic output interface. Allows sending the results of virtually any
IDL command or file to any predefined hard copy device. In detail,
OUTPUT executes the provided command, writes the output to a file and
sends the file to a printout que.
CATEGORY:
Input/Output
CALLING SEQUENCE:
OUTPUT, COMM [, keywords] [,optional input parameters]
INPUTS:
COMM
Character value representing a valid IDL command. Can be (and usually
is) a procedure or function call.
OPTIONAL INPUT PARAMETERS:
V_0 through V_7
Serve to pass variables which are used in the command COMM. Since COMM
is passed to output as a single string, OUTPUT is not receiving the
values of any variables used by COMM. If such values are needed they
have to be passed separately. This is done using the variables V_0
through V_7 in combination with the keyword SUBST (see below), which
accepts a string made of the names of the variables separated by spaces
or commas.
Example:
Assume a routine named NEWPLOT which is called using the syntax
NEWPLOT, I, X, SCOPE = Y
If at the time of call I, X, and Y have known values, say 3, 12.4
and [12,95] then it is possible to issue the command
OUTPUT, 'NEWPLOT, 3, 12.4, SCOPE = [12,95]'
If, on the other hand one would want to pass NEWPLOT to output
using the variables K, E and RANG for I, X, Y, the command can be
OUTPUT, 'NEWPLOT, I, X, SCOPE = Y', $
SUBST = 'I,X Y', K, E, RANG
The order in which the variable names appear in SUBST is arbitrary
but it has to be in a one-to-one correspondence with the order in
which the actual arguments are given. Therefore, the following is
equally valid
OUTPUT, 'NEWPLOT, I, X, SCOPE = Y', $
SUBST = 'Y, I, X', RANG, K, E
KEYWORD PARAMETERS:
QUE
Accepts a string and sets the printout queue. Currently accepted
values and the queues they represent are as follows:
'LN03' - The LN03 printer at the X26.
'SIXEL' - The SIXEL printer in 901.
'EPS' - Writes an encapsulated PostScript file, no printout.
'FILE' - Writes a PostScript file, no printout.
'PHASER' - Phaser color printer. Valid only in BNL.
'TRANSP' - Phaser Printer with LEGAL sized paper. Use this
one for transparencies.
'CARS1' - The PostScript printer at CARS1.
'SYS$PRINT' - Generic PostScript. This is the initial Default.
This is by no means the final list, as new queues keep being added from
time to time. For all queues on this list only the first three
characters of the name are needed as input.
If a queue name not on the list is entered, OUTPUT will use this name
with the parameters of the default queue, SYS$PRINT. If no queue name
is entered, output will use SYS$PRINT when first called, and the name
of the last queue used subsequently.
FIL
Accepts a string representing a valid VMS file name.
Extension isn't necessery. Default is 'IDL'.
/KEEP
Switch. Specifies file disposition. If set, the file is kept after
printout. The default is 'DELETE', unless the queue is 'EPS' or 'FILE'.
/BEEP
Switch. If set, a beep will sound when OUTPUT finishes processing the
file, and another beep sounds when the printout is complete. Useful
for long files. Also, if set, the VAX verifies that the printer is on.
OPTION
Accepts a string representing a valid IDL command. If given, this
command will be executed BEFORE COMM. If the command in OPTION
includes variables, their values can be passed using the same mechanism
as the one used for COMM (see above).
MAIL
Name of a recipient to whom the resulting file is mailed. Optional.
SUBST
Accepts a string containing the names of the variables which are to
receive the values V_0 through V_7 (or part of them) for substitution
purposes. Commas and/or spaces are valid delimiters.
OUTPUTS:
None, other then the file that's created and whatever outputs are
generated by COMM.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
M_OUT_PREFS. Contains the name of the last queue used.
SIDE EFFECTS:
OUTPUT tries to avoid any side effects, as far as possible.
Specifically, the values of all the system variables are reset at exit
from OUTPUT to the values they had before output was called. Still,
since COMM can be any possible command, side effects cannot be totally
avoided.
A currently known side effect has to do with PostScript printers. If
either COMM or OPTION change the postscipt settings, the new settings
will remain in effect after OUTPUT exits.
RESTRICTIONS:
1) With IDL before version 3.1, the commands in COMM and OPTION (if used)
are not allowed to use calls to the EXECUTE system routine, either
directly or indirectly. This is so since OUTPUT itself relies on
EXECUTE and since EXECUTE (in older versions of IDL) could not be
called recursively.
2) Currently the number of substitution variables is limited to 8. If
it'll turn out that this number isn't sufficient it can be easily
increased. Let me know.
3) The commands in COMM (and OPTION) shouldn't change the output device
(i.e. NO using SET_PLOT, DEVICE/CLOSE, etc., all this is taken care of
by OUTPUT). If they do, no error will result but the outcome will be
unpredictable.
4) In order to make the best use of OUTPUT it is recommended that the
commands in COMM will be totally device independent (i.e. no using
explicit device coordinates etc.). This allows to send the output of
the same procedure to the various printers and get consistent results.
If one finds it necessery to use some device specific commands (like
setting a color table for the Phaser printer), they should be put in
OPTION (that's really the whole purpose of having OPTION)
PROCEDURE:
OUTPUT contains a list of the appropriate device opening and closing
commands for the ques it recognizes. When called, it does the
following.
1) Checks QUE and if recognizable generates the appropriate OPEN,
CLOSE and PRINTOUT commands. If QUE isn't recognized, OUTPUT assumes
SYS$PRINT.
2) Performs variable substitution if so specified (by a non-blank
value of SUBST)
3) Opens device.
4) Executes OPTION, if given.
5) Executes COMM
6) Closes device.
7) Optionally mails the file to the specified recipient.
8) Spawns PRINT command to the appropriate que (unless que = 'EPS' or
'FILE' is specified).
9) Deletes the file unless specified otherwise.
OUTPUT uses various routines from MIDL, namely:
TYPE, DEFAULT, STREQ, STRMATCH, STRPARSE and PLVAR_KEEP.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
Modified 15-SEP-1991 by Mati Meron. Added Phaser and Sixel support.
Modified 15-NOV-1991 by Mati Meron. Added the 'TRANSP' que and the
/BEEP keyword.
Modified 28-DEC-1991 by Mati Meron. Now any changes made to the color
table of PostScript devices by either COMM or OPTION are undone before
OUTPUT exits.
Modified 15-MAY-1993 by Mati Meron. Added 'EPS', 'FILE' and 'CARS1'
queues.
Modified 20-NOV-1993 by Mati Meron. Introduced SYS$PRINT as default
queue and maintenance of last que as current default.
(See IDL_USER:[MERON]OUTPUT.PRO;1)
NAME:
PLOTOT
PURPOSE:
Plots multiple data sets on a single plot
CATEGORY:
Plotting
CALLING SEQUENCE:
PLOTOT, [X,] Y [, optional keywords]
INPUTS:
Y
A numeric vector or 2 dimensional array containing the Y coordinates of
the data. If Y is a vector PLOTOT operates same as PLOT. If it is
a 2-dim.array, each row is ploted separately. It is assumed that the
number of points per plot is larger than the number of plots so that if
Y is an (M*N) array with N > M, it will be transposed prior to plotting.
OPTIONAL INPUT PARAMETERS:
X
A numeric vector containing the X coordinates of the data. If absent
it is replaced by the vector [0, 1, 2 ...].
KEYWORD PARAMETERS:
XTYPE
Standard IDL plotting interpretation.
YTYPE
Ditto.
/YNOZERO
Ditto.
PSYM
Ditto. If given as a vector consecutive elements are applied to
consecutive plots.
LINESTYLE
Ditto. If given as a vector consecutive elements are applied to
consecutive plots.
COLOR
Ditto. If given as a vector consecutive elements are applied to
consecutive plots.
_EXTRA
A formal keyword used to pass all plotting keywords. Not to be used
directly.
OUTPUTS:
None.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward. Uses calls to DEFAULT, SIGN and WHERINSTRUCT in MIDL.
MODIFICATION HISTORY:
Created 30-JUL-1991 by Mati Meron.
Modified 15-JAN-1994 by Mati Meron. Now PLOTOT takes advantage of the
keyword inheritance property and accepts all IDL plotting keywords.
(See IDL_USER:[MERON]PLOTOT.PRO;1)
NAME:
PLOT_VER2
PURPOSE:
Draws 2 plots, vertically spaced, with a possibility of multiple curves
on each plot.
CATEGORY:
Plotting
CALLING SEQUENCE:
PLOT_VER2, [X,] Y0, Y1 [, optional keywords]
INPUTS:
Y0
A numeric vector or 2 dimensional array containing the Y coordinates of
the data for the top plot. If Y is a 2-dim.array, each row is ploted
separately. It is assumed that the number of points per plot is larger
than the number of plots so that if Y is an (M*N) array with N > M, it
will be transposed prior to plotting.
Y1
Same as Y0 for the bottom plot.
OPTIONAL INPUT PARAMETERS:
X
A numeric vector containing the X coordinates of the data. If absent
it is replaced by the vector [0, 1, 2 ...].
KEYWORD PARAMETERS:
RATIO
Size ratio between top and bottom plot. Default is 1.
GAP
Width of the gap between the plots in character units. Default is 0.1
XMARGIN
Standard IDL plotting interpretation
YMARGIN
Ditto.
XTYPE
Ditto.
YTYPE
Ditto. If given as 2-element vector, elements 0 and 1 apply to top and
bottom plots, respectively.
YNOZERO
Ditto. If given as 2-element vector, elements 0 and 1 apply to top and
bottom plots, respectively.
TITLE
Ditto.
XTITLE
Ditto.
YTITLE
Ditto. If given as 2-element vector, elements 0 and 1 apply to top and
bottom plots, respectively.
PSYM
Ditto. If given as a vector consecutive elements are applied to
consecutive curves on each plot.
LINESTYLE
Ditto. If given as a vector consecutive elements are applied to
consecutive curves on each plot.
COLOR
Ditto. If given as a vector consecutive elements are applied to
consecutive curves on each plot.
_EXTRA
A formal keyword used to pass all plotting keywords. Not to be used
directly.
OUTPUTS:
None.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward. Uses calls to DEFAULT, PLVAR_KEEP, and PLOTOT from
MIDL.
MODIFICATION HISTORY:
Created 30-JUL-1991 by Mati Meron.
Modified 15-JAN-1994 by Mati Meron. Now PLOT_VER2 takes advantage of
the keyword inheritance property and accepts all IDL plotting keywords.
(See IDL_USER:[MERON]PLOT_VER2.PRO;1)
NAME:
PLVAR_KEEP
PURPOSE:
Saves or restores the values of system variables.
CATEGORY:
Input/output
CALLING SEQUENCE:
PLVAR_KEEP, ACTION = ACT [, /RESET]
INPUTS:
None.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
ACTION
Specifies the action to take. Two possible values, 'SAVE' and
'RESTORE' (only first three characters count).
/RESET
Switch. Protection bypass. Normally multiple calls to PLVAR_KEEP are
counted but no action is taken after the first. For example, if 3
consecutive calls with ACTION = 'SAVE' were issued then the system
variables are saved on the first call and nothing happens on the next
two. Then, when calls with ACTION = 'RESTORE' are issued, only the
third call will have an effect. This mechanism allows using 'SAVE' and
'RESTORE' calls as pairs of braces around program sections. For the
(rare) cases when one wants to save or restore regardless of previously
issued calls, setting RESET disables the protection mechanism.
OUTPUTS:
None.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
M_PLVARS
SIDE EFFECTS:
None when used properly. If the numbers of SAVEs and RESTOREs are not
equal, either due to an omission or to an error in a called routine,
the settings won't be restored to their initial state. In this case
the cure is to execute
PLVAR_KEEP, ACTION = 'RESTORE', /RESET
RESTRICTIONS:
None.
PROCEDURE:
Uses a common block (M_PLVARS) to save and restore the values of:
!P, !X, !Y, !Z, !D.NAME. Also uses the routines DEFAULT, TYPE and
STRMATCH from MIDL.
MODIFICATION HISTORY:
Created by 15-JUL-1991 by Mati Meron.
(See IDL_USER:[MERON]PLVAR_KEEP.PRO;1)
NAME:
POLEVAL
PURPOSE:
Evaluates a polynomial function according to the formula:
F = c(0) + c(1)*X + ... + c(n)*X^N
Similar to the library routine POLY. The difference is that when the
keyword QUOTIENT is used, the routine returns, in QCOEF, the values of
the coefficients of the quotient polynomial. In other words, given the
coefficients of a polynomial P, and a value Xc, the function returns
the value P(Xc), and in QCOEF are returned the coefficients of the
polynomial Q(X) = P(X)/(X - Xc). Note that unless P(Xc) is 0, the
division has a remainder.
CATEGORY:
Mathemetical function (general).
CALLING SEQUENCE:
Result = POLEVAL( X, COEF [, QUOTIENT = QCOEF])
INPUTS:
X
Numeric, otherwise arbitrary
COEF
Numeric vector.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
QUOTIENT
An optional output parameter. See below.
OUTPUTS:
Returns the value of the polynomial at X. The result has the same
structure and number of elements as X and the same type as the higher
of X and COEF.
OPTIONAL OUTPUT PARAMETERS:
QUOTIENT
The name of the variable to receive the quotient polynomial. The
quotient is an array with one more dimension than X. For example, if
X is given as an array with dimensions (10,8,64) and the order of the
polynomial is 4 then the dimensions of the quotient will be (10,8,64,4).
QCOEF(4,5,6,*) will then contain the coefs. of P(X)/(X - X(4,5,6)), etc.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Standard Horner evaluation. Uses the function DEFAULT from MIDL.
MODIFICATION HISTORY:
Created 15-NOV-1991 by Mati Meron.
(See IDL_USER:[MERON]POLEVAL.PRO;1)
NAME:
PRINUMS
PURPOSE:
Calculates a table of prime numbers in the range NLO - NHI.
CATEGORY:
Mathematical function (general).
CALLING SEQUENCE:
List = PRINUMS( [NLO,] NHI)
INPUTS:
NHI
Upper limit of the range of the primes table. Converted to long
integer on input.
OPTIONAL INPUT PARAMETERS:
NLO
Lower limit of the prime table range. Converted to long integer on
input.If not provided, i.e. if only one input parameter is provided,
NLO defaults to 1.
KEYWORD PARAMETERS:
/BYPASS
Switch. Used only on internal calls.
OUTPUTS:
Returns the list of primes between NLO and NHI (inclusive), as long
integer. If no primes are found, returns 0.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
Inputs must be positive. If both NLO and NHI are given, NHI >= NLO.
PROCEDURE:
Uses the Sieve of Erasthotenes algorithm. Generates the primes table
calling itself recursively.
MODIFICATION HISTORY:
Created 15-NOV-1991 by Mati Meron.
Modified 15-DEC-1993 by Mati Meron. Combined previous PRIMES and
PR_SIEVE in a single routine.
Modified 20-JUN-1995 by Mati Meron. Renamed PRINUMS to avoid conflict
with an IDL routine bearing the same name.
(See IDL_USER:[MERON]PRINUMS.PRO;1)
NAME:
RANDISC
PURPOSE:
Generates a set of discretely distributed random numbers.
CATEGORY:
Mathematical, general.
CALLING SEQUENCE:
Result = RANDISC (SEED, [,parameters] [,keywords])
INPUTS:
SEED
A named variable containing the seed value for random number generation.
Does not need to be defined prior to call. For details see IDL
routines RANDOMN and RANDOMU.
OPTIONAL INPUT PARAMETERS:
D_0 through D_7
Dimensions of the result. All default to 1. Trailing dimensions of 1
are removed.
KEYWORD PARAMETERS:
AMPLITUDE
Numerical value, rounded to long integer on input. Specifies the
output range. Output values are randomly spread among AMP + 1 possible
values ranging from -AMP to AMP (unless the keyword NORMALIZE is used),
with a spacing of 2. Default value of AMP is 1.
/UNIFORM
Switch. Specifies uniform distribution. This is the default.
/BINOMIAL
Switch. Specifies binomial distribution. For large values of amp the
result approaches a Gaussian with sigma = sqrt(AMP)
/NORMALIZE
Switch. If set, the result is normalized to lie in the [-1,1] range,
with a spacing of -2/AMP
OUTPUTS:
Returns number randomly distributed among the values
-AMP, -AMP + 2 ... AMP or, if the keyword NORMALIZE is set, among
-1, -1 + 2/AMP ... 1. The distribution may be uniform (the default) or
binomial (quasi gaussian). The result can have any number (up to 8) of
dimensions which are specified by the optional variables D_0, ... D_7.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
On return, SEED is replaced with the new value of the randomizer seed.
RESTRICTIONS:
None.
PROCEDURE:
Uses the system routine RANDOMU. Also uses DEFAULT and ONE_OF from
MIDL.
MODIFICATION HISTORY:
Created 20-APR-1995 by Mati Meron.
(See IDL_USER:[MERON]RANDISC.PRO;1)
NAME:
READ_ASCII
PURPOSE:
Reads data from an ASCII file into an array. It is assumed that the
file contains columns of numbers, with the same number of entries in
each row. The numbers may be separated by commas, spaces and/or tabs.
The file may contain a header. The first line in which the first
non-blank character is one of ".+-0123456789" will be considered the
beginning of the data. Text lines imbedded in the data are skipped.
CATEGORY:
Input/Output.
CALLING SEQUENCE:
Result = READ_ASCII( FILNAM [, optional keywords])
INPUTS:
FILNAM
Char. value, the name of the data file. Default extension is '.DAT'.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
BUFFER
Initial number of data rows. Default is 256. In any case the result
Is trimmed to the actual number.
/DOUBLE
If set, the data is input as DOUBLE. Default is FLOAT.
/SHOW
If set, the header (if one exists) will be printed to the screen.
NPOINTS
Optional output, see below.
HEADER
Optional output, see below.
SKIP
Number of lines to skip at the beginning of the file. This keyword can
be used if the header of the file contains lines beginning with
".+-0123456789" which would otherwise be read as data. Default is 0.
OUTPUTS:
Returns the data in a (NC,NR) floating (or double precision if DOUBLE
is set) array, where NC, NR, are the numbers of columns and rows,
respectively. In case of error returns 0.
OPTIONAL OUTPUT PARAMETERS:
NPOINTS
The name of a 2-dim vector to receive the values of NC, NR (see above).
Doesn't need to be defined prior to the call. In case of an error
returns [0,0]
HEADER
The name of a character array to receive the header lines. Doesn't
need to be defined prior to the call. In case of an error, or if no
header exists, returns a zero length string.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward. Uses DEFAULT, STREQ and STRPARSE from MIDL.
MODIFICATION HISTORY:
Created 25-JAN-1992 by Mati Meron.
Modified 25-MAY-1994 by Mati Meron. Added buffering and DOUBLE option.
Modified 14-FEB-1995 by Mark Rivers. Added keyword SKIP.
Modified 24-JUL-1995 by Mati Meron. Removed a UNIX/VMS conflict in the
file OPENR statement.
(See IDL_USER:[MERON]READ_ASCII.PRO;1)
NAME:
RECTAN
PURPOSE:
Draws a rectangle between the limits specified by XLIMS and YLIMS. The
drawing is done in the currently defined plot area. DATA coordinate
system is assumed unless specified otherwise by one of the keywords
/DEVICE or /NORMAL.
CATEGORY:
General Graphics.
CALLING SEQUENCE:
RECTAN, XLIMS = XLS, YLIMS = YLS [, optional keywords]
INPUTS:
None
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
XLIMS
2 dimensional vector, format [xmin,xmax], mandatory.
YLIMS
2 dimensional vector, format [xmin,xmax], mandatory.
ROTATE
Optional. Angle of rotation in the mathematical positive direction.
Assumed in radians, unless DEGREES is set. Rotation center is the
center of the rectangle unless specified otherwise by the keyword
rotation_center (see below).
/DEGREES
Switch. Specifies that the rotation angle is given in degrees.
ROTATION_CENTER
Optional. Accepts a two element vector specifying the center of
rotation. Ignored if ROTATE is not given. Defaults to center of shape.
RADIUS
Value of radius for rounded corners.
/RELATIVE
Switch. Specifies that the radius value is relative to the shorter
side of the rectangle.
/FILL
Switch. Causes the rectangle to be filled with a solid pattern.
/DEVICE
Standard IDL plotting interpretation.
/NORMAL
Ditto.
_EXTRA
A formal keyword used to pass all plotting keywords. Not to be used
directly.
OUTPUTS:
None.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
RECTAN calls either PLOTS or (when /FILL is used) POLYFILL. Since
some graphics keywords work only with PLOTS, or only with POLYFILL,
some care must be exercised.
PROCEDURE:
Uses calls to DEFAULT, ONE_OF, SHAPE_COCON, SHAPE_CLOSE, and
SHAPE_TRANS from MIDL.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
Modified 15-OCT-1991 by Mati Meron. Added keyword COLOR.
Modified 15-OCT-1992 by Mati Meron. Added rotation capability.
Modified 30-OCT-1992 by Mati Meron. Added corner rounding capability.
Modified 15-DEC-1993 by Mati Meron. Now RECTAN takes advantage of the
keyword inheritance property and accepts all IDL graphics keywords.
(See IDL_USER:[MERON]RECTAN.PRO;1)
NAME:
RENERF_FUN
PURPOSE:
Calculates A renormalized complementary error function.
CATEGORY:
Mathematical function.
CALLING SEQUENCE:
Result = RENERF_FUN( X )
INPUTS:
X
Numeric, otherwise arbitrary.
OPTIONAL INPUT PARAMETERS:
None
KEYWORD PARAMETERS:
OUTPUTS:
Returns the values of exp(x^2)*(1 - errorf(abs(x))). For larger values
of ; X, above ~4, this values cannot be calculated directly from the
error function due to cancellation errors.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
While double precision input is acceptable, the results are only
single precision accurate.
PROCEDURE:
Using the approximation from Numerical Recipes, Sec. 6.2. Calling
CAST, POLEVAL and TYPE from MIDL.
MODIFICATION HISTORY:
Created 20-DEC-1994 by Mati Meron.
(See IDL_USER:[MERON]RENERF_FUN.PRO;1)
NAME:
ROMBERG
PURPOSE:
Performs high precision numerical integration.
CATEGORY:
Mathematical function (general).
CALLING SEQUENCE:
Result = ROMBERG( FUN, RANGE [, EPS [, keywords]])
INPUTS:
FUN
Character value representing an existing IDL function. The function
must comply with the IDL standard of being able to accept an array
input and return an array output. The calling sequence for the
function must be either
Result = FUN(x)
or
Result = FUN(x, extra)
where X is the variable and EXTRA may be any single entity (scalar,
array, structure etc.) used to pass additional parameters to the
function.
RANGE
Two element vector, integration range.
OPTIONAL INPUT PARAMETERS:
EPS
Allowed integration error. Default is around 1e-7 for single-precision
integration and 2e-16 for double-precision. EPS is understood to
represent absolute error unless the keyword RELATIVE is set.
KEYWORD PARAMETERS:
/RELATIVE
If set, EPS represent the allowed relative integration error.
PARAMS
An arbitrary value or variable which is passed to the function FUN.
TRY
Normally ROMBERG exits, with STATUS = 2, if the calculation error
starts to grow before the convergence criterion is satisfied. Setting
TRY to an integer > 0 specifies the number of additional attempts at
convergence before exit (useful with ill-conditioned functions). The
Default value is 0.
ERROR
Optional output, see below.
STATUS
Optional output, see below.
OUTPUTS:
Returns the value of the integral. The result is always a scalar. The
numerical type of the result (floating, double-precision or complex) is
determined by the type of values returned by FUN.
OPTIONAL OUTPUT PARAMETERS:
ERROR
The name of the variable to receive the estimated integration error.
If RELATIVE is set the error returned is relative.
STATUS
The name of the variable to receive integration status information.
Possible values are:
0 - Integration didn't converge.
1 - OK.
2 - Integration converged, but with precision worse then specified.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Enhanced Romberg integration, using the extended midpoint rule and
Neville's interpolation algorithm. The process is iterated untill
either the desired accuracy is achieved, the maximal allowed number of
steps is exceeded or further iterations cause the error to grow instead
of diminishing (the last can be postponed using the TRY keyword). The
procedure can handle functions with an integrable singularity at one
(or both) end of the integration interval.
Uses CAST, DEFAULT, TOLER and TYPE from MIDL.
MODIFICATION HISTORY:
Created 15-FEB-92 by Mati Meron.
Modified 20-JAN-1994 by Mati Meron. Added keyword TRY.
(See IDL_USER:[MERON]ROMBERG.PRO;1)
NAME:
ROOT
PURPOSE:
Finds roots of real functions.
CATEGORY:
Mathematical function (general).
CALLING SEQUENCE:
Result = ROOT( FUN, RANGE [, EPS [, keywords]])
INPUTS:
FUN
Character value representing an existing IDL function. The function
must return scalar values. It is not necessery for FUN to be able to
accept an array input and return an array output. The calling sequence
for the function must be either
Result = FUN(x)
or
Result = FUN(x, extra)
where X is the variable and EXTRA may be any single entity (scalar,
array, or structure) used to pass additional parameters to the function.
RANGE
Two element vector, search range.
OPTIONAL INPUT PARAMETERS:
EPS
Allowed error. Default is 1e-6 for single-precision search and 1e-14
for double-precision. EPS is understood to represent absolute error
unless the keyword RELATIVE is set. The allowed error is dynamically
adjusted during calculation.
KEYWORD PARAMETERS:
/RELATIVE
If set, EPS represent the allowed relative (to the size of RANGE) error.
PARAMS
An arbitrary value or variable which is passed to the function FUN.
MULTI
Specifies multiplicity of search (i.e. what is the maximal number of
roots to look for. Default is 1. If MULTI is set to -1 (or any
negative number) the search is unlimited.
ERROR
Optional output, see below.
STATUS
Optional output, see below.
DONE
Optional output, see below.
OUTPUTS:
Returns a vector containing the location(s) of the root(s). The
numerical type of the result (floating, or double) is determined by the
numerical type of RANGE. If no root is found, returns 1e38.
OPTIONAL OUTPUT PARAMETERS:
ERROR
The name of the variable to receive the estimated error of the root
location. Returned as vector, same length as the function output.
STATUS
The name of the variable to receive search status information.
Returned as vector, same length as the function output.
Possible values are:
0 - No root found.
1 - OK.
2 - Search converged, but the result appears to be a singularity.
This may happen with nonsingular functions if the precision
demands are set to high.
DONE
The name of the variable to receive search completion information.
Possible values are:
0 - Indicates that the number of roots prescribed by MULTI has been
found without all of RANGE being searched. This does not
necesserily mean that there are more roots. Disabled for
MULTI = 1, or negative.
1 - Indicates that search has been completed, i.e. all the roots
that could be found have been found.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Uses Golden section search for minima of ABS(FUN(X)). When an
interval where F(X) changes sign is identified, uses weighted interval
halving to pinpoint the root.
Uses CAST, DEFAULT, TOLER and TYPE from MIDL.
MODIFICATION HISTORY:
Created 15-FEB-92 by Mati Meron.
Modified 15-APR-92 by Mati Meron. Added Quadratic Interpolation to
speed up convergence for smooth functions.
Modified 25-JAN-94 by Mati Meron. Added multi-root search capability.
Quadratic Interpolation replaced by a weighted halving to increase
robustness without loosing speed.
(See IDL_USER:[MERON]ROOT.PRO;1)
NAME:
SEQLIM
PURPOSE:
Estimates limits of infinite sequences.
CATEGORY:
Mathematical Function (General).
CALLING SEQUENCE:
Result = SEQLIM( SVL [, RVL ] [, keywords])
INPUTS:
SVL
Numeric vector containing consecutive terms of the sequence. At least
two terms are needed.
OPTIONAL INPUT PARAMETERS:
RVL
Numeric vector, same length as SVL. Contains estimates of the
deviations of the terms of SVL from the limit. Usually RVL is
generated internally, since if good estimates of the deviations from
the limit do exist, SEQLIM is not needed.
KEYWORD PARAMETERS:
/OSCILLATING
Switch. Should be set if the sequence is expected to oscillate around
its limit.
ERROR
Optional output, see below.
STATUS
Ditto.
OUTPUTS:
Returns the limit estimate if one is found, otherwise returns 1E38.
OPTIONAL OUTPUT PARAMETERS:
ERROR
The name of the variable to receive the estimated error of the returned
limit value. If the sequence doesn't seem to converge, returns 1E38.
STATUS
The name of the variable to receive convergence status information.
Returns 1 if the sequence converges, 0 otherwise.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Uses Neville's interpolation algorithm.
MODIFICATION HISTORY:
Created 15-JUN-1992 by Mati Meron.
(See IDL_USER:[MERON]SEQLIM.PRO;1)
NAME:
SERIES_SUM
PURPOSE:
Estimates sums of infinite series.
CATEGORY:
Mathematical Function (General).
CALLING SEQUENCE:
Result = SERIES_SUM( SVL [, RVL ] [, keywords])
INPUTS:
SVL
Numeric vector containing consecutive terms of the series. At least
two terms are needed.
OPTIONAL INPUT PARAMETERS:
RVL
Numeric vector, same length as SVL. Contains estimates of the
deviations of the partial sums of SVL from the limit. Usually RVL is
generated internally, since if good estimates of the deviations from
the limit do exist, SERIES_SUM is not needed.
KEYWORD PARAMETERS:
/OSCILLATING
Switch. Should be set if the series is oscillating, i.e. contains
positive and negative terms.
ERROR
Optional output, see below.
STATUS
Ditto.
OUTPUTS:
Returns the sum estimate if one is found, otherwise returns 1E38.
OPTIONAL OUTPUT PARAMETERS:
ERROR
The name of the variable to receive the estimated error of the returned
sum value. If the series doesn't seem to converge, returns 1E38.
STATUS
The name of the variable to receive convergence status information.
Returns 1 if the series converges, 0 otherwise.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Uses the routine SEQLIM from MIDL. Also uses DEFAULT.
MODIFICATION HISTORY:
Created 15-JUN-1992 by Mati Meron.
(See IDL_USER:[MERON]SERIES_SUM.PRO;1)
NAME:
SHAPE_AREA
PURPOSE:
Calculates the area enclosed by a 2-dimensional shape.
CATEGORY:
Mathematical Array function.
CALLING SEQUENCE:
Result = SHAPE_AREA( SHAPE)
INPUTS:
SHAPE
A (2,*) numeric array. 3D shapes are not supported.
OPTIONAL INPUT PARAMETERS:
None.
OUTPUTS:
0 for failure (improper or 3D shape) else returns the area of the shape.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
Limited to 2 dimensional shapes.
PROCEDURE:
Straightforward. Calls SHAPE_VER from MIDL.
MODIFICATION HISTORY:
Created 10-NOV-1992 by Mati Meron.
(See IDL_USER:[MERON]SHAPE_AREA.PRO;1)
NAME:
SHAPE_CLOSE
PURPOSE:
Closes the shape, i.e. appends the first point to the end of the shape,
unless the shape is already closed in which case nothing happens.
CATEGORY:
Array Manipulation / General Graphics
CALLING SEQUENCE:
Result = SHAPE_CLOSE( SHAPE)
INPUTS:
SHAPE
A (2,*) or (3,*) numeric array.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
0 for failure, i.e. a missing or invalid shape, otherwise returns the
closed shape.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward. Uses calls to SHAPE_VER and ARREQ in MIDL.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
(See IDL_USER:[MERON]SHAPE_CLOSE.PRO;1)
NAME:
SHAPE_COCON
PURPOSE:
Converts 2 or 3 dimensional shapes from the FROM to the TO coordinate
system. Allowed systems are DATA, DEVICE (only for 2-dim shapes) and
NORMAL. In principle identical to the system routine CONVERT_COORD,
SHAPE_COCON is maintained for historical reasons.
CATEGORY:
Plotting / General Graphics
CALLING SEQUENCE:
Result = SHAPE_COCON( SHAPE [,keywords])
INPUTS:
SHAPE
A (2,*) or (3,*) array.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
FROM
Specifies input coordinate system. Possible values are 'DATA',
'DEVICE' and 'NORMAL' (Only the first 3 characters matter). Default
is 'DATA'.
TO
Same as FROM for the output coordinate system.
OUTPUTS:
0 for failure (improper shape or bad keyword value) else returns the
transformed shape.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Uses calls to DEFAULT, SHAPE_VER and COO_CONV from MIDL.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
(See IDL_USER:[MERON]SHAPE_COCON.PRO;1)
NAME:
SHAPE_TRANS
PURPOSE:
Performs a geometrical transformation of an arbitrary 2_dim shape.
The transformation may include (in order):
1) Magnification by MAG. If MAG is a 2-dim vector, X and Y
coordinates are magnified by MAG(0) and MAG(1) respectively.
If FLIP is set, the magnification will include inversion in
the X or Y axis, according to the value of FLIP.
2) Rotation by the angle ANG.
3) Translation by ROFF.
CATEGORY:
General Graphics
CALLING SEQUENCE:
Result = SHAPE_TRANS( SHAPE [,parameters] [,keywords])
INPUTS:
SHAPE
A (2,*) numeric array. Future support for 3D shapes is planned.
OPTIONAL INPUT PARAMETERS:
ANG
Rotation angle, assumed to be measured in radians, unless /DEGREES is
set. Default value is 0, i.e. no rotation.
MAG
Magnification factor, can be given as a scalar (in which case both
dimensions are multiplied by this scalar) or a 2 dimensional vector (in
which case the X and Y dimensions are multiplied by MAG(0) and MAG(1)
respectively. Default value is 1, i.e. no magnification.
ROFF
Translation vector. Can be given as a scalar (in which case same
translation is applied to both dimensions) or as a 2 dimensional
vector. Default is [0,0], i.e. no translation.
KEYWORD PARAMETERS:
/DEGREES
Switch. If set, the angle value is given in degrees.
FLIP
Accepts a char value ('X' or 'Y'). Causes inversion in the
appropriate axis.
/CENTER
Switch. If set, the transformations are performed relative to the
center of the shape, given by the average of the minimal and maximal
value in each dimension. By default the transformation center is [0,0].
OUTPUTS:
0 for failure (improper or 3D shape) else returns the transformed shape.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
Currently limited to 2 dimensional shapes.
PROCEDURE:
Uses calls to DEFAULT, SHAPE_VER, STRMATCH and TYPE from MIDL.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
(See IDL_USER:[MERON]SHAPE_TRANS.PRO;1)
NAME:
SHAPE_VER
PURPOSE:
Checks whether SHAPE is a proper shape, i.e. a (2,*) or (3,*) , numeric
non-complex array.
CATEGORY:
General Graphics.
CALLING SEQUENCE:
Result = SHAPE_VER( SHAPE [, LENGTH = LEN])
INPUTS:
SHAPE
Arbitrary
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
LENGTH
Provides an optional output. See below.
OUTPUTS:
If SHAPE fits the definition of a proper shape (see above), returns the
number of dimensions (2 or 3) as floating, otherwise returns 0.
OPTIONAL OUTPUT PARAMETERS:
LENGTH
The name of a variable to receive the length (number of points) of the
shape. If the shape isn't defined or isn't proper, the value is 0.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Uses information provided by the system function SIZE.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron under the name IS_SHAPE
Renamed SHAPE_VER, 25-NOV-1993 for consistency with other shape routines
(See IDL_USER:[MERON]SHAPE_VER.PRO;1)
NAME:
SHUFFLE
PURPOSE:
Randomizes an array.
CATEGORY:
Array function.
CALLING SEQUENCE:
Result = SHUFFLE( ARR [, keywords])
INPUTS:
ARR
Array, arbitrary type.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
SEED
1) In the default usage, SEED is optional. It accepts a value to be
used as the randomization seed. It can also be used as an optional
output parameter (see below)
2) If the keyword REORDER is used, SEED is obligatory and contains the
seed used for derandomizing. If it does not equal the value that was
returned while randomizing the array, ARR will be rerandomized instead
of reordered.
REORDER
Switch. If set, the array is returned to its original order.
OUTPUTS:
Returns an array with the same values as the original one but in random
order.
OPTIONAL OUTPUT PARAMETERS:
SEED
If, during a randomization call, SEED is provided with a name of a
variable, it returns in this variable the seed value that can be used
in a reorder call.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward. Uses the system routine RANDOMU.
MODIFICATION HISTORY:
Created 1-MAY-1995 by Mati Meron.
(See IDL_USER:[MERON]SHUFFLE.PRO;1)
NAME:
SIGN
PURPOSE:
Gives the sign of X, i.e. 1 for positive, -1 for negative, 0 for 0.
CATEGORY:
Mathematical Function (General)
CALLING SEQUENCE:
Result = SIGN(X)
INPUTS:
X
Numerical, otherwise arbitrary.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Returns the value of SIGN(X), see above, as an long integer.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
For complex X the result is SIGN(REAL(X)), the imaginary part is ignored
PROCEDURE:
Straightforward. Using CAST from MIDL.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
Modified 25-DEC-1991 by Mati Meron.
Modified 5-DEC-1993 by Mati Meron. Output type changed to LONG.
(See IDL_USER:[MERON]SIGN.PRO;1)
NAME:
SOLVE_LINSYS
PURPOSE:
Solves the system of linear equations ARR*X = RHS
CATEGORY:
Mathematical Function /matrix manipulation.
CALLING SEQUENCE:
Result = SOLVE_LINSYS( ARR, RHS [, keywords])
INPUTS:
ARR
Matrix, numeric. Must be square, unless the keyword SVD is set.
RHS
Vector representing the right hand side of the equation. Length should
be compatible to the dimensions of the matrix.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
THRESHOLD
Sets the threshold that's used to determine whether the matrix is
regular. Default value is 1e-20. See OPTIONAL OUTPUT PARAMETERS for
details.
STATUS
Optional output, see below.
/SVD
Switch. Specifies solution using the Singular Value Decomposition
method. Default is LU decomposition.
UMAT
Optional SVD output. See below.
VMAT
Optional SVD output. See below.
DVEC
Optional SVD output. See below.
OUTPUTS:
Returns the solution of the linear system in a vector form, type floating
or higher.
OPTIONAL OUTPUT PARAMETERS:
STATUS
The name of the variable to receive the status flag for the operation.
Possible values are 0 for a singular ARR, 1 for regular. ARR is
considered singular if the ratio of the smallest and largest diagonal
element in the LU decomposition (or the diagonal part of the SVD
decomposition) of ARR is less then THRESHOLD.
UMAT
SVD only. The name of the variable to receive the U matrix from the
SVD decomposition. See SVD routine for more detail.
VMAT
SVD only. The name of the variable to receive the V matrix from the
SVD decomposition. See SVD routine for more detail.
DVEC
Named variable. Result depends on calculation mode, namely:
LU : vector of the diagonal elements of the LU decomposition.
SVD : vector of the diagonal elements of W (see the SVD routine).
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Normally uses LU decomposition and backsubstitution, followed by LU
correction. These operations are perfomed by the system routines
LUDCMP, LUBKSB and MPROVE, based on routines from the book NUMERICAL
RECIPES IN C. If the keyword SVD is set, the solution is obtained
using Singular Value Decomposition, and back-substitution performed by
the system routines SVDC and SVSOL (same source). Also uses the
functions CAST, DEFAULT, DIAGOVEC and TYPE from MIDL.
MODIFICATION HISTORY:
Created 15-DEC-1991 by Mati Meron.
Modified 25-MAY-1993 by Mati Meron. SVD option added.
Modified 30-JUN-1995 by Mati Meron. Changed from the SVD and SVBKSB
routines to the new SVDC and SVSOL. The change is transparent to the
user other than the fact that that it allows for a DOUBLE type SVD
solution.
(See IDL_USER:[MERON]SOLVE_LINSYS.PRO;1)
NAME:
SORPURGE
PURPOSE:
Similar to the SORT function, but ignores repeated values of elements.
CATEGORY:
Array Manipulation
CALLING SEQUENCE:
Result = SORPURGE ( ARR [, keywords])
INPUTS:
ARR
The array to be sorted (scalar is also accepted).
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
NETLEN
Optional output, see below.
OUTPUTS:
Returns a vector of indices that allow access to all DIFFERENT elements
of ARR in ascending order.
OPTIONAL OUTPUT PARAMETERS:
NETLEN
The name of a variable to receive the number of elements
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Uses SORT to order the array, then finds all the elements that differ
from their predecessors.
MODIFICATION HISTORY:
Created 15-AUG-1992 by Mati Meron.
(See IDL_USER:[MERON]SORPURGE.PRO;1)
NAME:
SPLINT
PURPOSE:
Integrates a function provided as a set of spline coefficients.
CATEGORY:
Mathematical Function (general)
CALLING SEQUENCE:
Result = SPLINT (X, SPC [/VALUE_ONLY])
INPUTS:
X
Numeric vector, 2 or more points. The X coordinates of the data.
SPC
An (n,3) array of spline coefficients, created by the function
SPLIN_COEEFS.
KEYWORD PARAMETERS:
/VALUE_ONLY
Switch. Normally SPLINT returns the integral function of Y, as a vector
(see OUTPUTS below). If VALUE_ONLY is set, only the full value of the
integral is returned as scalar. This makes the execution faster.
OUTPUTS:
Normally returns the integral function of Y, i.e. a vector whose i-th
entry is the integral of Y from X(0) to X(i) (and therefore the last
entry is the full integral of Y. If the optional keyword VALUE_ONLY is
set, only the full integral is returned, as a scalar.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
The X vector must be of length >= 2.
PROCEDURE:
Exact integration, of the cubic-spline approximation to the function.
Uses SPLIN_EVAL from MIDL.
MODIFICATION HISTORY:
Created 20-FEB-1993 by Mati Meron.
(See IDL_USER:[MERON]SPLINT.PRO;1)
NAME:
SPLIN_COEFFS
PURPOSE:
Calculates cubic splines coefficients which are intended to be used by
the supplementary function SPLIN_EVAL. The combination of SPLIN_COEFFS
and SPLIN_EVAL is more efficient than the library function SPLINE when
repeated interpolations based on the same data set are performed.
CATEGORY:
Mathemetical Function (General).
CALLING SEQUENCE:
Result = SPLIN_COEFFS( X, Y [, /SEGMENTED] )
INPUTS:
X
Vector, numeric, at least 2 elements. Contains the X coordinates of
the data, in arbitrary order.
Y
Vector, numeric, same length as X. Contains the Y values corresponding
to the values in X.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
/SEGMENTED
Switch. If set the input data is treated as segmented, where segment
boundary is defined as two consecutive points with the same X
coordinate. Spline fitting is performed on each segment separately.
In default operation, whenever multiple points with the same X
coordinate are encountered, all but the first one are deleted.
OUTPUTS:
Returns an (n,3) array where n is the number of data points. The
columns of the result are:
0 - X values, sorted in increasing order.
1 - Corresponding Y values.
2 - Calculated corresponding spline coefficients.
This array is intended to be used as an input to the function SPLIN_EVAL
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
As mentioned above, the X and Y arrays must have at least 2 elements.
Also, if the keyword SEGMENTED is used, the arrays must be presorted in
ascending order. In normal (not SEGMENTED) evaluation the order
doesn't matter.
PROCEDURE:
Standard Cubic spline evaluation (see Numerical Recipies, chapt. 3.3)
with the boundary condition of 0 THIRD derivative (constant end
curvature). Calls itself recursively. Also uses calls to CAST and
SORPURGE in MIDL. If X and Y have only 2 elements, the spline is a
plain linear fit.
MODIFICATION HISTORY:
Created 15-APR-1992 by Mati Meron.
Modified 15-AUG-1992 by Mati Meron. Replaced SORT with SORPURGE in
order to protect against a possible repetition of x values.
Modified 10-FEB-1993 by Mati Meron. Added SEGMENTED option.
Modified 10-APR-1993 by Mati Meron. Added acceptance of 2-point data.
(See IDL_USER:[MERON]SPLIN_COEFFS.PRO;1)
NAME:
SPLIN_EVAL
PURPOSE:
Cubic spline evaluation using spline coefficients supplied by the
supplementary function SPLIN_COEFFS. The combination of SPLIN_COEFFS
and SPLIN_EVAL is more efficient than the library function SPLINE when
repeated interpolations based on the same data set are performed.
CATEGORY:
Mathemetical Function (General).
CALLING SEQUENCE:
Result = SPLIN_EVAL( X, SPC [, DERIV = Nder)
INPUTS:
X
Numeric, otherwise arbitrary. The X value (or values) for which the
spline interpolation is to be performed.
SPC
An (n,3) array of spline coefficients, created by the function
SPLIN_COEEFS.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
DERIV
Integer. If provided and nonzero, an interpolated derivative of the
order DERIV is returned. Default value is 0.
OUTPUTS:
Returns the result of the interpolation, in the same form as X. The
type of the result is floating or higher, depending on X.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Standard Cubic spline evaluation (see Numerical Recipies, chapt. 3.3)
with the boundary condition of 0 THIRD derivative (constant end
curvature). Uses DEFAULT from MIDL.
MODIFICATION HISTORY:
Created 15-APR-1992 by Mati Meron.
Modified 15-MAY-1992 by Mati Meron. Added derivative option.
(See IDL_USER:[MERON]SPLIN_EVAL.PRO;1)
NAME:
SP_BESELJ
PURPOSE:
Calculates spherical Bessel functions of the first kind, j_n(x).
CATEGORY:
Mathematical function.
CALLING SEQUENCE:
Result = SP_BESELJ( X, N)
INPUTS:
X
Numeric, otherwise arbitrary.
N
Nonnegative scalar. Should be integer (if not then rounded downwards
to an integer on input.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Returns the values of the spherical Bessel function j_n(x), which is
related to the standard Bessel function J by
j_n(x) = sqrt(pi/(2*x))*J_(n+1/2) (x)
The result is of the same form and type as the input (but no lower then
FLOAT.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None other than the restriction on N mentioned above.
PROCEDURE:
Uses a combination of modified series expansion (for small values of X
and recursion for large X. The transition between the two regions
occurs in the vicinity of |X| ~ N.
Warning: for large values of N small inaccuracies may occur in the
vicinity of the transition region. These are usually to small to be
noticed, though.
Calls CAST and TYPE from MIDL.
MODIFICATION HISTORY:
Created 5-SEP-1995 by Mati Meron.
(See IDL_USER:[MERON]SP_BESELJ.PRO;1)
NAME:
SP_BESELY
PURPOSE:
Calculates spherical Bessel functions of the first kind, y_n(x).
CATEGORY:
Mathematical function.
CALLING SEQUENCE:
Result = SP_BESELY( X, N)
INPUTS:
X
Numeric, otherwise arbitrary.
N
Nonnegative scalar. Should be integer (if not then rounded downwards
to an integer on input.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Returns the values of the spherical Bessel function y_n(x), which is
related to the standard Bessel function Y by
y_n(x) = sqrt(pi/(2*x))*Y_(n+1/2) (x)
The result is of the same form and type as the input (but no lower then
FLOAT.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None other than the restriction on N mentioned above.
PROCEDURE:
Recursion, using calculated values of y_0 and y_1.
Calls CAST and TYPE from MIDL.
MODIFICATION HISTORY:
Created 5-SEP-1995 by Mati Meron.
(See IDL_USER:[MERON]SP_BESELY.PRO;1)
NAME:
SQUARE
PURPOSE:
Draws a SQUARE, based on a length of a side and a given location of a
corner. The square is drawn so as to appear visually as a square, even
if the lengths of the sides in DATA coordinates differ. The drawing is
done in the currently defined plot area. DATA coordinates are used
unless one of the keywords /DEVICE or /NORMAL is set.
CATEGORY:
General Graphics.
CALLING SEQUENCE:
Square, {BASE = BAS, HEIGHT = HEI, SIDE = SID}, $
{LL_CORNER = LLC, LR_CORNER = LRC, UR_CORNER = URC, UL_CORNER = ULC}, $
[optional keywords]
INPUTS:
None.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
BASE |
Length of side, measured in the X-direction. | One
SIDE | and only one
Same as BASE. | must be
HEIGHT | provided
Length of side, measured in the Y-direction. |
LL_CORNER |
2dim vector, coordinates of the lower left corner. |
LR_CORNER | One
2dim vector, coordinates of the lower right corner.| and only one
UR_CORNER | must be
2dim vector, coordinates of the upper right corner.| provided
UL_CORNER |
2dim vector, coordinates of the upper left corner. |
/FILL
Switch. Causes the square to be filled with a solid pattern.
/DEVICE
Standard IDL plotting interpretation.
/NORMAL
Ditto.
_EXTRA
A formal keyword used to pass all plotting keywords. Not to be used
directly.
OUTPUTS:
None.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
SQUARE passes the extra keywords through _EXTRA, without checking.
Therefore, some care must be exercised.
PROCEDURE:
Uses calls to COO_CONV and ONE_OF from MIDL. Converts all
parameters to device coordinates and calls RECTAN (also from MIDL) to
do the actual plotting.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
Modified 15-DEC-1993 by Mati Meron. Now SQUARE takes advantage of the
keyword inheritance property and accepts all IDL plotting keywords.
(See IDL_USER:[MERON]SQUARE.PRO;1)
NAME:
SQUNEXP
PURPOSE:
Calculates a "flattened" exponent. See definition below.
CATEGORY:
Mathematical function.
CALLING SEQUENCE:
Result = SQUNEXP( X, N)
INPUTS:
X
Numeric, otherwise arbitrary. However, negative inputs may create
overflows and/or divergences.
N
Nonnegative scalar. Should be integer (if not then rounded downwards
to an integer on input.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Returns the values of a "flattened negative exponent, defined by
SQUNEXP(X,N) = exp(-X)*sum_(0 to N)(X^K)/K!
The result is of the same form and type as the input (but no lower then
FLOAT.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None other than the restriction on N mentioned above.
PROCEDURE:
Clenshaw recursion with renormalization.
Calls CAST and ISNUM from MIDL.
MODIFICATION HISTORY:
Created 25-OCT-1995 by Mati Meron.
(See IDL_USER:[MERON]SQUNEXP.PRO;1)
NAME:
SQUNORM
PURPOSE:
Calculates a "flattened" Gaussian. See definition below.
CATEGORY:
Mathematical function.
CALLING SEQUENCE:
Result = SQUNORM( X, N)
INPUTS:
X
Numeric, otherwise arbitrary. However, negative inputs may create
overflows and/or divergences.
N
Nonnegative scalar. Should be integer (if not then rounded downwards
to an integer on input.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Returns the values of a "flattened" Gaussian, defined by
SQUNORM(X,N) = C*exp(-X^2/(2*D^2))*sum_(0 to N)((X^2/(2*D^2))^K)/K!
Where the constants C, D, given by:
C = sqrt((2*N+3)/(6*PI))*2^(2*N)*(N!)^2/(2*N+1)!
D = sqrt(3/(2*N+3))
are chosen so as to make the integral and the variance of the function
equal 1 (especially for N=0 the standard Normal distribution is
obtained).
The result is of the same form and type as the input (but no lower then
FLOAT.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None other than the restriction on N mentioned above.
PROCEDURE:
Calculates the mormalization constants and calls SQUNEXP. Also calls
CAST, DEFAULT and TYPE from MIDL.
MODIFICATION HISTORY:
Created 25-OCT-1995 by Mati Meron.
(See IDL_USER:[MERON]SQUNORM.PRO;1)
NAME:
STREQ
PURPOSE:
Compares for equality the first LEN characters of STR1, STR2.
If LEN is 0, or absent, the whole strings are compared.
CATEGORY:
String Processing
CALLING SEQUENCE:
Result = STREQ( STR1, STR2 [,LEN] [, keywords])
INPUTS:
STR1, STR2
character strings, mandatory.
OPTIONAL INPUT PARAMETERS:
LEN
Number of characters to compare. Default is 0, translating to a full
comparison.
KEYWORD PARAMETERS:
/CASEON
Switch. If set the comparison is case sensitive. Default is ignore case.
/WARN
Switch. If set, a warning is issued whenever STR1 or STR2 is not a
character variable. Default is no warning.
OUTPUTS:
1b for equal, 0b for nonequal.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward. Using DEFAULT and TYPE from MIDL.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
(See IDL_USER:[MERON]STREQ.PRO;1)
NAME:
STRMATCH
PURPOSE:
Compares the string STR with the strings in the array LIST. Comparison
is done for the first LEN characters, or all of them if LEN is 0. If a
match is found, STR is replaced by the full string from the list (or
if the keyword /ALL is set, by an array containing all the matching
strings).
CATEGORY:
String Processing
CALLING SEQUENCE:
Result = STRMATCH( STR, LIST [, LEN] [, keywords])
INPUTS:
STR
Character string.
LIST
Character array.
OPTIONAL INPUT PARAMETERS:
LEN
The number of characters to compare. Default is full comparison.
KEYWORD PARAMETERS:
/CASEON
Switch. If set the comparison is case sensitive. Default is ignore case.
/ALL
Switch. If set, returns the indices of all the matching elements.
OUTPUTS:
Returns the index of the first match, or -1l if no match is found.
Optionally (see keyword ALL above) returns all the matching indices.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None other then the substitution in STR.
RESTRICTIONS:
None.
PROCEDURE:
Uses the function STREQ from MIDL.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
Modified 20-NOV-1993 by Mati Meron. Added keyword ALL.
(See IDL_USER:[MERON]STRMATCH.PRO;1)
NAME:
STRPARSE
PURPOSE:
Parses the string LINE using the characters in DELIM as delimiters.
Puts individual pieces into consecutive locations in LIST.
CATEGORY:
String Processing
CALLING SEQUENCE:
Result = STRPARSE( LINE, DELIM [, LIST])
INPUTS:
LINE
Character string.
DELIM
Character string. Each Character of DELIM is used as a delimiter.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Returns the number of pieces found minus one i.e. the index of the last
element of LIST if LIST is provided. If LINE is a null string or not a
string, the function returns -1l.
OPTIONAL OUTPUT PARAMETERS:
LIST
Character array. If name is provided, the pieces of LINE resulting
from the parsing process are returned in consecutive locations in LIST.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward. Using the function TYPE from MIDL.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
(See IDL_USER:[MERON]STRPARSE.PRO;1)
NAME:
TABULATE
PURPOSE:
Accepts data in form of a set (up to 8) one dimensional arrays and
prints it out as a table.
CATEGORY:
Input/Output
CALLING SEQUENCE:
TABULATE, A [,B ....H] [,keywords]
INPUTS:
A [B ... H]
One or more (up to 8) one dimensional arrays. Type arbitrary
(including string arrays). If the array lengths are not all equal, the
shortest length will be used.
OPTIONAL INPUT PARAMETERS:
All but the first array are arbitrary.
KEYWORD PARAMETERS:
/INDEX
If set, the elements indices (0, 1 ... etc.) are printed in the first
column of the table. Set by default if only one column is provided.
FROM
Specifies the index of the first element to be displayed. Default is 0.
TO
Specifies the index of the last element to be displayed. Default is
end of array.
TITLE
Character string, used as the title of the table. Default is no title.
HEADER
Character array containing the titles of the columns. Default titles
are the letters A thru H. The title of the index column, if it appears
is N and cannot be changed. If some of the entries in HEADER are null
strings, the default headers will be used for the corresponding columns.
/NOHEADER
Switch. If set, no header is printed. If HEADER is provided and
NOHEADER is set, HEADER will be ignored.
FORMAT
Character array, containing format specifications for the columns. The
default formats are as follows:
BYTE - I4
INTEGER - I6
LONG - I11
FLOATING - G14.7
DOUBLE - G22.14
COMPLEX - G14.7 (twice)
STRING - A16
DOUBLECOMPLEX - G22.14 (twice)
If some of the entries in FORMAT are null strings, defaults will be
used for the corresponding columns. If only partial formats are given
(for example 'E', or '16.6') missing fields are filled from the
default. Valid formats are A, D, E, F, G, I, O, Z. Nonvalid formats
are ignored.
Important: TABULATE may change the formats (either defaults or
provided explicitly through FORMAT) in order to make enough room in the
display.
REALFORM
Character string (only first letter matters). If given and is one of
D, E, F or G, provides the default format for all the real, double and
complex data. If not given, the default is G format.
FILE
String representing a valid file name (if extension is not provided the
default is .TAB). If provided, the output is sent to this file,
otherwise it is sent to the terminal.
/MORE
Sends output to the screen one page at a time (like UNIX MORE).
OUTPUTS:
None, other then the printed table.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
TABULATE may reduce the widths of the print fields in order to
accomodate all the data. If after reduction to minimum widths the data
still cannot be fitted, no table will be generated.
While in theory tabulate can display up to 8 columns, the actual number
depends on the data types. Approximate maximal numbers of columns are:
BYTE, INTEGER or STRING - 8 columns (strings may be truncated)
LONG or FLOAT - 6 columns
DOUBLE - 5 columns
COMPLEX - 3 columns
DOUBLECOMPLEX - 2 columns
PROCEDURE:
Straightforward. Uses DEFAULT, STRPARSE and TYPE from MIDL.
MODIFICATION HISTORY:
Created 3-MAY-1992 by Mati Meron.
Modified 20-JUN-1995 by Mati Meron to accept the new DOUBLECOMPLEX type.
Modified 30-MAY-1996 by Mati Meron. Added keyword NOHEADER.
(See IDL_USER:[MERON]TABULATE.PRO;1)
NAME:
TOLER
PURPOSE:
Establishes numerical tolerance value for numerical procedures.
CATEGORY:
Programming.
CALLING SEQUENCE:
Result = TOLER(X [, TYPE = TYP])
INPUTS:
X
Numeric, otherwise arbitrary. Ignored if the keyword TYPE (see below)
is used.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
TYPE
Type code. If given overrides the type provided by X
OUTPUTS:
Returns a value equal to twice the .EPS field of the structure created
by the IDL function MACHAR. If the type code, as set by the type of X,
or directly by the keyword TYPE is 5 (DOUBLE) or 9 (DOUBLECOMPLEX),
MACHAR is called with the keyword /DOUBLE.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
X (when provided) must be numeric else an error occurs. Similarly,
calling TOLER with TYPE = 8 or 9 will cause an error.
PROCEDURE:
Straightforward. Uses MACHAR. Calls DEFAULT and TYPE from MIDL.
MODIFICATION HISTORY:
Created 15-JUN-1995 by Mati Meron.
(See IDL_USER:[MERON]TOLER.PRO;1)
NAME:
TYPE
PURPOSE:
Finds the type class of a variable.
CATEGORY:
Programming.
CALLING SEQUENCE:
Result = TYPE(X)
INPUTS:
X
Arbitrary, doesn't even need to be defined.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Returns the type of X as a long integer, in the (0,9) range.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Extracts information from the SIZE function.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
(See IDL_USER:[MERON]TYPE.PRO;1)
NAME:
WHERINSTRUCT
PURPOSE:
Finding fields within a structure.
CATEGORY:
Programming.
CALLING SEQUENCE:
Result = WHERINSTRUCT( TAGNAM, STRUCTNUM [, COUNT] [,TAGS = TNAM])
INPUTS:
TAGNAM
Character variable or constant.
STRUCTNUM
Name of a structure variable.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
TAGS
Optional output, see below.
OUTPUTS:
If STRUCTNAM exists, is a structure, and has one or more tag names
which match with TAGNAM, The return is a numeric (long integer) array
which includes the indices of the matching fields (similar to the
output of WHERE. In all other cases the output is -1.
OPTIONAL OUTPUT PARAMETERS:
COUNT
Same as in WHERE, returns the number of matches found.
TAGS
Accepts the name of the variable in which the names of the matching
fields are returned as a string array.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Uses the system routine TAG_NAMES to find all the tag names of the
structure, and then uses STRMATCH from MIDL to match these names with
the input TAGNAM. The number of characters in TAGNAM determines the
number of characters used in the match. For example, if TAGNAM = 't'
then all the names starting with 't' will be picked but if TAGNAM =
'thor' then only those starting with 'thor' will be noticed.
Calls STRMATCH and TYPE from MIDL.
MODIFICATION HISTORY:
Created 15-JUN-1995 by Mati Meron.
(See IDL_USER:[MERON]WHERINSTRUCT.PRO;1)
NAME:
WRITE_ASCII
PURPOSE:
Writes an array into an ASCII file.
CATEGORY:
Input/Output.
CALLING SEQUENCE:
WRITE_ASCII, ARR, FILNAM [, keywords]
INPUTS:
ARR
Array, arbitrary, no more than 8 columns.
FILNAM
Char. value, the name of the data file. Default extension is '.DAT'.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
TITLE
Character string, optional, used as title of the data
HEADER
Character array, optional, if provided, the entries are used as column
titles. Null string entries translate to default column headings of
TABULATE. If not provided, no column headers appear in the file.
FORMAT
Character string translating to a valid format. If provided will apply
to all the columns. If not provided. the default formats of TABULATE
are used.
OUTPUTS:
None.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
The number of columns (first index of array) is limited. See
restrictions in TABULATE.
PROCEDURE:
Straightforward, using TABULATE from MIDL. Also calls DEFAULT, and
TYPE from MIDL.
MODIFICATION HISTORY:
Created 30-MAY-1996 by Mati Meron.
(See IDL_USER:[MERON]WRITE_ASCII.PRO;1)