Professional Documents
Culture Documents
Donald E. Amos
Prepared by
Sandia National Laboratories
Albuquerque, New Mexico 87185 and Livermore, California 94550
for the United States Department of Energy
under Contract DE-AC04-76DP00789
Issued by Sandia National Laboratories, operated for the United States
Department of Energy by Sandia Corporation.
NOTICE: This report was prepared as an account of work sponsored by an
agency of the United States Government. Neither the United States Govern-
ment nor any agency thereof, nor any of their employees, nor any of their
contractors, subcontractors, or their employees, makes any warranty, express
or implied, or assumes any legal liability or responsibility for the accuracy,
completeness, or usefulness of any information, apparatus, product, or pro-
cess disclosed, or represents that its use would not infringe privately owned
rights. Reference herein to any specific commercial product, process, or
service by trade name, trademark, manufacturer, or otherwise, does not
necessarily constitute or imply its endorsement, recommendation, or favoring
by the United States Government, any agency thereof or any of their
contractors or subcontractors. The views and opinions expressed herein do
not necessarily state or reflect those of the United States Government, any
agency thereof or any of their contractors or subcontractors.
Donald E. Amos
Numerical Mathematics Division 1642
1
1. Introduction
2
v a l u e s computed from t h e package. These d r i v e r s a r e p r o v i d e d t o g i v e
first-time u s e r s c o n f i d e n c e t h a t t h e package h a s been i n s t a l l e d prop-
erly. A l l r o u t i n e s , except t h e Airy f u n c t i o n r o u t i n e s and t h e q u i c k
check d r i v e r s , c a n r e t u r n N member s e q u e n c e s f o r o r d e r s v , v + l , . ..,v+N-1.
The package a l s o a l l o w s f o r e x p o n e n t i a l s c a l i n g t o i n c r e a s e t h e argument
range of each function. A l i s t o f lower l e v e l r o u t i n e s and t h e i r pur-
p o s e is shown i n S e c t i o n 8.
S i n c e t h e r e i s no s t a n d a r d t y p e DOUBLE PRECISION COMPLEX, t h e
d o u b l e p r e c i s i o n r o u t i n e s c a r r y complex numbers a s o r d e r e d p a i r s .
S e c t i o n 8 a l s o l i s t s t h e common m a t h e m a t i c a l f u n c t i o n s n e e d e d t o
m a n i p u l a t e d o u b l e p r e c i s i o n o r d e r e d p a i r s i n c a l l i n g programs.
T h e p a c k a g e was w r i t t e n a c c o r d i n g t o FORTRAN 66 s t a n d a r d s a n d
p a s s e d t h e PFORT a n a l y z e r . Except p o s s i b l y f o r h o l l e r i t h t y p e s , w h i c h
o c c u r o n l y i n e r r o r m e s s a g e s f r o m c a l l s t o SUBROUTINE X E R R O R , t h e
package s h o u l d c o m p i l e on many FORTRAN 77 c o m p i l e r s .
The s e c t i o n s t o f o l l o w d e t a i l some o f t h e more i m p o r t a n t
c o n s i d e r a t i o n s f o r implementation of b a s i c formulae.
--2O l ? vL(c) v
2. E s t i m a t i o n o f Magnitudes of I v ( z ) and K . . ( z ) , R e ( z ) 2 0
v
m u s t b e s a t i s f i e d i n o r d e r t o p r o c e e d , w h e r e ELIM i s t h e -------
package
exponential overflow o r underflow l i m i t ,
e-
= I l a r g e s t ( p o s i t i v e ) package number
s m a l l e s t ( p o s i t i v e ) package number.
and
-
+iA V / 2 +iT / 2
I (z>
V
= e Jv(ze- 1
-3A < larg zI 5 571
where
(2.2)
5
Here 11, 12, S 1 and S a r e sums i n r e c i p r o c a l powers of v. A t t h i s
2
p o i n t , we a r e i n t e r e s t e d i n o n l y t h e l e a d i n g terms a n d we s i m p l i f y t o
obtain
(2.3)
u s i ng
6
remains on s c a l e . However, when s e q u e n c e s o f K f u n c t i o n s a r e n e e d e d ,
t h e r e c u r r e n c e is s t a r t e d w i t h K
V
and K
v+ 1
, -1/2 S v < 1 / 2 , and
T h u s , K V + l c a n o v e r f l o w when I z I i s s m a l l s i n c e v + 1 can b e a s
much as 3/2. T h i s t e s t is made on ( v + 1 ) l l n ( 2 / z ) I i n CBESH a n d CBESK
2
when a p p r o p r i a t e . I n r a n g e s where IzI is l a r g e (1.1 > m a x ( R L ( E ) , F ) ) ,
V
t h e e x p a n s i o n f o r z i. (0 is a p p l i e d f o r I ( 2 ) . F o r K ( z > i n I z I > 2
V V
1 1
and - - I v <
2
-2'
t h e l e a d i n g terms of t h e Miller a l g o r i t h m is a s y m p t o t i -
c a l l y c o r r e c t ( F i g u r e s 1 and 2 ) and one has
or
7
3. S c a l i n g Near Underflow and Overflow L i m i t s
-1 4
= 10 (.99999 x 10-276 + 1.00001 x 10-276i)
-290 -290i
= .99999 x 10 + 1.00001 x 10
Thus, c o u l d be r e p l a c e d by a n y t h i n g smaller a n d s t i l l o b t a i n
answers a c c u r a t e t o w i t h i n u n i t round o f f .
T h i s example shows t h e c a s e where t h e r e a l a n d i m a g i n a r y p a r t s
remain on s c a l e . However, c o n s i d e r t h e f i n a l s c a l i n g o p e r a t i o n
8
l a r g e r component a t l e a s t one p r e c i s i o n = l/TOL l a r g e r than t h e smaller
component. T h i s w i l l g i v e a m a g n i t u d e w i t h r e l a t i v e a c c u r a c y and a
phase a n g l e w i t h a b s o l u t e a c c u r a c y . These r e q u i r e m e n t s a r e c o n s i s t e n t
w i t h what i s o b t a i n a b l e w i t h complex a r i t h m e t i c i n g e n e r a l . That i s ,
r e l a t i v e a c c u r a c y i n t h e p h a s e a n g l e i s n o t a l w a y s p o s s i b l e when o n e
component d o m i n a t e s b e c a u s e of s u b t r a c t i o n s i n a complex m u l t i p l y .
These underflow t e s t s on components a r e made i n CUCHK b e f o r e t h e f i n a l
s c a l i n g by TOL i s done. CUCHK r e t u r n s a n o n - z e r o e r r o r f l a g on an
underflow which i s p r o c e s s e d by t h e c a l l i n g r o u t i n e t o r e t u r n a z e r o
value f o r t h e function.
For o v e r f l o w , t h e s e problems are m i t i g a t e d somewhat b e c a u s e o f t h e
inequalities
z = x + i y
9
4. Analytic Continuation of K ( z ) , Re(z) > 0
V
The a n a l y t i c c o n t i n u a t i o n o f K ( z ) from t h e r i g h t t o t h e l e f t h a l f
V
p l a n e is c a r r i e d o u t by t h e formula
- -
K (ze+
- ia = e+ i r v K ( z ) + iaI (z) , Re ( z ) 2 0 (4.1 1
V V V
-
e -Z
K (ze-
+ia
) = e
+ i a v e-2z z
{e K V ( z ) }
-+ ire
-iy -x
{e I ( z ) ) (4.2)
V V
5. Avoiding R e c u r s i v e Calls
The a n a l y t i c c o n t i n u a t i o n o f I ( z ) from t h e r i g h t t o t h e l e f t h a l f
V
z p l a n e is c a r r i e d o u t by t h e formula
10
Re ( z ) 2 0 (5.1 1
I n c l u d e d i n t h e p a c k a g e are f u n c t i o n s u b r o u t i n e s which d e f i n e t h e
machine environment i n which t h e package is t o o p e r a t e [ 5 ] . This helps
make t h e package p o r t a b l e by r e l e g a t i n g a l l machine d e p e n d e n t parameters
t o these f u n c t i o n s u b r o u t i n e s . These r o u t i n e s [ 5 ] a r e c a l l e d I l M A C H ,
RlMACH and D l M A C H .
IlMACH defines integer constants associated w i t h t h e environment.
F o r e x a m p l e , s t a n d a r d i n p u t , o u t p u t , punch and e r r o r message u n i t s a r e
11
d e f i n e d by I l M A C H ( I 1 , I = 1, 4. The number o f b i t s p e r s t o r a g e u n i t
( w o r d ) and number o f a l p h a - n u m e r i c c h a r a c t e r s i n a s t o r a g e u n i t are
d e f i n e d i n IlMACH(5) a n d IlMACH(6). The c o n s t a n t s a s s o c i a t e d w i t h
i n t e g e r , s i n g l e p r e c i s i o n and d o u b l e p r e c i s i o n a r i t h m e t i c a r e d e f i n e d i n
IlMACH(7) t h r o u g h IlMACH(16). These I n c l u d e t h e base o f t h e a r i t h m e t i c
B , maximum and minimum e x p o n e n t s and t h e number o f base B d i g i t s .
RIMACH(I), I = 1 , 5 r e t u r n s t h e smallest and l a r g e s t ( p o s i t i v e )
f l o a t i n g ( s i n g l e p r e c i s i o n ) numbers, t h e smallest r e l a t i v e s p a c i n g , t h e
l a r g e s t r e l a t i v e s p a c i n g ( u n i t round o f f ) and l o g base 10 o f t h e s i n g l e
p r e c i s i o n arithmetic base. Similarly for DlMACH(I), I = 1,5 f o r double
p r e c i s i o n arithmetic.
To m a k e t h e u s a g e e a s i e r , these q u a n t i t i e s are d e f i n e d on comment
cards f o r a wide v a r i e t y of s y s t e m s . To d e f i n e o n e o f t h e s e s y s t e m s ,
one has o n l y t o r e p l a c e CIS i n column 1 by s p a c e s t o make a p a r t i c u l a r
s e t of FORTRAN s t a t e m e n t s a c t i v e .
I n t h e m a i n r o u t i n e s , which a r e c a l l e d by t h e u s e r , package
p a r a m e t e r s TOL, ELIM, and ALIM are computed from m a c h i n e c o n s t a n t s a n d
p a s s e d t o lower l e v e l r o u t i n e s . These package p a r a m e t e r s are s l i g h t l y
d i f f e r e n t from t h o s e which c o u l d b e computed d i r e c t l y from I I M A C H ,
RIMACH and DlMACH b e c a u s e we w i s h t o impose f u r t h e r l i m i t a t i o n s . Thus,
d e f i n e s t h e p a c k a g e u n i t r o u n d o f f l i m i t e d t o 18 d i g i t s b e c a u s e
c o n s t a n t s are s t o r e d t o o n l y 18 d i g i t s ( U N I V A C d o u b l e p r e c i s i o n . ) The
statements
K = MINO(IABS(IlMACH(12)), I A B S ( I l M A C H ( 1 3 ) )
ELIM = 2.303E0 * (FLOAT(K) * R l M A C H ( 5 ) - 3.OEO)
AA = 2.303E0 * RlMACH(5) * FLOAT(I1MACH(11)-1)
A L I M = ELIM + A M A X l ( - A A , -41.45EO)
d e f i n e t h e package e x p o n e n t i a l o v e r f l o w o r u n d e r f l o w l i m i t E L I M
c u s h i o n e d b y l o 3 t o a l l o w f o r some i m p r e c i s e n e s s i n tests u s i n g f i r s t
term a p p r o x i m a t i o n s . Also, one is n o t always s u r e t h a t t h e ALOG ( o r
12
D L O G ) f u n c t i o n w o u l d p e r f o r m c o r r e c t l y on t h e l a r g e s t o r s m a l l e s t
machine numbers. Thus,
may be d e s i r a b l e , b u t n o t p r u d e n t . ALIM i s a n e a r - u n d e r f l o w o r n e a r -
o v e r f l o w q u a n t i t y which t r i g g e r s a non-unit s c a l i n g o p t i o n d e s c r i b e d i n
Section 3. More p r e c i s e l y , these c o m p u t a t i o n s e x p r e s s t h e r e l a t i o n s
-ALIM -ELIM,TOL
e-ELIM = B -K - 1 03 9 e = e
13
TABLE I
IFLAG v a l u e ( d e f i n e d by c a l l s t o XSETFO o r by
l i b r a r i a n as d e f a u l t )
LEVEL 0 f1 f2
N o t e : P = p r i n t e r r o r message; P-once = p r i n t f i r s t o c c u r r e n c e o f e r r o r
message; R = RETURN from X E R R O R O ; A = a b o r t ; ( T ) = trace-back i f IFLAG
is p o s i t i v e and s u b r o u t i n e FDUMPO is coded f o r a trace-back.
14
summary. ( T h e d e f a u l t p a r a m e t e r IPARAM(2) = 2 is c o n t a i n e d i n a DATA
statement i n function JIISAVEO.)
S i m i l a r u s a g e a p p l i e s t o s u b r o u t i n e s X G E T U N ( L U N ) and XSETUN(LUN)
where LUN is t h e u n i t number on which e r r o r messages are t o a p p e a r . The
d e f a u l t is LUN = IlMACH(41, t h e s t a n d a r d e r r o r message u n i t d e f i n e d by
t h e machine i n t e g e r f u n c t i o n I l M A C H O d e s c r i b e d above. XGETUA(IUNIT, N )
a n d XSETUA(IUNIT,N) s e r v e t h e same purpose when e r r o r messages are t o
a p p e a r on m u l t i p l e u n i t s I U N I T ( l ) , ..., I U N I T ( N ) , N 2 5.
I n an i n s t i t u t i o n a l s e t t i n g t h e package can be t a i l o r e d t o t h e
s y s t e m by the l i b r a r i a n t o p r o v i d e trace back i n f o r m a t i o n o r a p p r o p r i a t e
d i a g n o s t i c i n f o r m a t i o n f o r t h e u s e r from FDUMPO o r X E R A B T O .
The m a i n c o n s i d e r a t i o n i n a l l r o u t i n e s is t o a c h i e v e t h e a c c u r a c y
s p e c i f i e d by TOL ( u n i t round o f f . ) T h i s is n o t always p o s s i b l e b e c a u s e
of a r g u m e n t r e d u c t i o n i n e l e m e n t a r y f u n c t i o n s when v a r i a b l e s a r e l a r g e .
However, we can program t o e n s u r e t h a t u n n e c e s s a r y l o s s e s d o n o t o c c u r
and maximum u s e is made of t h e f u l l exponent r a n g e of t h e machine.
Asymptotic expansions r e q u i r e a v a r i a b l e t o b e l a r g e .
S p e c i f i c a l l y , v must be l a r g e t o a p p l y t h e uniform e x p a n s i o n s ( 2 . 1 ) and
(2.2). T h i s makes I ( z ) small when I z I is o n l y m o d e r a t e l y s m a l l e r t h a n
V
v. I n t h e case of t h e VAX, where u n i t round o f f is a p p r o x i m a t e l y 10-1 6
i n d o u b l e p r e c i s i o n arithmetic and t h e arithmetic r a n g e i s o n l y 1 0 +38
- ,
t h e lower bound on v f o r ( 2 . 1 ) and ( 2 . 2 ) , called FNUL, is a p p r o x i m a t e l y
88. I n t h i s case, I v ( z ) can underflow e a s i l y f o r v > FNUL. This
happens i n C B U N I on a c a l l from C B I N U . C B I N U s e t s a l l members of a
s e q u e n c e t o z e r o whose o r d e r s exceed FNUL a n d r e t u r n s t h e l a s t i n d e x ,
N L A S T , whose v a l u e was n o t s e t . A t t h i s p o i n t C U O I K g e t s a chance t o
examine t h e c o r r e s p o n d i n g o r d e r , vo + N L A S T - 1 , t o see whether o r n o t
( z ) is on s c a l e . If n o t , t h e n C U O I K s e t s more v a l u e s t o zero
l V O + ~ ~ ~ ~ ~ - i
u n t i l e i t h e r t h e sequence is e x h a u s t e d o r a member comes on scale. If a
member is deemed t o b e on s c a l e b y C U O I K , t h e n other r o u t i n e s g e t t o
compute i t . I n t h e c a s e v 5 FNUL, C U O I K a l s o g e t s a chance t o s e t
underflow v a l u e s b e f o r e any computation is a t t e m p t e d . The p o i n t here is
15
t h a t t h e small exponent r a n g e f o r c e s t h e u n d e r f l o w b o u n d a r y f o r I ( z )
V
(overflow boundary f o r K ( z ) ) t o b e superimposed o v e r f o r m u l a b o u n d a r i e s
V
t o e x c l u d e t h e u s e o f t h e u n i f o r m e x p a n s i o n s i n some r a n g e of z . A
s i m i l a r s i t u a t i o n can o c c u r i f a sequence f o r I
v+k
(z), k + N-1, ..., 0
2
c r o s s e s t h e boundary ( 1 2 1 / 2 ) 2 v + 1. The l a s t N Z members a r e s e t t o
z e r o i n C S E R I , t h e i n d e x i s m o d i f i e d t o N - N Z a n d t h e new ( s u b )
sequence is examined f o r underflow by c a l l s t o CUOIK o r C B U N I .
T h i s i l l u s t r a t e s t h a t underflow on a VAX may b e v e r y l i k e l y b e c a u s e
t h e o r d e r s v do n o t have t o b e v e r y l a r g e f o r t h i s t o h a p p e n . I t is
e s p e c i a l l y i m p o r t a n t t h a t t h e s c a l i n g d e s c r i b e d i n S e c t i o n 3 b e used t o
keep a s much of the exponent r a n g e a s p o s s i b l e ; o t h e r w i s e , t h e underflow
a n d o v e r f l o w l i m i t s ( i n d o u b l e p r e c i s i o n a r i t h m e t i c ) would have t o b e
modified by making t h e e f f e c t i v e exponent r a n g e ( w h e r e a c c u r a t e
+22.
r e s u l t s can be o b t a i n e d ) o n l y 10-
16
TABLE I1
GAMLN YES
CMLRI I ( z ) by Miller a l g o r i t h m n o r m a l i z e d by a NO
d r i e s , Re(z) 2 0
CASY I I ( z ) by a s y m p t o t i c e x p a n s i o n f o r z +. 00, NO
Rg(z) 2 0
CUNI1 I v ( z ) by ( 2 . 1 ) NO
CUNI 2 I v ( z ) by ( 2 . 2 ) NO
CACON A n a l y t i c c o n t i n u a t i o n of K ( z ) t o l e f t NO
V
half plane
CACAI A n a l y t i c c o n t i n u a t i o n of A i , A i ' t o NO
l e f t half plane
CUNIK Parameters f o r ( 2 . 1 ) f o r u s e i n C U N I l , NO
CUNKl, C U O I K
CUOIK S e t u n d e r f l o w o r o v e r f l o w i n d i c t a t o r s and NO
s e t underflow v a l u e s f o r I sequences
17
CUCHK 12ckz f o r component underflow when NO
m g n i t u d e 6 exp(-ALIM) = 1 . O E + 3 *
R l M A C H ( 1 )/TOL
CKSCL S c a l e d r e c u r r e n c e on u n d e r f l o w f o r CBKNU, NO
C U N K 1 , CUNK2
CSlS2 A d d i t i o n of I and K f u n c t i o n s f o r ( 4 . 2 ) NO
on KODE = 2
A d d i t i o n a l Double P r e c i s i o n R o u t i n e s
ZMLT z
1
* z2 = z3 YES
ZDIV z 1 / z 2 = z3 YES
9. Package Accuracy
18
10. Q u i c k Check R o u t i n e s
u s i n g t h e scaled v e r s i o n (KODE = 2)
-5 - 5 r1 21~i/3 r
e 2[e Ai(ze )I [e 2 A i 1 ( z ) l -
5 -l~i/6
e -'1-'2 e-21ri/3 Ce51Ai, ( z e 2lri 131 3 [e 2 A i 1 ( z ) I = -e
21T
because t h e scale f a c t o r s a r e n o t a n a l y t i c i n t h e w h o l e z p l a n e a n d
introduce a d i s c o n t i n u i t y along t h e l i n e 9 = n/3:
s i n c e 9 is i n t h e p r o p e r range f o r t h e p r i n c i p a l s q u a r e r o o t . Now,
w = re
i9 . e21ri/3 = re
i(0+2~/3)
I
- -71 21T
< ' + - - S T
3 3
19
and
A = r ei(e/2+a/3)
2a
since 8 + -
3
is i n a p r o p e r domain f o r t h e p r i n c i p a l s q u a r e r o o t . Thus,
-5, -5,
Therefore e = eo = 1 and no s c a l i n g is n e c e s s a r y .
I n t h i s case,
w = r ei ( e + 21~13) 2a
IT<^+- 5a
SF
2 ,3/2 e i ( e - 4 ~ 1 3 )e i ( e / 2 - 2a/3)
51 = 3
2 ,3/2 ,38i/2
= -
3 = c2
20
Thus, t h e s c a l i n g f a c t o r f o r u s e w i t h KODE = 2 i n t h e argument
range a / 3 < 8 5 a is
Zero of Y,
I n . [ 4 , p. 2201, t h e 4 t h z e r o of Y 4 ( z ) should b e
-3.4307435178
- + 1.3945703562i
where t h e e r r o r i n [ 4 ] is i n t h e f i r s t decimal p l a c e of t h e r e a l p a r t .
21
References
5. Fong, K . W . , J e f f e r s o n , T. H . , S u y e h i r o , T . , F o r m a l C o n v e n t i o n s o f
t h e SLATEC L i b r a r y , ACM SIGNUM Newsletter, Vol. 1 9 , No.1, J a n u a r y
1984, pp. 17-22.
22
Distribution :
1000 W. F. Brinkman
1241 J. P. Quintenz
1541 H. C. Hardee
1600 R. G. Clem
Attn: 1601 G. W. Kuswa .
1620 R. D. Andreas
1630 R. C. Maydew
1650 D. J. Rigali
1601 L. B. Dean
1640 G. J . Simmons
1641 R . J . Thompson
1642 L . F. Shampine
1642 D . E . Amos ( 3 5 )
1651 W. Williams
1651 J . S. Yu
2322 E . M. G u r r o l a
2322 D . J . R i l e y
2343 B. C. Brock
2552 R . D. Moyer
2644 T . E . Koontz
2646 W. H . Vandevender ( 5 )
2646 R . J . Hanson
6240 L . C. Bartel
6241 P . C. Lysne
6256 D . Engi
7553 M. Morris
7553 K . M. Damrau
7553 W. A . Johnson
8024 M. A . Pound
8235 T. H . J e f f e r s o n ( 5 )
8341 M. I . B a s k i s
3 1 4 1 C. M. O s t r a n d e r ( 5 )
3151 W. L . Garner ( 3 )
For DOE/TIC (Unlim. Release)
3154- .3 C. H. Dalin ( 2 8 )
For D O E / T I C
23