math docs

library/bootstrap/boot-stage1.factor

@@ -229,6 +229,12 @@ vectors words ;
         "/library/generic/slots.facts"
         "/library/generic/standard-combination.facts"
         "/library/generic/tuple.facts"
+        "/library/math/arc-trig-hyp.facts"
+        "/library/math/complex.facts"
+        "/library/math/constants.facts"
+        "/library/math/float.facts"
+        "/library/math/integer.facts"
+        "/library/math/math.facts"
         "/library/syntax/parse-stream.facts"
         "/library/syntax/parser.facts"
         "/library/syntax/parse-syntax.facts"

library/math/arc-trig-hyp.factor

@@ -3,12 +3,6 @@
 IN: math
 USING: kernel math math-internals ;
 
-! Inverse trigonometric functions:
-!    acos asec asin acosec atan acot
-
-! Inverse hyperbolic functions:
-!    acosh asech asinh acosech atanh acoth
-
 : acosh dup sq 1- sqrt + log ; inline
 : asech recip acosh ; inline
 : asinh dup sq 1+ sqrt + log ; inline

library/math/arc-trig-hyp.facts

@@ -0,0 +1,60 @@
+IN: help
+USING: math ;
+
+: $values-x/y { { "x" "a complex number" } { "y" "a complex number" } } $values ;
+
+HELP: acosh "( x -- y )"
+$values-x/y
+{ $description "Inverse hyperbolic cosine." } ;
+
+HELP: asech "( x -- y )"
+$values-x/y
+{ $description "Inverse hyperbolic secant." } ;
+
+HELP: asinh "( x -- y )"
+$values-x/y
+{ $description "Inverse hyperbolic sine." } ;
+
+HELP: asinh "( x -- y )"
+$values-x/y
+{ $description "Inverse hyperbolic sine." } ;
+
+HELP: acosech "( x -- y )"
+$values-x/y
+{ $description "Inverse hyperbolic cosecant." } ;
+
+HELP: atanh "( x -- y )"
+$values-x/y
+{ $description "Inverse hyperbolic tangent." } ;
+
+HELP: acoth "( x -- y )"
+$values-x/y
+{ $description "Inverse hyperbolic cotangent." } ;
+
+HELP: acosh "( x -- y )"
+$values-x/y
+{ $description "Inverse trigonometric cosine." } ;
+
+HELP: asech "( x -- y )"
+$values-x/y
+{ $description "Inverse trigonometric secant." } ;
+
+HELP: asinh "( x -- y )"
+$values-x/y
+{ $description "Inverse trigonometric sine." } ;
+
+HELP: asinh "( x -- y )"
+$values-x/y
+{ $description "Inverse trigonometric sine." } ;
+
+HELP: acosech "( x -- y )"
+$values-x/y
+{ $description "Inverse trigonometric cosecant." } ;
+
+HELP: atanh "( x -- y )"
+$values-x/y
+{ $description "Inverse trigonometric tangent." } ;
+
+HELP: acoth "( x -- y )"
+$values-x/y
+{ $description "Inverse trigonometric cotangent." } ;

library/math/complex.factor

@@ -4,8 +4,6 @@ IN: math-internals
 USING: errors generic kernel kernel-internals math ;
 
 : (rect>) ( xr xi -- x )
-    #! Does not perform a check that the arguments are reals.
-    #! Do not use in your own code.
     dup 0 number= [ drop ] [ <complex> ] if ; inline
 
 IN: math

library/math/complex.facts

@@ -0,0 +1,69 @@
+USING: help math math-internals ;
+
+HELP: complex f
+{ $description "The class of complex numbers with non-zero imaginary part." } ;
+
+HELP: real "( z -- x )"
+{ $values { "z" "a complex number" } { "x" "a real number" } }
+{ $description "Outputs the real part of a complex number. This acts as the identity on real numbers." }
+{ $notes "This word also acts as the class word for the class of real numbers, which is a disjoint union of rationals and floats." } ;
+
+HELP: imaginary "( z -- y )"
+{ $values { "z" "a complex number" } { "y" "a real number" } }
+{ $description "Outputs the imaginary part of a complex number. This outputs zero for real numbers." } ;
+
+HELP: (rect>) "( x y -- z )"
+{ $values { "x" "a real number" } { "y" "a real number" } { "z" "a complex number" } }
+{ $description "Creates a complex number from real and imaginary components." }
+{ $warning "This word does not check that the arguments are real numbers, which can have undefined consequences. Use the " { $link rect> } " word instead." } ;
+
+HELP: number f
+{ $description "The class of numbers." } ;
+
+HELP: rect> "( x y -- z )"
+{ $values { "x" "a real number" } { "y" "a real number" } { "z" "a complex number" } }
+{ $description "Creates a complex number from real and imaginary components." } ;
+
+HELP: >rect "( z -- x y )"
+{ $values { "z" "a complex number" } { "x" "a real number" } { "y" "a real number" } }
+{ $description "Extracts the real and imaginary components of a complex number." } ;
+
+HELP: conjugate "( z -- z* )"
+{ $values { "z" "a complex number" } { "z*" "a complex number" } }
+{ $description "Computes the complex conjugate by flipping the sign of the imaginary part of " { $snippet "z" } "." } ;
+
+HELP: arg "( z -- arg )"
+{ $values { "z" "a complex number" } { "arg" "a number in the interval " { $snippet "(-pi,pi]" } } }
+{ $description "Computes the complex argument." } ;
+
+HELP: >polar "( z -- abs arg )"
+{ $values { "z" "a complex number" } { "abs" "a non-negative real number" } { "arg" "a number in the interval " { $snippet "(-pi,pi]" } } }
+{ $description "Creates a complex number from an absolute value and argument (polar form)." } ;
+
+HELP: cis "( arg --- z )"
+{ $values { "arg" "a real number" } { "z" "a complex number on the unit circle" } }
+{ $description "Computes a point on the unit circle using Euler's formula for " { $snippet "exp(arg*i)" } "." }
+{ $see-also exp } ;
+
+HELP: polar> "( abs arg -- z )"
+{ $values { "z" "a complex number" } { "abs" "a non-negative real number" } { "arg" "a real number" } }
+{ $description "Converts an absolute value and argument (polar form) to a complex number." } ;
+
+HELP: quadrant "( z -- n )"
+{ $values { "z" "a complex number" } { "n" "0, 1, 2, or 3" } }
+{ $description "If the imaginary axis runs from bottom to top and the real axis runs from left to right, the quadrants of the complex plane run anti-clockwise starting from the positive real axis:" { $code "1|0" "---" "2|3" } } ;
+
+HELP: 2>rect "( x y -- xr xi yr yi )"
+{ $values { "x" "a complex number" } { "y" "a complex number" } { "xr" "real part of " { $snippet "x" } } { "xi" "imaginary part of " { $snippet "x" } } { "yr" "real part of " { $snippet "y" } } { "yi" "imaginary part of " { $snippet "y" } } }
+{ $description "Extracts real and imaginary components of two numbers at once." } ;
+
+HELP: complex/ "( x y -- r i m )"
+{ $values { "x" "a complex number" } { "y" "a complex number" } { "r" "a real number" } { "i" "a real number" } { "m" "a real number" } }
+{ $description
+    "Complex division kernel. If we use the notation from " { $link 2>rect } ", this word computes:"
+    { $code
+        "r = xr*yr+xi*yi"
+        "i = xi*yr-xr*yi"
+        "m = yr*yr+yi*yi"
+    }
+} ;

library/math/float.facts

@@ -0,0 +1,8 @@
+USING: help math ;
+
+HELP: float f
+{ $description "The class of double-precision floating point numbers." } ;
+
+HELP: >float "( x -- y )"
+{ $values { "x" "a real number" } { "y" "a float" } }
+{ $description "Converts a real to a float. This is the identity on floats, and performs a floating point division on rationals." } ;

library/math/integer.factor

@@ -17,10 +17,7 @@ UNION: integer fixnum bignum ;
         tuck /mod >r pick * swap >r swapd - r> r> (gcd)
     ] if ; inline
 
-: gcd ( x y -- a d )
-    #! Compute the greatest common divisor d and multiplier a
-    #! such that a*x=d mod y.
-    swap 0 1 2swap (gcd) abs ; foldable
+: gcd ( x y -- a d ) swap 0 1 2swap (gcd) abs ; foldable
 
 : (next-power-of-2) ( i n -- n )
     2dup >= [
@@ -29,8 +26,7 @@ UNION: integer fixnum bignum ;
         >r 1 shift r> (next-power-of-2)
     ] if ;
 
-: next-power-of-2 ( n -- n )
-    1 swap (next-power-of-2) ;
+: next-power-of-2 ( n -- n ) 1 swap (next-power-of-2) ;
 
 IN: math-internals
 
@@ -47,10 +43,7 @@ M: integer / ( x y -- x/y )
         2dup gcd nip tuck /i >r /i r> fraction>
     ] if ;
 
-M: fixnum number=
-    #! Fixnums are immediate values, so equality testing is
-    #! trivial.
-    eq? ;
+M: fixnum number= eq? ;
 
 M: fixnum < fixnum< ;
 M: fixnum <= fixnum<= ;

library/math/integer.facts

@@ -0,0 +1,39 @@
+USING: help math math-internals ;
+
+HELP: fixnum f
+{ $description "The class of fixnums, which are fixed-width integers small enough to fit in a machine cell. Because they are not heap-allocated, fixnums do not have object identity. Equality of tagged pointer bit patterns is actually " { $emphasis "value" } " equality for fixnums." } ;
+
+HELP: >fixnum "( x -- n )"
+{ $values { "x" "a real number" } { "n" "a fixnum" } }
+{ $description "Converts a real number to a fixnum, with a possible loss of precision and overflow." } ;
+
+HELP: bignum f
+{ $description "The class of bignums, which are heap-allocated arbitrary-precision integers." } ;
+
+HELP: >bignum "( x -- n )"
+{ $values { "x" "a real number" } { "n" "a bignum" } }
+{ $description "Converts a real number to a bignum, with a possible loss of precision." } ;
+
+HELP: integer f
+{ $description "The class of integers, which is a disjoint union of fixnums and bignums." } ;
+
+HELP: even? "( n -- ? )"
+{ $values { "n" "an integer" } { "?" "a boolean" } }
+{ $description "Tests if an integer is even." } ;
+
+HELP: odd? "( n -- ? )"
+{ $values { "n" "an integer" } { "?" "a boolean" } }
+{ $description "Tests if an integer is odd." } ;
+
+HELP: gcd "( x y -- a d )"
+{ $values { "x" "an integer" } { "y" "an integer" } { "a" "an integer" } { "d" "an integer" } }
+{ $description "Computes the positive greatest common divisor " { $snippet "d" } " of " { $snippet "x" } " and " { $snippet "y" } ", and another value " { $snippet "a" } " satisfying:" { $code "a*x = d mod y" } }
+{ $notes "If " { $snippet "d" } " is 1, then " { $snippet "a" } " is the inverse of " { $snippet "x" } " modulo " { $snippet "y" } "." } ;
+
+HELP: next-power-of-2 "( m -- n )"
+{ $values { "m" "a non-negative integer" } { "n" "an integer" } }
+{ $description "Outputs the smallest power of 2 greater than " { $snippet "m" } ". The output value is always at least 1." } ;
+
+HELP: fraction> "( a b -- a/b )"
+{ $values { "a" "an integer" } { "b" "a positive integer" } { "a/b" "a rational number" } }
+{ $description "Creates a new ratio, or outputs the numerator if the denominator is 1. This word does not reduce the fraction to lowest terms, and should not be called directly; use " { $link / } " instead." } ;

library/math/math.factor

@@ -1,5 +1,5 @@
-! Copyright (C) 2003, 2005 Slava Pestov.
-! See http://factor.sf.net/license.txt for BSD license.
+! Copyright (C) 2003, 2006 Slava Pestov.
+! See http://factorcode.org/license.txt for BSD license.
 IN: math
 USING: errors generic kernel math-internals ;
 
@@ -27,11 +27,11 @@ G: bitor  ( x y -- z ) math-combination ; foldable
 G: bitxor ( x y -- z ) math-combination ; foldable
 G: shift  ( x n -- y ) math-combination ; foldable
 
+GENERIC: bitnot ( n -- n ) foldable
+
 GENERIC: 1+ ( x -- x+1 ) foldable
 GENERIC: 1- ( x -- x-1 ) foldable
 
-GENERIC: bitnot ( n -- n ) foldable
-
 GENERIC: truncate ( n -- n ) foldable
 GENERIC: floor    ( n -- n ) foldable
 GENERIC: ceiling  ( n -- n ) foldable
@@ -39,10 +39,7 @@ GENERIC: ceiling  ( n -- n ) foldable
 : max ( x y -- z ) [ > ] 2keep ? ; inline
 : min ( x y -- z ) [ < ] 2keep ? ; inline
 
-: between? ( x min max -- ? )
-    #! Push if min <= x <= max. Handles case where min > max
-    #! by swapping them.
-    pick rot >= [ <= ] [ 2drop f ] if ; inline
+: between? ( x min max -- ? ) pick >= >r >= r> and ; inline
 
 : sq dup * ; inline
 
@@ -51,17 +48,17 @@ GENERIC: ceiling  ( n -- n ) foldable
 
 : rem ( x y -- x%y )
     #! Like modulus, but always gives a positive result.
-    [ mod ] keep  over 0 < [ + ] [ drop ] if ; inline
+    [ [ mod ] keep + ] keep mod ; inline
 
 : sgn ( n -- -1/0/1 )
     #! Push the sign of a real number.
-    dup 0 = [ drop 0 ] [ 1 < -1 1 ? ] if ; foldable
+    dup 0 < -1 0 ? swap 0 > 1 0 ? bitor ; foldable
 
 GENERIC: abs ( z -- |z| ) foldable
 GENERIC: absq ( n -- |n|^2 ) foldable
 
 : align ( offset width -- offset )
-    2dup mod dup 0 number= [ 2drop ] [ - + ] if ; inline
+    1- [ + ] keep bitnot bitand ; inline
 
 : (repeat) ( i n quot -- )
     pick pick >=

library/math/math.facts

@@ -0,0 +1,143 @@
+USING: help kernel math ;
+
+HELP: number= "( x y -- ? )"
+{ $values { "x" "a number" } { "y" "a number" } { "?" "a boolean" } }
+{ $description "Tests if two numbers have the same numerical value." }
+{ $notes "Do not call this word directly. Calling " { $link = } " has the same effect and is more concise." } ;
+
+HELP: < "( x y -- ? )"
+{ $values { "x" "a real number" } { "y" "a real number" } { "?" "a boolean" } }
+{ $description "Tests if " { $snippet "x" } " is less than " { $snippet "y" } "." } ;
+
+HELP: <= "( x y -- ? )"
+{ $values { "x" "a real number" } { "y" "a real number" } { "?" "a boolean" } }
+{ $description "Tests if " { $snippet "x" } " is less than or equal to " { $snippet "y" } "." } ;
+
+HELP: > "( x y -- ? )"
+{ $values { "x" "a real number" } { "y" "a real number" } { "?" "a boolean" } }
+{ $description "Tests if " { $snippet "x" } " is greater than " { $snippet "y" } "." } ;
+
+HELP: >= "( x y -- ? )"
+{ $values { "x" "a real number" } { "y" "a real number" } { "?" "a boolean" } }
+{ $description "Tests if " { $snippet "x" } " is greater than or equal to " { $snippet "y" } "." } ;
+
+HELP: + "( x y -- z )"
+{ $values { "x" "a number" } { "y" "a number" } { "z" "a number" } }
+{ $description
+    "Adds two numbers."
+    { $list
+        "Addition of fixnums may overflow and convert the result to a bignum."
+        "Addition of bignums always yields a bignum."
+        "Addition of floats always yields a float."
+        "Addition of ratios and complex numbers proceeds using the relevant mathematical rules."
+    }
+} ;
+
+HELP: - "( x y -- z )"
+{ $values { "x" "a number" } { "y" "a number" } { "z" "a number" } }
+{ $description
+    "Subtracts " { $link "y" } " from " { $snippet "x" } "."
+    { $list
+        "Subtraction of fixnums may overflow and convert the result to a bignum."
+        "Subtraction of bignums always yields a bignum."
+        "Subtraction of floats always yields a float."
+        "Subtraction of ratios and complex numbers proceeds using the relevant mathematical rules."
+    }
+} ;
+
+HELP: * "( x y -- z )"
+{ $values { "x" "a number" } { "y" "a number" } { "z" "a number" } }
+{ $description
+    "Multiplies two numbers."
+    { $list
+        "Multiplication of fixnums may overflow and convert the result to a bignum."
+        "Multiplication of bignums always yields a bignum."
+        "Multiplication of floats always yields a float."
+        "Multiplication of ratios and complex numbers proceeds using the relevant mathematical rules."
+    }
+} ;
+
+HELP: / "( x y -- z )"
+{ $values { "x" "a number" } { "y" "a number" } { "z" "a number" } }
+{ $description
+    "Divides " { $snippet "x" } " by " { $snippet "y" } ", retaining as much precision as possible."
+    { $list
+        "Division of fixnums may yield a ratio, or overflow and yield a bignum."
+        "Division of bignums may yield a ratio."
+        "Division of floats always yields a float."
+        "Division of ratios and complex numbers proceeds using the relevant mathematical rules."
+    }
+} ;
+
+HELP: /i "( x y -- z )"
+{ $values { "x" "a real number" } { "y" "a real number" } { "z" "a real number" } }
+{ $description
+    "Divides " { $snippet "x" } " by " { $snippet "y" } ", truncating the result to an integer."
+    { $list
+        "Integer division of fixnums may overflow and yield a bignum."
+        "Integer division of bignums always yields a bignum."
+        "Integer division of floats always yields a float."
+        "Integer division of ratios and complex numbers proceeds using the relevant mathematical rules."
+    }
+} ;
+
+HELP: /f "( x y -- z )"
+{ $values { "x" "a real number" } { "y" "a real number" } { "z" "a real number" } }
+{ $description
+    "Divides " { $snippet "x" } " by " { $snippet "y" } ", representing the result as a floating point number."
+    { $list 
+        "Integer division of fixnums may overflow and yield a bignum."
+        "Integer division of bignums always yields a bignum."            
+        "Integer division of floats always yields a float."
+        "Integer division of ratios and complex numbers proceeds using the relevant mathematical rules."
+    }
+} ;
+
+HELP: mod "( x y -- z )"
+{ $values { "x" "an integer" } { "y" "an integer" } { "z" "an integer" } }
+{ $description
+    "Computes the remainder of dividing " { $snippet "x" } " by " { $snippet "y" } ", with the remainder being negative if " { $snippet "x" } " is negative."
+    { $list 
+        "Modulus of fixnums always yields a fixnum."
+        "Modulus of bignums always yields a bignum."            
+    }
+} ;
+
+HELP: /mod "( x y -- z w )"
+{ $values { "x" "an integer" } { "y" "an integer" } { "z" "an integer" } { "w" "an integer" } }
+{ $description
+    "Computes the quotient " { $snippet "z" } " and remainder " { $snippet "w" } " of dividing " { $snippet "x" } " by " { $snippet "y" } ", with the remainder being negative if " { $snippet "x" } " is negative."
+    { $list 
+        "The quotient of two fixnums may overflow and yield a bignum; the remainder is always a fixnum"
+        "The quotient and remainder of two bignums is always a bignum."            
+    }
+} ;
+
+HELP: bitand "( x y -- z )"
+{ $values { "x" "an integer" } { "y" "an integer" } { "z" "an integer" } }
+{ $description "Outputs a new integer where each bit is set if and only if the corresponding bit is set in both inputs." }
+{ $examples
+    { $example "BIN: 101 BIN: 10 bitand .b" "0" }
+    { $example "BIN: 110 BIN: 10 bitand .b" "10" }
+} ;
+
+HELP: bitor "( x y -- z )"
+{ $values { "x" "an integer" } { "y" "an integer" } { "z" "an integer" } }
+{ $description "Outputs a new integer where each bit is set if and only if the corresponding bit is set in at least one of the inputs." }
+{ $examples
+    { $example "BIN: 101 BIN: 10 bitor .b" "111" }
+    { $example "BIN: 110 BIN: 10 bitor .b" "110" }
+} ;
+
+HELP: bitxor "( x y -- z )"
+{ $values { "x" "an integer" } { "y" "an integer" } { "z" "an integer" } }
+{ $description "Outputs a new integer where each bit is set if and only if the corresponding bit is set in exactly one of the inputs." }
+{ $examples
+    { $example "BIN: 101 BIN: 10 bitxor .b" "111" }
+    { $example "BIN: 110 BIN: 10 bitxor .b" "100" }
+} ;
+
+HELP: shift "( x n -- y )"
+{ $values { "x" "an integer" } { "n" "an integer" } { "y" "an integer" } }
+{ $description "Shifts " { $snippet "x" } " to the left by " { $snippet "y" } " bits if " { $snippet "y" } " is positive, or " { $snippet "-y" } " bits to the right if " { $snippet "y" } " is negative. Bits ``falling off'' the right hand side are discarded." }
+{ $examples { $example "BIN: 101 5 shift .b" "10100000" } { $example "BIN: 11111 -2 shift .b" "111" } } ;

library/math/pow.factor

@@ -3,9 +3,6 @@
 IN: math
 USING: errors kernel math math-internals ;
 
-! Power-related functions:
-!     exp log sqrt pow ^mod
-
 : exp >rect swap fexp swap polar> ; inline
 : log >polar swap flog swap rect> ; inline
 

library/math/trig-hyp.factor

@@ -3,12 +3,6 @@
 IN: math
 USING: kernel math math-internals ;
 
-! Trigonometric functions:
-!    cos sec sin cosec tan cot
-
-! Hyperbolic functions:
-!    cosh sech sinh cosech tanh coth
-
 : cos ( z -- cos )
     >rect 2dup
     fcosh swap fcos * -rot