From e1efb189a44f131fba0809bc1dcd4e08928df7d6 Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Wed, 23 Sep 2009 03:08:45 -0500 Subject: [PATCH] math and math.vectors: improved documentation --- basis/math/vectors/vectors-docs.factor | 96 +++++++++++++++++++++++--- basis/math/vectors/vectors.factor | 10 +-- core/math/math-docs.factor | 11 ++- 3 files changed, 98 insertions(+), 19 deletions(-) diff --git a/basis/math/vectors/vectors-docs.factor b/basis/math/vectors/vectors-docs.factor index 67ac27400e..3790e38d55 100644 --- a/basis/math/vectors/vectors-docs.factor +++ b/basis/math/vectors/vectors-docs.factor @@ -1,4 +1,4 @@ -USING: help.markup help.syntax math sequences ; +USING: help.markup help.syntax math math.functions sequences ; IN: math.vectors ARTICLE: "math-vectors" "Vector arithmetic" @@ -14,26 +14,46 @@ $nl { $subsection n+v } { $subsection v-n } { $subsection n-v } -"Combining two vectors to form another vector with " { $link 2map } ":" +"Vector unary operations:" +{ $subsection vneg } +{ $subsection vabs } +{ $subsection vsqrt } +{ $subsection vfloor } +{ $subsection vceiling } +{ $subsection vtruncate } +"Vector/vector binary operations:" { $subsection v+ } { $subsection v- } { $subsection v+- } { $subsection v* } { $subsection v/ } +"Saturated arithmetic (only on " { $link "specialized-arrays" } "):" +{ $subsection vs+ } +{ $subsection vs- } +{ $subsection vs* } +"Comparisons:" { $subsection vmax } { $subsection vmin } +"Bitwise operations:" +{ $subsection vbitand } +{ $subsection vbitor } +{ $subsection vbitxor } "Inner product and norm:" { $subsection v. } { $subsection norm } { $subsection norm-sq } { $subsection normalize } -"Saturated arithmetic may be performed on " { $link "specialized-arrays" } "; the results are clamped to the minimum and maximum bounds of the array element type, instead of wrapping around:" -{ $subsection vs+ } -{ $subsection vs- } -{ $subsection vs* } "Comparing vectors:" { $subsection distance } -{ $subsection v~ } ; +{ $subsection v~ } +"Other functions:" +{ $subsection vsupremum } +{ $subsection vinfimum } +{ $subsection trilerp } +{ $subsection bilerp } +{ $subsection vlerp } +{ $subsection vnlerp } +{ $subsection vbilerp } ; ABOUT: "math-vectors" @@ -41,6 +61,43 @@ HELP: vneg { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } } { $description "Negates each element of " { $snippet "u" } "." } ; +HELP: vabs +{ $values { "u" "a sequence of numbers" } { "v" "a sequence of non-negative real numbers" } } +{ $description "Takes the absolute value of each element of " { $snippet "u" } "." } ; + +HELP: vsqrt +{ $values { "u" "a sequence of non-negative real numbers" } { "v" "a sequence of non-negative real numbers" } } +{ $description "Takes the square root of each element of " { $snippet "u" } "." } +{ $warning "For performance reasons, this does not work with negative inputs, unlike " { $link sqrt } "." } ; + +HELP: vfloor +{ $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } } +{ $description "Takes the " { $link floor } " of each element of " { $snippet "u" } "." } ; + +HELP: vceiling +{ $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } } +{ $description "Takes the " { $link ceiling } " of each element of " { $snippet "u" } "." } ; + +HELP: vtruncate +{ $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } } +{ $description "Truncates each element of " { $snippet "u" } "." } ; + +HELP: n+v +{ $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } } +{ $description "Adds " { $snippet "n" } " to each element of " { $snippet "u" } "." } ; + +HELP: v+n +{ $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } } +{ $description "Adds " { $snippet "n" } " to each element of " { $snippet "u" } "." } ; + +HELP: n-v +{ $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } } +{ $description "Subtracts each element of " { $snippet "u" } " from " { $snippet "n" } "." } ; + +HELP: v-n +{ $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } } +{ $description "Subtracts " { $snippet "n" } " from each element of " { $snippet "u" } "." } ; + HELP: n*v { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } } { $description "Multiplies each element of " { $snippet "u" } " by " { $snippet "n" } "." } ; @@ -51,11 +108,13 @@ HELP: v*n HELP: n/v { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } } -{ $description "Divides " { $snippet "n" } " by each element of " { $snippet "u" } "." } ; +{ $description "Divides " { $snippet "n" } " by each element of " { $snippet "u" } "." } +{ $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ; HELP: v/n { $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } } -{ $description "Divides each element of " { $snippet "u" } " by " { $snippet "n" } "." } ; +{ $description "Divides each element of " { $snippet "u" } " by " { $snippet "n" } "." } +{ $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ; HELP: v+ { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } } @@ -87,7 +146,7 @@ HELP: v* HELP: v/ { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } } { $description "Divides " { $snippet "u" } " by " { $snippet "v" } " component-wise." } -{ $errors "Throws an error if an integer division by zero occurs." } ; +{ $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ; HELP: vmax { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } } @@ -104,7 +163,7 @@ HELP: v. { $description "Computes the real-valued dot product." } { $notes "This word can also take complex number sequences as input, however mathematically it will compute the wrong result. The complex-valued dot product is defined differently:" - { $snippet "0 [ conjugate * + ] 2reduce" } + { $code "0 [ conjugate * + ] 2reduce" } } ; HELP: vs+ @@ -135,6 +194,21 @@ HELP: vs* { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } } { $description "Multiplies " { $snippet "u" } " and " { $snippet "v" } " component-wise with saturation." } ; +HELP: vbitand +{ $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } } +{ $description "Takes the bitwise and of " { $snippet "u" } " and " { $snippet "v" } " component-wise." } +{ $notes "Unlike " { $link bitand } ", this word may be used on a specialized array of floats or doubles, in which case the bitwise representation of the floating point numbers is operated upon." } ; + +HELP: vbitor +{ $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } } +{ $description "Takes the bitwise or of " { $snippet "u" } " and " { $snippet "v" } " component-wise." } +{ $notes "Unlike " { $link bitor } ", this word may be used on a specialized array of floats or doubles, in which case the bitwise representation of the floating point numbers is operated upon." } ; + +HELP: vbitxor +{ $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } } +{ $description "Takes the bitwise exclusive or of " { $snippet "u" } " and " { $snippet "v" } " component-wise." } +{ $notes "Unlike " { $link bitxor } ", this word may be used on a specialized array of floats or doubles, in which case the bitwise representation of the floating point numbers is operated upon." } ; + HELP: norm-sq { $values { "v" "a sequence of numbers" } { "x" "a non-negative real number" } } { $description "Computes the squared length of a mathematical vector." } ; diff --git a/basis/math/vectors/vectors.factor b/basis/math/vectors/vectors.factor index eb97fba663..4b6f67544a 100644 --- a/basis/math/vectors/vectors.factor +++ b/basis/math/vectors/vectors.factor @@ -1,7 +1,7 @@ ! Copyright (C) 2005, 2009 Slava Pestov. ! See http://factorcode.org/license.txt for BSD license. USING: arrays alien.c-types kernel sequences math math.functions -hints math.order fry combinators ; +hints math.order math.libm fry combinators ; QUALIFIED-WITH: alien.c-types c IN: math.vectors @@ -44,7 +44,7 @@ PRIVATE> : vs* ( u v -- w ) [ * ] 2saturate-map ; : vabs ( u -- v ) [ abs ] map ; -: vsqrt ( u -- v ) [ sqrt ] map ; +: vsqrt ( u -- v ) [ >float fsqrt ] map ; : vbitor ( u v -- w ) over '[ _ [ bitor ] fp-bitwise-op ] 2map ; : vbitxor ( u v -- w ) over '[ _ [ bitxor ] fp-bitwise-op ] 2map ; -: vfloor ( v -- _v_ ) [ floor ] map ; -: vceiling ( v -- ^v^ ) [ ceiling ] map ; -: vtruncate ( v -- -v- ) [ truncate ] map ; +: vfloor ( u -- v ) [ floor ] map ; +: vceiling ( u -- v ) [ ceiling ] map ; +: vtruncate ( u -- v ) [ truncate ] map ; : vsupremum ( seq -- vmax ) [ ] [ vmax ] map-reduce ; : vinfimum ( seq -- vmin ) [ ] [ vmin ] map-reduce ; diff --git a/core/math/math-docs.factor b/core/math/math-docs.factor index e5de106bbb..e6805d693b 100644 --- a/core/math/math-docs.factor +++ b/core/math/math-docs.factor @@ -434,11 +434,15 @@ HELP: byte-array>bignum { $description "Converts a byte-array, interpreted as little-endian, into a bignum integer. User code should call " { $link le> } " or " { $link be> } " instead." } ; ARTICLE: "division-by-zero" "Division by zero" -"Floating point division never raises an error if the denominator is zero. This means that if at least one of the two inputs to " { $link / } ", " { $link /f } " or " { $link mod } " is a float, the result will be a floating point infinity or not a number value." +"Behavior of division operations when a denominator of zero is used depends on the data types in question, as well as the platform being used." +$nl +"Floating point division only throws an error if the appropriate traps are enabled in the floating point environment. If traps are disabled, a Not-a-number value or an infinity is output, depending on whether the numerator is zero or non-zero." +$nl +"Floating point traps are disabled by default and the " { $vocab-link "math.floats.env" } " vocabulary provides words to enable them. Floating point division is performed by " { $link / } ", " { $link /f } " or " { $link mod } " if at least one of the two inputs is a float. Floating point division is always performed by " { $link /f } "." $nl "The behavior of integer division is hardware specific. On x86 processors, " { $link /i } " and " { $link mod } " raise an error if both inputs are integers and the denominator is zero. On PowerPC, integer division by zero yields a result of zero." $nl -"On the other hand, the " { $link / } " word, when given integer arguments, implements a much more expensive division algorithm which always yields an exact rational answer, and this word always tests for division by zero explicitly." ; +"The " { $link / } " word, when given integer arguments, implements a much more expensive division algorithm which always yields an exact rational answer, and this word always tests for division by zero explicitly." ; ARTICLE: "number-protocol" "Number protocol" "Math operations obey certain numerical upgrade rules. If one of the inputs is a bignum and the other is a fixnum, the latter is first coerced to a bignum; if one of the inputs is a float, the other is coerced to a float." @@ -459,7 +463,8 @@ $nl { $subsection > } { $subsection >= } "Numbers can be compared for equality using " { $link = } ", or a less precise test which disregards types:" -{ $subsection number= } ; +{ $subsection number= } +{ $see-also "math.floats.compare" } ; ARTICLE: "modular-arithmetic" "Modular arithmetic" { $subsection mod }