XSET(3)

SYNOPSIS
SUBROUTINE XSET (IRAD, NRADPL, DZERO, NBITS, IERROR)

NAME
xset - To provide single-precision floating-point arithmetic with an extended exponent range.

LIBRARY
SLATEC

CATEGORY
A3D

TYPE
SINGLE PRECISION (XSET-S, DXSET-D)

KEYWORDS
EXTENDED-RANGE SINGLE-PRECISION ARITHMETIC

AUTHOR
Lozier, Daniel W., (National Bureau of Standards) Smith, John M., (NBS and George Mason University)

DESCRIPTION
SUBROUTINE XSET MUST BE CALLED PRIOR TO CALLING ANY OTHER EXTENDED-RANGE SUBROUTINE. IT CALCULATES AND STORES SEVERAL MACHINE-DEPENDENT CONSTANTS IN COMMON BLOCKS. THE USER MUST SUPPLY FOUR CONSTANTS THAT PERTAIN TO HIS PARTICULAR COMPUTER. THE CONSTANTS ARE IRAD = THE INTERNAL BASE OF SINGLE-PRECISION ARITHMETIC IN THE COMPUTER. NRADPL = THE NUMBER OF RADIX PLACES CARRIED IN THE SINGLE-PRECISION REPRESENTATION. DZERO = THE SMALLEST OF 1/DMIN, DMAX, DMAXLN WHERE DMIN = THE SMALLEST POSITIVE SINGLE-PRECISION NUMBER OR AN UPPER BOUND TO THIS NUMBER, DMAX = THE LARGEST SINGLE-PRECISION NUMBER OR A LOWER BOUND TO THIS NUMBER, DMAXLN = THE LARGEST SINGLE-PRECISION NUMBER SUCH THAT LOG10(DMAXLN) CAN BE COMPUTED BY THE FORTRAN SYSTEM (ON MOST SYSTEMS DMAXLN = DMAX). NBITS = THE NUMBER OF BITS (EXCLUSIVE OF SIGN) IN AN INTEGER COMPUTER WORD. ALTERNATIVELY, ANY OR ALL OF THE CONSTANTS CAN BE GIVEN THE VALUE 0 (0.0 FOR DZERO). IF A CONSTANT IS ZERO, XSET TRIES TO ASSIGN AN APPROPRIATE VALUE BY CALLING I1MACH (SEE P.A.FOX, A.D.HALL, N.L.SCHRYER, ALGORITHM 528 FRAMEWORK FOR A PORTABLE LIBRARY, ACM TRANSACTIONS ON MATH SOFTWARE, V.4, NO.2, JUNE 1978, 177-188). THIS IS THE SETTING-UP SUBROUTINE FOR A PACKAGE OF SUBROUTINES THAT FACILITATE THE USE OF EXTENDED-RANGE ARITHMETIC. EXTENDED-RANGE ARITHMETIC ON A PARTICULAR COMPUTER IS DEFINED ON THE SET OF NUMBERS OF THE FORM (X,IX) = X*RADIX**IX WHERE X IS A SINGLE-PRECISION NUMBER CALLED THE PRINCIPAL PART, IX IS AN INTEGER CALLED THE AUXILIARY INDEX, AND RADIX IS THE INTERNAL BASE OF THE SINGLE-PRECISION ARITHMETIC. OBVIOUSLY, EACH REAL NUMBER IS REPRESENTABLE WITHOUT ERROR BY MORE THAN ONE EXTENDED-RANGE FORM. CONVERSIONS BETWEEN DIFFERENT FORMS ARE ESSENTIAL IN CARRYING OUT ARITHMETIC OPERATIONS. WITH THE CHOICE OF RADIX WE HAVE MADE, AND THE SUBROUTINES WE HAVE WRITTEN, THESE CONVERSIONS ARE PERFORMED WITHOUT ERROR (AT LEAST ON MOST COMPUTERS). (SEE SMITH, J.M., OLVER, F.W.J., AND LOZIER, D.W., EXTENDED-RANGE ARITHMETIC AND NORMALIZED LEGENDRE POLYNOMIALS, ACM TRANSACTIONS ON MATHEMATICAL SOFTWARE, MARCH 1981). AN EXTENDED-RANGE NUMBER (X,IX) IS SAID TO BE IN ADJUSTED FORM IF X AND IX ARE ZERO OR RADIX**(-L) .LE. ABS(X) .LT. RADIX**L IS SATISFIED, WHERE L IS A COMPUTER-DEPENDENT INTEGER DEFINED IN THIS SUBROUTINE. TWO EXTENDED-RANGE NUMBERS IN ADJUSTED FORM CAN BE ADDED, SUBTRACTED, MULTIPLIED OR DIVIDED (IF THE DIVISOR IS NONZERO) WITHOUT CAUSING OVERFLOW OR UNDERFLOW IN THE PRINCIPAL PART OF THE RESULT. WITH PROPER USE OF THE EXTENDED-RANGE SUBROUTINES, THE ONLY OVERFLOW THAT CAN OCCUR IS INTEGER OVERFLOW IN THE AUXILIARY INDEX. IF THIS IS DETECTED, THE SOFTWARE CALLS XERROR (A GENERAL ERROR-HANDLING FORTRAN SUBROUTINE PACKAGE). MULTIPLICATION AND DIVISION IS PERFORMED BY SETTING (X,IX)*(Y,IY) = (X*Y,IX+IY) OR (X,IX)/(Y,IY) = (X/Y,IX-IY). PRE-ADJUSTMENT OF THE OPERANDS IS ESSENTIAL TO AVOID OVERFLOW OR UNDERFLOW OF THE PRINCIPAL PART. SUBROUTINE XADJ (SEE BELOW) MAY BE CALLED TO TRANSFORM ANY EXTENDED- RANGE NUMBER INTO ADJUSTED FORM. ADDITION AND SUBTRACTION REQUIRE THE USE OF SUBROUTINE XADD (SEE BELOW). THE INPUT OPERANDS NEED NOT BE IN ADJUSTED FORM. HOWEVER, THE RESULT OF ADDITION OR SUBTRACTION IS RETURNED IN ADJUSTED FORM. THUS, FOR EXAMPLE, IF (X,IX),(Y,IY), (U,IU), AND (V,IV) ARE IN ADJUSTED FORM, THEN (X,IX)*(Y,IY) + (U,IU)*(V,IV) CAN BE COMPUTED AND STORED IN ADJUSTED FORM WITH NO EXPLICIT CALLS TO XADJ. WHEN AN EXTENDED-RANGE NUMBER IS TO BE PRINTED, IT MUST BE CONVERTED TO AN EXTENDED-RANGE FORM WITH DECIMAL RADIX. SUBROUTINE XCON IS PROVIDED FOR THIS PURPOSE. THE SUBROUTINES CONTAINED IN THIS PACKAGE ARE SUBROUTINE XADD USAGE CALL XADD(X,IX,Y,IY,Z,IZ,IERROR) IF (IERROR.NE.0) RETURN DESCRIPTION FORMS THE EXTENDED-RANGE SUM (Z,IZ) = (X,IX) + (Y,IY). (Z,IZ) IS ADJUSTED BEFORE RETURNING. THE INPUT OPERANDS NEED NOT BE IN ADJUSTED FORM, BUT THEIR PRINCIPAL PARTS MUST SATISFY RADIX**(-2L).LE.ABS(X).LE.RADIX**(2L), RADIX**(-2L).LE.ABS(Y).LE.RADIX**(2L). SUBROUTINE XADJ USAGE CALL XADJ(X,IX,IERROR) IF (IERROR.NE.0) RETURN DESCRIPTION TRANSFORMS (X,IX) SO THAT RADIX**(-L) .LE. ABS(X) .LT. RADIX**L. ON MOST COMPUTERS THIS TRANSFORMATION DOES NOT CHANGE THE MANTISSA OF X PROVIDED RADIX IS THE NUMBER BASE OF SINGLE-PRECISION ARITHMETIC. SUBROUTINE XC210 USAGE CALL XC210(K,Z,J,IERROR) IF (IERROR.NE.0) RETURN DESCRIPTION GIVEN K THIS SUBROUTINE COMPUTES J AND Z SUCH THAT RADIX**K = Z*10**J, WHERE Z IS IN THE RANGE 1/10 .LE. Z .LT. 1. THE VALUE OF Z WILL BE ACCURATE TO FULL SINGLE-PRECISION PROVIDED THE NUMBER OF DECIMAL PLACES IN THE LARGEST INTEGER PLUS THE NUMBER OF DECIMAL PLACES CARRIED IN SINGLE-PRECISION DOES NOT EXCEED 60. XC210 IS CALLED BY SUBROUTINE XCON WHEN NECESSARY. THE USER SHOULD NEVER NEED TO CALL XC210 DIRECTLY. SUBROUTINE XCON USAGE CALL XCON(X,IX,IERROR) IF (IERROR.NE.0) RETURN DESCRIPTION CONVERTS (X,IX) = X*RADIX**IX TO DECIMAL FORM IN PREPARATION FOR PRINTING, SO THAT (X,IX) = X*10**IX WHERE 1/10 .LE. ABS(X) .LT. 1 IS RETURNED, EXCEPT THAT IF (ABS(X),IX) IS BETWEEN RADIX**(-2L) AND RADIX**(2L) THEN THE REDUCED FORM WITH IX = 0 IS RETURNED. SUBROUTINE XRED USAGE CALL XRED(X,IX,IERROR) IF (IERROR.NE.0) RETURN DESCRIPTION IF RADIX**(-2L) .LE. (ABS(X),IX) .LE. RADIX**(2L) THEN XRED TRANSFORMS (X,IX) SO THAT IX=0. IF (X,IX) IS OUTSIDE THE ABOVE RANGE, THEN XRED TAKES NO ACTION. THIS SUBROUTINE IS USEFUL IF THE RESULTS OF EXTENDED-RANGE CALCULATIONS ARE TO BE USED IN SUBSEQUENT ORDINARY SINGLE-PRECISION CALCULATIONS.

REFERENCES
Smith, Olver and Lozier, Extended-Range Arithmetic and Normalized Legendre Polynomials, ACM Trans on Math Softw, v 7, n 1, March 1981, pp 93--105.

ROUTINES CALLED
I1MACH, XERMSG

COMMON BLOCKS
XBLK1, XBLK2, XBLK3

REVISION HISTORY (YYMMDD)
820712 DATE WRITTEN
881020 Revised to meet SLATEC CML recommendations. (DWL and JMS)
901019 Revisions to prologue. (DWL and WRB)
901106 Changed all specific intrinsics to generic. (WRB) Corrected order of sections in prologue and added TYPE section. (WRB) CALLs to XERROR changed to CALLs to XERMSG. (WRB)
920127 Revised PURPOSE section of prologue. (DWL)