extra/math/dual/dual-docs.factor

   1 ! Copyright (C) 2009 Jason W. Merrill.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax kernel math
   4 math.derivatives.syntax words ;
   5 IN: math.dual
   6
   7 HELP: <dual>
   8 { $values
   9     { "ordinary-part" real } { "epsilon-part" real }
  10     { "dual" dual number }
  11 }
  12 { $description "Creates a dual number from its ordinary and epsilon parts." } ;
  13
  14 HELP: define-dual
  15 { $values
  16     { "word" word }
  17 }
  18 { $description "Defines a word " { $snippet "d[word]" } " in the " { $vocab-link "math.dual" } " vocabulary that operates on dual numbers." }
  19 { $notes "Uses the derivative word-prop, which holds a list of quotations giving the partial derivatives of the word with respect to each of its arguments. This can be set using " { $link POSTPONE: DERIVATIVE: } "." } ;
  20
  21 { define-dual dual-op POSTPONE: DERIVATIVE: } related-words
  22
  23 HELP: dual
  24 { $class-description "The class of dual numbers with non-zero epsilon part." } ;
  25
  26 HELP: dual-op
  27 { $values
  28     { "word" word }
  29 }
  30 { $description "Similar to " { $link execute } ", but promotes word to operate on duals." }
  31 { $notes "Uses the derivative word-prop, which holds a list of quotations giving the partial derivatives of the word with respect to each of its arguments. This can be set using " { $link POSTPONE: DERIVATIVE: } ". Once a derivative has been defined for a word, dual-op makes it easy to extend the definition to dual numbers." }
  32 { $examples
  33     { $unchecked-example "USING: math math.dual math.derivatives.syntax math.functions ;"
  34     "DERIVATIVE: sin [ cos * ]"
  35     "M: dual sin \\sin dual-op ;" "" }
  36     { $unchecked-example "USING: math math.dual math.derivatives.syntax ;"
  37     "DERIVATIVE: * [ drop ] [ nip ]"
  38     ": d* ( x y -- x*y ) \ * dual-op ;" "" }
  39 } ;
  40
  41 HELP: unpack-dual
  42 { $values
  43     { "dual" dual }
  44     { "ordinary-part" number } { "epsilon-part" number }
  45 }
  46 { $description "Extracts the ordinary and epsilon part of a dual number." } ;
  47
  48 ARTICLE: "math.dual" "Dual Numbers"
  49 "The " { $vocab-link "math.dual" } " vocabulary implements dual numbers, along with arithmetic methods for working with them. Many of the functions in " { $vocab-link "math.functions" } " are extended to work with dual numbers."
  50 $nl
  51 "Dual numbers are ordered pairs " { $snippet "<o,e>" } "--an ordinary part and an epsilon part--with component-wise addition and multiplication defined by " { $snippet "<o1,e1>*<o2,e2> = <o1*o2,e1*o2 + e2*o1>" } ". They are analagous to complex numbers with " { $snippet "i^2 = 0" } "instead of " { $snippet "i^2 = -1" } ". For well-behaved functions " { $snippet "f" } ", " { $snippet "f(<o1,e1>) = f(o1) + e1*f'(o1)" } ", where " { $snippet "f'" } " is the derivative of " { $snippet "f" } "."
  52 ;
  53
  54 ABOUT: "math.dual"