CHAPTER 5 GENERAL PURPOSE MODULES
5.1 USRINP SUBROUTINE
This subroutine accepts numerical and character information
from the user in free format with defaults.
Call:
CALL USRINP(A,N,TYPE,LENGTH,DEFAULT,KEYWORD,MESSAGE)
where:
NAME I/O TYPE DESCRIPTION
NAME I/O TYPE DESCRIPTION
A C R4 is the array of dimension N. Usually this
is the output it is also used to supply
default information to the user.
N C R4 is the dimension of A. Can be 1 if A is a
simple variable
TYPE C CHAR 'F' real numbers returned unless input
contains alphanumeric information.
'I' Integers are returned.
'A' Alphanumeric information. No
conversions are made.
'L' Logical. A is true if reply is yes,
ja, or true. A is false if reply is no,
nee, or false. The first letter is
sufficient. Note that logical variables
can be declared as LOGICAL in the calling
program but must have LENGTH=1.
LENGTH C I4 is the data type length in bytes. 1, 2, 4,
end 8 are possible. See note on length of
logical variables above.
DEFAULT C I4 0 No defualt is possible; user is forced to
answer.
1 Default is input values of A if user
replys with <CR>.
2 Default is input values of A if no
keyword is present.
3 Suppresses printing of values.
KEYWORD C CHAR The keyword is used to supply the parameter
in advance. It must end with an = and
cannot have a space, e.g., 'STAR='.
MESSAGE C CHAR Message to user if keyword is or is not
present.
Page 2
The input is in free format. Real numbers can be given in
exponential format. Reals and integers must be separated by
blanks or commas. For these types it is possible to give
do-loops in the format s:e[:i] without separations symbols where
s=startv e=endvalue, and i=incrementvalue (default i=1). (Max.
10 do-loops in one string). Array A is filled up with "ENDLIN"
double words, "ENDLIN" words,or binary zeros depending on TYPE.
The input is decoded by DCD. Do not use the tab.
Example: To read one number into the R*4 variable XMAG with a
default value of 13.7 XMAG=13.7 CALL:
CALL USRINP(XMAG,1,'F',4,0,'MAGNITUDE=','Enter the
1magnitude:')
Page 3
5.2 ALPHA SUBROUTINE
This subroutine is designed to deal with character data from
USRINP.
Call:
CALL ALPHA(A,N,LENGTH,NCHAR,NFULL,NREST,NPOS)
where:
NAME I/O TYPE DESCRIPTION
NAME I/O TYPE DESCRIPTION
A C BYTE is the input array.
N C I4 is the dimension of A.
LENGTH C I4 is the length of the words (in bytes).
NCHAR R I4 is the number of actual characters.
NFULL R I4 is the number of full words.
NREST R I4 is the number of remaining characters.
NPOS C I4 is the possibility selector; if 1, it
counts the number of characters in each
word; if 2, it sets the remaining "0"s to
blanks; if 3, it counts the number of
characters in each word exclusive of
control characters; if 4 it sets the
remaining 0's and ,'s to blanks and places
each word in its correct position.
Example: NAME is CHARACTER*40; USRINP reads it in:
CALL USRINP(%REF(NAME),1,'A',40,1,'FILE=','Enter the filename:
1(default = last entry)')
Then ALPHA is called returning the length of the string.
CALL ALPHA(%REF(NAME),1,40,LX,NF,NR,1)
Example: COLORS(10) is CHARACTER*7; USRINP reads it in:
CALL USRINP(%REF(COLORS),10,'A',7,0,'COLORS=','Enter the
1colors: (default = RED)')
The user then responds with RED WHITE BLUE
Then ALPHA is called, setting zeros to blanks and placing the
entries in their correct positions within the word.
CALL ALPHA(%REF(COLOR),10,6,LX,NF,NR,1)
The result is RED WHITE BLUE
Page 4
5.3 MESSAGE SUBROUTINE
This subroutine is used to send all messages to the user.
It saves writing FORMAT statements and WRITE statements and
automatically logs the message to file "007". (This is the "log"
file in MIIPS).
Example: CALL MESSAGE('Enter the start radius and end
1radius for plotting:')
Page 5
5.4 LINFIT1D SUBROUTINE
This subroutine does a linear least squares fit to weighted
data and returns the parameters of the fit and their errors. If
desired, selected coefficients may be held constant in the
solution. There is no limit on the degree of the polynomial.
For plotting purposes, an array is filled with calculated values
corresponding to the values in the array XPLOT. For spline fits,
this is the only meaningful returned value.
Call:
CALL LINFIT1D(X,DATA,WEIGHT,NPOINTS,DEGREE,CONSTANTTERMS,
1COEFF,COVARIANCE,MEANERROR,XPLOT,YPLOT,NPLPOINTS)
where:
NAME I/O TYPE DESCRIPTION
NAME I/O TYPE DESCRIPTION
X C R8 is an array containing the values of
the independent variable.
DATA C R8 is an array containing the observations
to be fitted.
WEIGHT C R8 is an array for the weights of each
point.
NPOINTS C I4 is the dimension of the above three
arrays and the number of points to be
fit.
DEGREE C/R I4 is the degree of the polynomial fit if
.GE. 0. If DEGREE=-1, the degree of
the polynomial fit is asked for; if
DEGREE=-2, the degree of the polynomial
fit and the coefficients which are to
be held constant are asked for; if
DEGREE=-3, the type of fit is asked for
and if it is to be a polynomial, the
degree and coefficients which are to be
held constant are asked for; if
DEGREE=-99, a spline fit is done.
CONSTANTTERMS C LOG is an array which is .TRUE. if that
coefficient is to be held constant and
not solved for.
COEFF C/R R8 is an array containing the coefficients
of the polynomial of the fit.
COVARIANCE R R8 is an array containing the covariances.
MEANERROR R R8 is the mean error for an observation of
average weight.
Page 6
XPLOT C R4 is an array containing points to be
evaluated with the fitted function.
YPLOT R R4 is an array containing the evaluated
points from XPLOT.
NPLPOINTS C I4 is the dimension of the above two
arrays and the number of points
contained therein.
Page 7
5.5 LINFIT2D SUBROUTINE
This subroutine does a two-dimensional linear least squares
polynomial fit to weighted data and returns the parameters of the
fit and their errors. There is no limit on the degree of the
polynomial. For plotting purposes, an array is filled with
calculated values corresponding to the values in the arrays XPLOT
and YPLOT. For spline fits, this is the only meaningful returned
value.
Call:
CALL LINFIT2D(X,Y,DATA,WEIGHT,NPOINTS,DEGREE,CONSTANTTERMS,
1COEFF,COVARIANCE,MEANERROR,XPLOT,YPLOT,DATPLOT,2NPLPOINTS)
where:
NAME I/O TYPE DESCRIPTION
X C R8 is an array containing the values of
the X independent variable.
Y C R8 is an array containing the values of
the Y independent variable.
DATA C R8 is an array containing the observations
to be fitted.
WEIGHT C R8 is an array for the weights of each
point.
NPOINTS C I4 is the dimensions of the above three
arrays and the number of points to be
fit.
DEGREE C/R I4 is the degree of the polynomial fit if
.GE. 0. If DEGREE=-1, the degree of
the polynomial fit is asked for; if
DEGREE=-2, the degree of the polynomial
fit and the coefficients which are to
be held constant are asked for; if
DEGREE=-3, the type of fit is asked for
and if it is to be a polynomial, the
degree and coefficients which are to be
held constant are asked for; if
DEGREE=-99, a spline fit is done.
CONSTANTTERMS C LOG is an array which is .TRUE. if that
coefficient is to be held constant and
not solved for.
COEFF C/R R8 is the array containing the
coefficients of the fit. For the case
of DEGREE=3, the order of coefficients
corresponds to the order of the terms 1
X X**2 X**3 Y XY X**2Y Y**2 XY**2 Y**3.
Page 8
The sequence of crossproduct terms is
the upper left triangular part of the
crossproduct matrix arranged columnwise
where the crossproduct matrix is the
product of a square matrix with powers
of X in the first column with a square
matrix with powers of Y in the first
row and zero elsewhere.
COVARIANCE R R8 is an array containing the covariances.
MEANERROR R R8 is the mean error for an observation of
average weight.
XPLOT C R4 is an array containing the X points to
be evaluated with the fitted function.
YPLOT C R4 is an array containing the Y points to
be evaluated with the fitted function.
DATPLOT R R4 is an array containing the evaluated
points to be plotted with XPLOT.
NPLPOINTS C I4 is the dimension of the above two
arrays and the number of points
contained therein.
Page 9
5.6 NONLINFIT SUBROUTINE
This subroutine does a nonlinear least squares fit to
weighted data and returns the parameters of the fit and their
errors. If desired, certain coefficients may be held constant in
the solution. The dimensions of the independent variable and the
data are unrestricted. The number of points to be fit and the
number of parameters to be solved for are also unrestricted. For
plotting purposes, an array is filled with calculated values
corresponding to the values in the array XPLOT. The weights are
not required to be normalized, ie., they are relative weights.
For each new function category, new subroutines which calculate
the function and its derivative must be created. These must be
referenced in subroutines NLFUN and NLDER. The object codes for
subroutines NLFUN, NLDER, NLFUN#, and NLDER# belong in the
NONLINFIT library. In the calling program, the plotting arrays
XPLOT and DATPLOT must be dimensioned at least as large as the
number of points and the dimension of the data. See the programs
[MIIPS.FOR]NL_DEMO_1, NL_DEMO_2, NLTEST3, REDSHFTMAG, NLTEST5,
DISPGAL, CLUSCOUNT, NLTEST8, SADFIT, and SUBSTAR for further
details on dimensioning and the subroutines NLFUN# and NLDER# for
how to loop through the calculations.
Call:
CALL NONLINFIT(X,MAXNPOINTS,DIMENSN_IND,DATA,DIMENSN_DATA,
1WEIGHT,IX,FUNCAT,CHOICE,CONSTANTTERMS,PARAMETRS,MAXNUMPARAM,
2NUMPARAM,ITERATION_SCHEME,TOLERANCE,INTERMEDIATE,OPERATE,
3COVARIANCE,MEANERROR,XPLOT,DATPLOT,NPLPOINTS)
where:
NAME I/O TYPE DESCRIPTION
NAME I/O TYPE DESCRIPTION
X C R8 is the array containing the values of
the independent variable.
MAXNPOINTS C I4 is the dimension of the array X. This
is greater than or equal to the number
of points to be fit.
DIMENSION_IND C I4 is the dimension of the independent
variable
DATA C R8 is an array containing the
observations to be fitted.
DIMENSION_DATA C I4 is the dimension of the data
WEIGHT C R8 is an array for the weights of each
point.
IX C I4 is an array containing the starting
and ending indexes of the data for the
fit.
Page 10
FUNCAT C I4 is the number of the function
category, ie., this selects the NLFUN
and NLDER that has been written for a
particular category of solution. If
it is zero in the call, it is prompted
for.
CHOICE C CHAR6 is the choice of fitting function
within a function category. Only 5
character locations are available for
usage. The sixth position is used as
a flag by the NLFUN when filling the
plot array.
CONSTANTTERMS C LOG is an array which is .TRUE. if that
coefficient is to be held constant and
not solved for. If NUMPARAM is .LE.
zero in the call, the user is prompted
for which parameters to hold constant.
PARAMETRS C/R R8 is the array containing the
coefficients of the fitting function.
MAXNUMPARAM C I4 is the maximum number of parameters
desired to be fit by the calling
program.
NUMPARAM C/R I4 is a number such that in the call, the
absolute value gives the total number
of parameters in the function. If it
is zero in the call, the user is
prompted for the number. The absolute
value is always returned.
ITERATION_SCHEME C CHAR1 is the scheme for iterating: A is
automatic with maximum searching; B is
automatic with minimum searching; C is
automatic with no searching; M is
manual. If ITERATIONSCHEME is blank
in the call or M, the user is promted
for the value and also prompted for
the initial value of the fractional
increment.
TOLERANCE C/R R4 is the fractional tolerance for
continuing the automatic iterations.
If it is zero in the call and the
ITERATIONSCHEME = 'A', 'B', or 'C',
the user is prompted for the value.
If the change in any parameter is
greater than TOLERANCE times the sum
of the parameter and its mean error,
iteration is continued.
INTERMEDIATE C LOG is a logical variable which
Page 11
determnines whether the intermediate
results are printed on the terminal.
OPERATE C LOG is a logical variable which determines
whether to perform a user defined
operation in the subroutines NLFUN#
and NLDER#.
COVARIANCE R R8 is an array containing the
covariances.
MEANERROR R R8 is the mean error for an observation
of average weight.
XPLOT C R4 is an array containing points from
each dimension of the independent
variable to be evaluated with the
fitted function.
DATPLOT R R4 is an array containing the evaluated
points from XPLOT.
NPLPOINTS C I4 is the number of points to be plotted
Page 12
5.7 CONVLV2DG SUBROUTINE
This subroutine will convlove the array ARAYIN with the
array SMEAR. The values in ARRAYIN and SMEAR are assumed to be
symmetric about the first element (index = 0). This subroutine
is useful for convolving galaxy surface brightness distributions
with a seeing distribution when there are few pixels resolving
the center of the galaxy. The information in ARRYIN and RADIUSIN
can be arranged so that the step size in radius is smallest at
the center of the galaxy. There are no restrictions on how the
step size is determined but it should be set up in the calling
program.
Call:
CALL CONVLV2DG(ARRAYIN,RADIUSIN,SIZE,SMEAR,NPTS_S,1ARRAYOUT,
NPTS_C,NANGLES)
where:
NAME I/O TYPE DESCRIPTION
ARRAYIN C R4 is the array containing the information to
be convolved.
RADIUSIN C R4 is the array containing the corresponding
radii for each element of ARRAYIN.
SIZE C I4 is the dimension of the above 2 arrays.
SMEAR C R4 is the smearing function taken to be
symmetric about the first index. The index
is equal to the radius measured in pixels.
NPTSS C I4 is the number of data points or pixels in
the array SMEAR and the dimension of the
array.
ARRAYOUT R R4 is the output array.
NPTS C I4 is the dimension of the array ARRAYOUT and
the maximum radius measured in pixels.
NPTSC C I4 is the number of points or pixels to be
convolved. If the entire range is to be
convolved it should equal NPTS but if a
saving in time is desired it can be less.
If NPTSC < NPTS, ARRAYOUT will contain the
unconvolved information for indexes > NPTSC
- 1.
NANGLES C I4 is the number of different angles at which
the function is sampled; 36 is a good
number. 72 is the current maximum.
Page 13
5.8 BLACKBODY SUBROUTINE
This subroutine computes various quantitites associated with
the Planck function.
Call:
CALL BLACKBODY(TEMP,WAVELEN,WAVELENMAX,SPECIFINT,BLBDYINT,
1DBB1,DBB2)
where:
NAME I/O TYPE DESCRIPTION
TEMP C R4 is the temperature in degrees Kelvin.
WAVELEN C R4 is the wavelength in microns.
WAVELENMAX R R4 is the wavelength in microns of the peak in
the blackbody spectrum,
SPECIFINT R R4 is the specific intensity in ergs/sec/cm2/
steradian/micron.
BLBDYINT R R4 is the black body intensity in
ergs/sec/cm2/ steradian.
DBB1 R R4 is the first derivative of SPECIFINT with
respect to microns.
DBB2 R R4 is the second derivative of SPECIFINT
REAL*8 C1,C2,C3, C4,C5,C6,PI,SIGMA.
Page 14
5.9 BELL SUBROUTINE
This subroutine rings the bell on a terminal. This is
useful for notifying a user when a process has completeled or a
response is required.
Page 15
5.10 INTERP1D SUBROUTINE
This subroutine linearly interpolates to find a value within
the range of ARRAY2 corresponding to the value chosen within the
range of ARRAY1. The interval between values is allowed to be
arbitrary, hovever, it is assumed that the values in ARRAY1 are
monotonically increasing or decreasing.
Call:
CALL INTERP1D(ARRAY1,ARRAY2,MAXSIZE,VALUE1,VALUE2)
where:
NAME I/O TYPE DESCRIPTION
NAME I/O TYPE DESCRIPTION
ARRAY1 C R4 is the array for the independent variable.
ARRAY2 C R4 is the array for the dependent variable.
MAXSIZE C I4 is the dimension of ARRAY1 and ARRAY2.
VALUE1 C R4 is the known value within the range of
ARRAY1.
VALUE2 R R4 is the requested value within the range of
ARRAY2.
Page 16
5.11 INTERP2D SUBROUTINE
This function does two-dimensional interpolation when given
a fractional pixel location. The pixel intensities of four
pixels are averaged with weights determined by the area of
overlap of a single pixel centered on the given fractional
location. The actual pixels used are determined by what quadrant
of the original pixel the given point lies in.
Call:
CALL INTERP2D(DATA,NCOL,NROW,S,Y)
where:
NAME I/I TYPE DESCRIPTION
NAME I/I TYPE DESCRIPTION
DATA C R4 is the array containing the data.
NCOL C I4 is the dimension of DATA in the X
direction.
NROW C I4 is the dimension of DATA in the Y
direction.
X C R4 is the pixel location in the x direction
where X=1.0 is the smallest value that can
reference the array.
Y C R4 is like X but in the Y direction.