core/math/complex.facts

   1 USING: help math math-internals ;
   2
   3 HELP: complex
   4 { $class-description "The class of complex numbers with non-zero imaginary part." } ;
   5
   6 HELP: real ( z -- x )
   7 { $values { "z" "a complex number" } { "x" "a real number" } }
   8 { $description "Outputs the real part of a complex number. This acts as the identity on real numbers." }
   9 { $notes "This word also acts as the class word for the class of real numbers, which is a disjoint union of rationals and floats." } ;
  10
  11 HELP: imaginary ( z -- y )
  12 { $values { "z" "a complex number" } { "y" "a real number" } }
  13 { $description "Outputs the imaginary part of a complex number. This outputs zero for real numbers." } ;
  14
  15 HELP: (rect>)
  16 { $values { "x" "a real number" } { "y" "a real number" } { "z" "a complex number" } }
  17 { $description "Creates a complex number from real and imaginary components." }
  18 { $warning "This word does not check that the arguments are real numbers, which can have undefined consequences. Use the " { $link rect> } " word instead." } ;
  19
  20 HELP: number
  21 { $class-description "The class of numbers." } ;
  22
  23 HELP: rect>
  24 { $values { "x" "a real number" } { "y" "a real number" } { "z" "a complex number" } }
  25 { $description "Creates a complex number from real and imaginary components." } ;
  26
  27 HELP: >rect
  28 { $values { "z" "a complex number" } { "x" "a real number" } { "y" "a real number" } }
  29 { $description "Extracts the real and imaginary components of a complex number." } ;
  30
  31 HELP: conjugate
  32 { $values { "z" "a complex number" } { "z*" "a complex number" } }
  33 { $description "Computes the complex conjugate by flipping the sign of the imaginary part of " { $snippet "z" } "." } ;
  34
  35 HELP: arg
  36 { $values { "z" "a complex number" } { "arg" "a number in the interval " { $snippet "(-pi,pi]" } } }
  37 { $description "Computes the complex argument." } ;
  38
  39 HELP: >polar
  40 { $values { "z" "a complex number" } { "abs" "a non-negative real number" } { "arg" "a number in the interval " { $snippet "(-pi,pi]" } } }
  41 { $description "Creates a complex number from an absolute value and argument (polar form)." } ;
  42
  43 HELP: cis
  44 { $values { "arg" "a real number" } { "z" "a complex number on the unit circle" } }
  45 { $description "Computes a point on the unit circle using Euler's formula for " { $snippet "exp(arg*i)" } "." }
  46 { $see-also exp } ;
  47
  48 HELP: polar>
  49 { $values { "z" "a complex number" } { "abs" "a non-negative real number" } { "arg" "a real number" } }
  50 { $description "Converts an absolute value and argument (polar form) to a complex number." } ;
  51
  52 HELP: 2>rect
  53 { $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" } } }
  54 { $description "Extracts real and imaginary components of two numbers at once." } ;
  55
  56 HELP: complex/
  57 { $values { "x" "a complex number" } { "y" "a complex number" } { "r" "a real number" } { "i" "a real number" } { "m" "a real number" } }
  58 { $description
  59     "Complex division kernel. If we use the notation from " { $link 2>rect } ", this word computes:"
  60     { $code
  61         "r = xr*yr+xi*yi"
  62         "i = xi*yr-xr*yi"
  63         "m = yr*yr+yi*yi"
  64     }
  65 } ;
  66
  67 HELP: <complex> ( x y -- z )
  68 { $values { "x" "a real number" } { "y" "a real number" } { "z" "a complex number" } }
  69 { $description "Low-level complex number constructor. User code should call " { $link rect> } " instead." } ;