basis/math/vectors/vectors-docs.factor

   1 USING: help.markup help.syntax math sequences ;
   2 IN: math.vectors
   3
   4 ARTICLE: "math-vectors" "Vector arithmetic"
   5 "Any Factor sequence can be used to represent a mathematical vector."
   6 $nl
   7 "Acting on vectors by a scalar:"
   8 { $subsection vneg }
   9 { $subsection v*n }
  10 { $subsection n*v }
  11 { $subsection v/n }
  12 { $subsection n/v }
  13 "Combining two vectors to form another vector with " { $link 2map } ":"
  14 { $subsection v+ }
  15 { $subsection v- }
  16 { $subsection v* }
  17 { $subsection v/ }
  18 { $subsection vmax }
  19 { $subsection vmin }
  20 "Inner product and norm:"
  21 { $subsection v. }
  22 { $subsection norm }
  23 { $subsection norm-sq }
  24 { $subsection normalize } ;
  25
  26 ABOUT: "math-vectors"
  27
  28 HELP: vneg
  29 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
  30 { $description "Negates each element of " { $snippet "u" } "." } ;
  31
  32 HELP: n*v
  33 { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
  34 { $description "Multiplies each element of " { $snippet "u" } " by " { $snippet "n" } "." } ;
  35
  36 HELP: v*n
  37 { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
  38 { $description "Multiplies each element of " { $snippet "u" } " by " { $snippet "n" } "." } ;
  39
  40 HELP: n/v
  41 { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
  42 { $description "Divides " { $snippet "n" } " by each element of " { $snippet "u" } "." } ;
  43
  44 HELP: v/n
  45 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
  46 { $description "Divides each element of " { $snippet "u" } " by " { $snippet "n" } "." } ;
  47
  48 HELP: v+
  49 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
  50 { $description "Adds " { $snippet "u" } " and " { $snippet "v" } " component-wise." } ;
  51
  52 HELP: v-
  53 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
  54 { $description "Subtracts " { $snippet "v" } " from " { $snippet "u" } " component-wise." } ;
  55
  56 HELP: [v-]
  57 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
  58 { $description "Subtracts " { $snippet "v" } " from " { $snippet "u" } " component-wise; any components which become negative are set to zero." } ;
  59
  60 HELP: v*
  61 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
  62 { $description "Multiplies " { $snippet "u" } " and " { $snippet "v" } " component-wise." } ;
  63
  64 HELP: v/
  65 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
  66 { $description "Divides " { $snippet "u" } " by " { $snippet "v" } " component-wise." }
  67 { $errors "Throws an error if an integer division by zero occurs." } ;
  68
  69 HELP: vmax
  70 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
  71 { $description "Creates a sequence where each element is the maximum of the corresponding elements from " { $snippet "u" } " andd " { $snippet "v" } "." }
  72 { $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 5 } { -7 6 3 } vmax ." "{ 1 6 5 }" } } ;
  73
  74 HELP: vmin
  75 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
  76 { $description "Creates a sequence where each element is the minimum of the corresponding elements from " { $snippet "u" } " andd " { $snippet "v" } "." }
  77 { $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 5 } { -7 6 3 } vmin ." "{ -7 2 3 }" } } ;
  78
  79 HELP: v.
  80 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "x" "a real number" } }
  81 { $description "Computes the real-valued dot product." }
  82 { $notes
  83     "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:"
  84     { $snippet "0 [ conjugate * + ] 2reduce" }
  85 } ;
  86
  87 HELP: norm-sq
  88 { $values { "v" "a sequence of numbers" } { "x" "a non-negative real number" } }
  89 { $description "Computes the squared length of a mathematical vector." } ;
  90
  91 HELP: norm
  92 { $values { "v" "a sequence of numbers" } { "x" "a non-negative real number" } }
  93 { $description "Computes the length of a mathematical vector." } ;
  94
  95 HELP: normalize
  96 { $values { "u" "a sequence of numbers, not all zero" } { "v" "a sequence of numbers" } }
  97 { $description "Outputs a vector with the same direction as " { $snippet "u" } " but length 1." } ;
  98
  99 HELP: set-axis
 100 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "axis" "a sequence of 0/1" } { "w" "a sequence of numbers" } }
 101 { $description "Using " { $snippet "w" } " as a template, creates a new sequence containing corresponding elements from " { $snippet "u" } " in place of 0, and corresponding elements from " { $snippet "v" } " in place of 1." }
 102 { $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 3 } { 4 5 6 } { 0 1 0 } set-axis ." "{ 1 5 3 }" } } ;
 103
 104 { 2map v+ v- v* v/ } related-words
 105
 106 { 2reduce v. } related-words