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 words math math.functions math.derivatives.syntax ;
   4 IN: math.dual
   5
   6 HELP: <dual>
   7 { $values
   8     { "ordinary-part" real } { "epsilon-part" real }
   9     { "dual" dual number }
  10 }
  11 { $description "Creates a dual number from its ordinary and epsilon parts." } ;
  12
  13 HELP: d*
  14 { $values
  15     { "x" dual } { "y" dual }
  16     { "x*y" dual }
  17 }
  18 { $description "Multiply dual numbers." } ;
  19
  20 HELP: d+
  21 { $values
  22     { "x" dual } { "y" dual }
  23     { "x+y" dual }
  24 }
  25 { $description "Add dual numbers." } ;
  26
  27 HELP: d-
  28 { $values
  29     { "x" dual } { "y" dual }
  30     { "x-y" dual }
  31 }
  32 { $description "Subtract dual numbers." } ;
  33
  34 HELP: d/
  35 { $values
  36     { "x" dual } { "y" dual }
  37     { "x/y" dual }
  38 }
  39 { $description "Divide dual numbers." }
  40 { $errors "Throws an error if the ordinary part of " { $snippet "x" } " is zero." } ;
  41
  42 HELP: d^
  43 { $values
  44     { "x" dual } { "y" dual }
  45     { "x^y" dual }
  46 }
  47 { $description "Raise a dual number to a (possibly dual) power" } ;
  48
  49 HELP: dabs
  50 { $values
  51      { "x" dual }
  52      { "|x|" dual }
  53 }
  54 { $description "Absolute value of a dual number." } ;
  55
  56 HELP: dacosh
  57 { $values
  58      { "x" dual }
  59      { "y" dual }
  60 }
  61 { $description "Inverse hyberbolic cosine of a dual number." } ;
  62
  63 HELP: dasinh
  64 { $values
  65      { "x" dual }
  66      { "y" dual }
  67 }
  68 { $description "Inverse hyberbolic sine of a dual number." } ;
  69
  70 HELP: datanh
  71 { $values
  72      { "x" dual }
  73      { "y" dual }
  74 }
  75 { $description "Inverse hyberbolic tangent of a dual number." } ;
  76
  77 HELP: dneg
  78 { $values
  79      { "x" dual }
  80      { "-x" dual }
  81 }
  82 { $description "Negative of a dual number." } ;
  83
  84 HELP: drecip
  85 { $values
  86      { "x" dual }
  87      { "1/x" dual }
  88 }
  89 { $description "Reciprocal of a dual number." } ;
  90
  91 HELP: define-dual-method
  92 { $values
  93     { "word" word }
  94 }
  95 { $description "Defines a method on the dual numbers for generic word." }
  96 { $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: } "." } ;
  97
  98 { define-dual-method dual-op POSTPONE: DERIVATIVE: } related-words
  99
 100 HELP: dual
 101 { $class-description "The class of dual numbers with non-zero epsilon part." } ;
 102
 103 HELP: dual-op
 104 { $values
 105     { "word" word }
 106 }
 107 { $description "Similar to " { $link execute } ", but promotes word to operate on duals." }
 108 { $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." }
 109 { $examples
 110     { $unchecked-example "USING: math math.dual math.derivatives.syntax math.functions ;"
 111     "DERIVATIVE: sin [ cos * ]"
 112     "M: dual sin \\sin dual-op ;" "" }
 113     { $unchecked-example "USING: math math.dual math.derivatives.syntax ;"
 114     "DERIVATIVE: * [ drop ] [ nip ]"
 115     ": d* ( x y -- x*y ) \ * dual-op ;" "" }
 116 } ;
 117
 118 HELP: unpack-dual
 119 { $values
 120     { "dual" dual }
 121     { "ordinary-part" number } { "epsilon-part" number }
 122 }
 123 { $description "Extracts the ordinary and epsilon part of a dual number." } ;
 124
 125 ARTICLE: "math.dual" "Dual Numbers"
 126 "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."
 127 $nl
 128 "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" } "."
 129 ;
 130
 131
 132 ABOUT: "math.dual"