Update of /project/oct/cvsroot/oct In directory clnet:/tmp/cvs-serv21392 Modified Files: qd-const.lisp qd-fun.lisp qd-io.lisp qd-rep.lisp qd.lisp Log Message: Add or cleanup some docstrings. --- /project/oct/cvsroot/oct/qd-const.lisp 2007/10/16 13:44:00 1.20 +++ /project/oct/cvsroot/oct/qd-const.lisp 2008/07/16 21:02:07 1.21 @@ -26,10 +26,12 @@ (in-package #:octi) (defconstant +qd-zero+ - (make-qd-d 0d0)) + (make-qd-d 0d0) + "%QUAD-DOUBLE representation of 0") (defconstant +qd-one+ - (make-qd-d 1d0)) + (make-qd-d 1d0) + "%QUAD-DOUBLE representation of 1") ;; The bits of 2/pi. Scale these bits by 2^(-1584) and you'll get ;; 2/pi. These are used for accurate argument reduction for the trig @@ -46,7 +48,8 @@ (scale-float (float -8753721960665020 1.0d0) -161) (scale-float (float 5857755168774013 1.0d0) -215) (scale-float (float 5380502254059520 1.0d0) -269)) - (%make-qd-d q0 q1 q2 q3))) + (%make-qd-d q0 q1 q2 q3)) + "%QUAD-DOUBLE representation of pi") ;; 6.2831853071795864769252867665590057683943387987502116419498891846156328125724L0 ;; #q6.2831853071795864769252867665590057683943387987502116419498891846q0 @@ -57,7 +60,8 @@ (scale-float (float -8753721960665020 1.0d0) -160) (scale-float (float 5857755168774013 1.0d0) -214) (scale-float (float 5380502254059520 1.0d0) -268)) - (%make-qd-d q0 q1 q2 q3))) + (%make-qd-d q0 q1 q2 q3)) + "%QUAD-DOUBLE representation of 2*pi") ;; 1.5707963267948966192313216916397514420985846996875529104874722961539082031431L0 ;; #q1.57079632679489661923132169163975144209858469968755291048747229615q0 @@ -68,7 +72,8 @@ (scale-float (float -8753721960665020 1.0d0) -162) (scale-float (float 5857755168774013 1.0d0) -216) (scale-float (float 5380502254059520 1.0d0) -270)) - (%make-qd-d q0 q1 q2 q3))) + (%make-qd-d q0 q1 q2 q3)) + "%QUAD-DOUBLE representation of pi/2") ;; 0.78539816339744830961566084581987572104929234984377645524373614807695410157155L0 ;; #q0.785398163397448309615660845819875721049292349843776455243736148076q0 @@ -79,7 +84,8 @@ (scale-float (float -8753721960665020 1.0d0) -163) (scale-float (float 5857755168774013 1.0d0) -217) (scale-float (float 5380502254059520 1.0d0) -271)) - (%make-qd-d q0 q1 q2 q3))) + (%make-qd-d q0 q1 q2 q3)) + "%QUAD-DOUBLE representation of pi/4") ;; 2.35619449019234492884698253745962716314787704953132936573120844423086230471467L0 ;; #q2.35619449019234492884698253745962716314787704953132936573120844423q0 @@ -90,7 +96,8 @@ (scale-float (float 5724553519491610 1.0d0) -160) (scale-float (float -6810541066450737 1.0d0) -214) (scale-float (float -7491566988951552 1.0d0) -273)) - (%make-qd-d q0 q1 q2 q3))) + (%make-qd-d q0 q1 q2 q3)) + "%QUAD-DOUBLE representation of 3*pi/4") ;; 0.00306796157577128245943617517898388953534879824157725177829584432842560195926387L0 ;; #q0.00306796157577128245943617517898388953534879824157725177829584432842q0 @@ -125,7 +132,8 @@ (%make-qd-d (scale-float (float 6243314768165359 1.0d0) -53) (scale-float (float 7525737178955839 1.0d0) -108) (scale-float (float 6673460182522164 1.0d0) -163) - (scale-float (float -7545482916914641 1.0d0) -217))) + (scale-float (float -7545482916914641 1.0d0) -217)) + "%QUAD-DOUBLE representation of log(2) (natural log)") ;; The rest of log(2) such that (+ +qd-log2+ +qd-log2-extra+) is ;; log(2) to twice the precision of a quad-double. --- /project/oct/cvsroot/oct/qd-fun.lisp 2007/11/28 20:00:28 1.92 +++ /project/oct/cvsroot/oct/qd-fun.lisp 2008/07/16 21:02:07 1.93 @@ -81,7 +81,7 @@ (scale-float-qd (mul-qd r new-a) (ash k -1))))) (defun sqrt-qd (a) - "Square root of the (non-negative) quad-float" + "Return the square root of the (non-negative) %QUAD-DOUBLE number A" (declare (type %quad-double a) (optimize (speed 3) (space 0))) ;; Perform the following Newton iteration: @@ -130,7 +130,8 @@ (- k)))) (defun hypot-qd (x y) - "sqrt(x^2+y^2) computed carefully without unnecessary overflow" + "sqrt(x^2+y^2) computed carefully without unnecessary overflow for +the %QUAD-DOUBLE numbers X and Y" (multiple-value-bind (abs^2 rho) (hypot-aux-qd x y) (scale-float-qd (sqrt-qd abs^2) rho))) @@ -168,7 +169,7 @@ (make-qd-d s0 s1 s2 s3)))) (defun ffloor-qd (a) - "The floor of A, returned as a quad-float" + "The floor of the %QUAD-DOUBLE A, returned as a %QUAD-DOUBLE number" (let ((x0 (ffloor (qd-0 a))) (x1 0d0) (x2 0d0) @@ -254,7 +255,8 @@ (mul-qd d (add-qd-d d 2d0)))))) (defun expm1-qd (a) - "exp(a) - 1, done accurately" + "Return exp(a) - 1 for the %QUAD-DOUBLE number A. This is more + accurate than just computing exp(a) - 1 directly." (declare (type %quad-double a)) (when (float-infinity-p (qd-0 a)) @@ -265,7 +267,7 @@ (expm1-qd/duplication a)) (defun exp-qd (a) - "exp(a)" + "Return the expnential of the %QUAD-DOUBLE number A" (declare (type %quad-double a)) ;; Should we try to be more accurate than just 709? (when (< (qd-0 a) (log least-positive-normalized-double-float)) @@ -348,8 +350,8 @@ (mul-qd-d sum 2d0))))) (defun log1p-qd (x) - "log1p(x) = log(1+x), done more accurately than just evaluating - log(1+x)" + "Return log1p(x) = log(1+x), done more accurately than just evaluating + log(1+x). X is a non-negative %QUAD-DOUBLE number" (declare (type %quad-double x)) (when (float-infinity-p (qd-0 x)) @@ -357,7 +359,7 @@ (log1p-qd/duplication x)) (defun log-qd (a) - "Log(a)" + "Return the (natural) log of the non-negative %QUAD-DOUBLE number A" (declare (type %quad-double a)) (cond ((onep-qd a) +qd-zero+) @@ -499,7 +501,7 @@ (neg-qd s))))))))))) (defun cos-qd (a) - "Cos(a)" + "Return the cosine of the %QUAD-DOUBLE number A" ;; Just like sin-qd, but for cos. (declare (type %quad-double a)) ;; To compute sin(x), choose integers a, b so that @@ -586,6 +588,8 @@ ;; Compute sin and cos of a (defun sincos-qd (a) + "Return the sine of the %QUAD-DOUBLE number A. The second returned value +is the cosine of A" (declare (type %quad-double a)) (when (zerop-qd a) (return-from sincos-qd @@ -784,7 +788,7 @@ (defun sin-qd (a) - "Sin(a)" + "Return the sine of the %QUAD-DOUBLE number A" (declare (type %quad-double a)) ;; To compute sin(x), choose integers a, b so that ;; @@ -861,7 +865,7 @@ (neg-qd c))))))))) (defun cos-qd (a) - "Cos(a)" + "Return the cosine of the %QUAD-DOUBLE number A" ;; Just like sin-qd, but for cos. (declare (type %quad-double a)) ;; To compute sin(x), choose integers a, b so that @@ -1100,18 +1104,18 @@ (atan2-qd/newton y x)) (defun atan-qd (y) - "Atan4b*(y)" + "Return the arc tangent of the %QUAD-DOUBLE number Y" (declare (type %quad-double y)) (atan-qd/newton y)) (defun asin-qd (a) - "Asin(a)" + "Return the arc sine of the %QUAD-DOUBLE number A" (declare (type %quad-double a)) (atan2-qd a (sqrt-qd (sub-d-qd 1d0 (sqr-qd a))))) (defun acos-qd (a) - "Acos(a)" + "Return the arc cosine of the %QUAD-DOUBLE number A" (declare (type %quad-double a)) (atan2-qd (sqrt-qd (sub-d-qd 1d0 (sqr-qd a))) @@ -1128,7 +1132,7 @@ (div-qd s c))) (defun tan-qd (r) - "Tan(r)" + "Return the tangent of the %QUAD-DOUBLE number A" (declare (type %quad-double r)) (if (zerop-qd r) r @@ -1136,7 +1140,7 @@  (defun sinh-qd (a) - "Sinh(a)" + "Return the hyperbolic sine of the %QUAD-DOUBLE number A" (declare (type %quad-double a)) ;; Hart et al. suggests sinh(x) = 1/2*(D(x) + D(x)/(D(x)+1)) ;; where D(x) = exp(x) - 1. This helps for x near 0. @@ -1153,7 +1157,7 @@ -1))))) (defun cosh-qd (a) - "Cosh(a)" + "Return the hyperbolic cosine of the %QUAD-DOUBLE number A" (declare (type %quad-double a)) ;; cosh(x) = 1/2*(exp(x)+exp(-x)) (let ((e (exp-qd a))) @@ -1163,7 +1167,7 @@ -1))) (defun tanh-qd (a) - "Tanh(a)" + "Return the hyperbolic tangent of the %QUAD-DOUBLE number A" (declare (type %quad-double a)) ;; Hart et al. suggests tanh(x) = D(2*x)/(2+D(2*x)) (cond ((zerop (qd-0 a)) @@ -1231,7 +1235,7 @@ (log1p-qd (sqrt-qd (add-qd-d (sqr-qd 1/a) 1d0)))))))) (defun asinh-qd (a) - "Asinh(a)" + "Return the inverse hyperbolic sine of the %QUAD-DOUBLE number A" (declare (type %quad-double a)) ;; asinh(x) = log(x + sqrt(1+x^2)) ;; @@ -1266,7 +1270,7 @@ (log1p-qd (sqrt-qd (add-qd-d (sqr-qd 1/a) 1d0))))))))) (defun acosh-qd (a) - "Acosh(a)" + "Return the inverse hyperbolic cosine of the %QUAD-DOUBLE number A" (declare (type %quad-double a)) ;; acosh(x) = log(x + sqrt(x^2-1)) #+nil @@ -1302,7 +1306,7 @@ (sqrt-qd (add-d-qd 1d0 1/a))))))))) (defun atanh-qd (a) - "Atanh(a)" + "Return the inverse hyperbolic tangent of the %QUAD-DOUBLE number A" (declare (type %quad-double a)) ;; atanh(x) = 1/2*log((1+x)/(1-x)) ;; = 1/2*log(1+(2*x)/(1-x)) @@ -1322,7 +1326,7 @@ (defun random-qd (&optional (state *random-state*)) - "Generate a quad-double random number in the range [0,1)" + "Generate a %QUAD-DOUBLE random number in the range [0,1)" (declare (optimize (speed 3))) ;; Strategy: Generate 31 bits at a time, shift the bits and repeat 7 times. (let* ((r +qd-zero+) --- /project/oct/cvsroot/oct/qd-io.lisp 2007/10/16 17:05:13 1.21 +++ /project/oct/cvsroot/oct/qd-io.lisp 2008/07/16 21:02:07 1.22 @@ -385,6 +385,7 @@ ;; convert bignums to qd. This supports converting rationals to qd ;; too. (defun rational-to-qd (rat) + "Convert a rational number RAT to a %QUAD-DOUBLE number" (declare (rational rat)) (let* ((p (coerce rat 'double-float)) (ans (make-qd-d p)) @@ -408,6 +409,9 @@ ;; This seems to work, but really needs to be rewritten! (defun read-qd (stream) + "Read a %QUAD-DOUBLE number from the stream STREAM. The format of the number +should be like a float, but with extra significant digits allowed. An exponent +marker of Q is allowed." (labels ((read-digits (s) ;; Read a sequence of digits and return the decimal ;; value, the character that terminated the sequence, and --- /project/oct/cvsroot/oct/qd-rep.lisp 2007/11/28 20:00:28 1.13 +++ /project/oct/cvsroot/oct/qd-rep.lisp 2008/07/16 21:02:07 1.14 @@ -55,18 +55,23 @@ ;; quad-double. QD-0 is the most significant part and QD-3 is the ;; least. (defun qd-0 (q) + "Return the most significant double-float in the %QUAD-DOUBLE number Q" (declare (type %quad-double q) (optimize (speed 3))) (kernel:double-double-hi (realpart q))) (defun qd-1 (q) + "Return the second most significant double-float in the %QUAD-DOUBLE number Q" (declare (type %quad-double q) (optimize (speed 3))) (kernel:double-double-lo (realpart q))) (defun qd-2 (q) + "Return the third most significant double-float in the %QUAD-DOUBLE number Q" (declare (type %quad-double q) (optimize (speed 3))) (kernel:double-double-hi (imagpart q))) (defun qd-3 (q) + "Return the fourth most significant (least significant) double-float in the + %QUAD-DOUBLE number Q" (declare (type %quad-double q) (optimize (speed 3))) (kernel:double-double-lo (imagpart q))) --- /project/oct/cvsroot/oct/qd.lisp 2008/02/11 17:04:13 1.65 +++ /project/oct/cvsroot/oct/qd.lisp 2008/07/16 21:02:07 1.66 @@ -307,6 +307,8 @@ ;; Quad-double + double (defun add-qd-d (a b &optional (target #+oct-array (%make-qd-d 0d0 0d0 0d0 0d0))) + "Add the %QUAD-DOUBLE A and the DOUBLE-FLOAT B, returning a %QUAD-DOUBLE. +If TARGET is given, TARGET is destructively modified to contain the result." (add-qd-d-t a b target)) (defun add-qd-d-t (a b target) @@ -337,6 +339,7 @@ (%store-qd-d target r0 r1 r2 r3))))) (defun add-d-qd (a b &optional (target #+oct-array (%make-qd-d 0d0 0d0 0d0 0d0))) + "Add the DOUBLE-FLOAT A and the %QUAD-DOUBLE B, returning a %QUAD-DOUBLE" (declare (double-float a) (type %quad-double b) (optimize (speed 3)) @@ -815,6 +818,8 @@ (renorm-5 p0 p1 s0 t0 t1)))))))))))))))))))) (defun sqr-qd (a &optional (target #+oct-array (%make-qd-d 0d0 0d0 0d0 0d0))) + "Return the square of the %QUAD-DOUBLE number A. If TARGET is also given, +it is destructively modified with the result." (sqr-qd-t a target)) (defun sqr-qd-t (a target) @@ -867,6 +872,8 @@ (defun div-qd (a b &optional (target #+oct-array (%make-qd-d 0d0 0d0 0d0 0d0))) + "Return the quotient of the two %QUAD-DOUBLE numbers A and B. +If TARGET is given, it destrutively modified with the result." (div-qd-t a b target)) #+nil @@ -1036,6 +1043,7 @@ (declaim (ext:end-block)) (defun abs-qd (a) + "Absolute value of the %QUAD-DOUBLE A" (declare (type %quad-double a)) (if (minusp (float-sign (qd-0 a))) (neg-qd a) @@ -1288,6 +1296,7 @@ (cl:* (qd-3 qd) scale)))) (defun scale-float-qd (qd k) + "Scale the %QUAD-DOUBLE number QD by 2^K. Just like SCALE-FLOAT" (declare (type %quad-double qd) (type (integer -2000 2000) k) (optimize (speed 3) (space 0)))