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.