basis/math/functions/functions-docs.factor

   1 USING: help.markup help.syntax kernel math math.order
   2 sequences quotations math.functions.private math.constants ;
   3 IN: math.functions
   4
   5 ARTICLE: "integer-functions" "Integer functions"
   6 { $subsections
   7     align
   8     gcd
   9     log2
  10     next-power-of-2
  11 }
  12 "Modular exponentiation:"
  13 { $subsections ^mod mod-inv }
  14 "Tests:"
  15 { $subsections
  16     power-of-2?
  17     even?
  18     odd?
  19     divisor?
  20 } ;
  21
  22 ARTICLE: "arithmetic-functions" "Arithmetic functions"
  23 "Computing additive and multiplicative inverses:"
  24 { $subsections neg recip }
  25 "Complex conjugation:"
  26 { $subsections conjugate }
  27 "Tests:"
  28 { $subsections zero? between? }
  29 "Control flow:"
  30 { $subsections
  31     if-zero
  32     when-zero
  33     unless-zero
  34 }
  35 "Sign:"
  36 { $subsections sgn }
  37 "Rounding:"
  38 { $subsections
  39     ceiling
  40     floor
  41     truncate
  42     round
  43 }
  44 "Inexact comparison:"
  45 { $subsections ~ }
  46 "Numbers implement the " { $link "math.order" } ", therefore operations such as " { $link min } " and " { $link max } " can be used with numbers." ;
  47
  48 ARTICLE: "power-functions" "Powers and logarithms"
  49 "Squares:"
  50 { $subsections sq sqrt }
  51 "Exponential and natural logarithm:"
  52 { $subsections e^ cis log }
  53 "Other logarithms:"
  54 { $subsections log1+ log10 logn }
  55 "Raising a number to a power:"
  56 { $subsections ^ e^ 10^ }
  57 "Logistics functions:"
  58 { $subsections sigmoid }
  59 "Finding the root of a number:"
  60 { $subsections nth-root }
  61 "Converting between rectangular and polar form:"
  62 { $subsections
  63     abs
  64     absq
  65     arg
  66     >polar
  67     polar>
  68 } ;
  69
  70 ARTICLE: "trig-hyp-functions" "Trigonometric and hyperbolic functions"
  71 "Trigonometric functions:"
  72 { $subsections cos sin tan }
  73 "Reciprocals:"
  74 { $subsections sec cosec cot }
  75 "Inverses:"
  76 { $subsections acos asin atan }
  77 "Inverse reciprocals:"
  78 { $subsections asec acosec acot }
  79 "Hyperbolic functions:"
  80 { $subsections cosh sinh tanh }
  81 "Reciprocals:"
  82 { $subsections sech cosech coth }
  83 "Inverses:"
  84 { $subsections acosh asinh atanh }
  85 "Inverse reciprocals:"
  86 { $subsections asech acosech acoth } ;
  87
  88 ARTICLE: "math-functions" "Mathematical functions"
  89 { $subsections
  90     "integer-functions"
  91     "arithmetic-functions"
  92     "power-functions"
  93     "trig-hyp-functions"
  94 } ;
  95
  96 ABOUT: "math-functions"
  97
  98 HELP: align
  99 { $values { "m" integer } { "w" "a power of 2" } { "n" "an integer multiple of " { $snippet "w" } } }
 100 { $description "Outputs the least multiple of " { $snippet "w" } " greater than " { $snippet "m" } "." }
 101 { $notes "This word will give an incorrect result if " { $snippet "w" } " is not a power of 2." } ;
 102
 103 HELP: e^
 104 { $values { "x" number } { "e^x" number } }
 105 { $description "Exponential function, raises " { $link e } " to the power of " { $snippet "x" } "." } ;
 106
 107 HELP: frexp
 108 { $values { "x" number } { "y" float } { "exp" integer } }
 109 { $description "Break the number " { $snippet "x" } " into a normalized fraction " { $snippet "y" } " and an integral power of 2 " { $snippet "e^" } "." $nl "The function returns a number " { $snippet "y" } " in the interval [1/2, 1) or 0, and a number " { $snippet "exp" } " such that " { $snippet "x = y*(2**exp)" } "." } ;
 110
 111 HELP: ldexp
 112 { $values { "x" number } { "exp" number } { "y" number } }
 113 { $description "Multiply " { $snippet "x" } " by " { $snippet "2^exp" } "." }
 114 { $notes { $link ldexp } " is the inverse of " { $link frexp } "." } ;
 115
 116 HELP: log
 117 { $values { "x" number } { "y" number } }
 118 { $description "Natural logarithm function. Outputs negative infinity if " { $snippet "x" } " is 0." } ;
 119
 120 HELP: logn
 121 { $values { "x" number } { "n" number } { "y" number } }
 122 { $description "Finds the base " { $snippet "n" } " logarithm of " { $snippet "x" } "." } ;
 123
 124 HELP: log1+
 125 { $values { "x" number } { "y" number } }
 126 { $description "Takes the natural logarithm of " { $snippet "1 + x" } ". Outputs negative infinity if " { $snippet "1 + x" } " is zero. This word may be more accurate than " { $snippet "1 + log" } " for very small values of " { $snippet "x" } "." } ;
 127
 128 HELP: log10
 129 { $values { "x" number } { "y" number } }
 130 { $description "Logarithm function base 10. Outputs negative infinity if " { $snippet "x" } " is 0." } ;
 131
 132 HELP: sqrt
 133 { $values { "x" number } { "y" number } }
 134 { $description "Square root function." } ;
 135
 136 HELP: cosh
 137 $values-x/y
 138 { $description "Hyperbolic cosine." } ;
 139
 140 HELP: sech
 141 $values-x/y
 142 { $description "Hyperbolic secant." } ;
 143
 144 HELP: sinh
 145 $values-x/y
 146 { $description "Hyperbolic sine." } ;
 147
 148 HELP: cosech
 149 $values-x/y
 150 { $description "Hyperbolic cosecant." } ;
 151
 152 HELP: tanh
 153 $values-x/y
 154 { $description "Hyperbolic tangent." } ;
 155
 156 HELP: coth
 157 $values-x/y
 158 { $description "Hyperbolic cotangent." } ;
 159
 160 HELP: cos
 161 $values-x/y
 162 { $description "Trigonometric cosine." } ;
 163
 164 HELP: sec
 165 $values-x/y
 166 { $description "Trigonometric secant." } ;
 167
 168 HELP: sin
 169 $values-x/y
 170 { $description "Trigonometric sine." } ;
 171
 172 HELP: cosec
 173 $values-x/y
 174 { $description "Trigonometric cosecant." } ;
 175
 176 HELP: tan
 177 $values-x/y
 178 { $description "Trigonometric tangent." } ;
 179
 180 HELP: cot
 181 $values-x/y
 182 { $description "Trigonometric cotangent." } ;
 183
 184 HELP: acosh
 185 $values-x/y
 186 { $description "Inverse hyperbolic cosine." } ;
 187
 188 HELP: asech
 189 $values-x/y
 190 { $description "Inverse hyperbolic secant." } ;
 191
 192 HELP: asinh
 193 $values-x/y
 194 { $description "Inverse hyperbolic sine." } ;
 195
 196 HELP: acosech
 197 $values-x/y
 198 { $description "Inverse hyperbolic cosecant." } ;
 199
 200 HELP: atanh
 201 $values-x/y
 202 { $description "Inverse hyperbolic tangent." } ;
 203
 204 HELP: acoth
 205 $values-x/y
 206 { $description "Inverse hyperbolic cotangent." } ;
 207
 208 HELP: acos
 209 $values-x/y
 210 { $description "Inverse trigonometric cosine." } ;
 211
 212 HELP: asec
 213 $values-x/y
 214 { $description "Inverse trigonometric secant." } ;
 215
 216 HELP: asin
 217 $values-x/y
 218 { $description "Inverse trigonometric sine." } ;
 219
 220 HELP: acosec
 221 $values-x/y
 222 { $description "Inverse trigonometric cosecant." } ;
 223
 224 HELP: atan
 225 $values-x/y
 226 { $description "Inverse trigonometric tangent." } ;
 227
 228 HELP: acot
 229 $values-x/y
 230 { $description "Inverse trigonometric cotangent." } ;
 231
 232 HELP: conjugate
 233 { $values { "z" number } { "z*" number } }
 234 { $description "Computes the complex conjugate by flipping the sign of the imaginary part of " { $snippet "z" } "." } ;
 235
 236 HELP: arg
 237 { $values { "z" number } { "arg" "a number in the interval " { $snippet "(-pi,pi]" } } }
 238 { $description "Computes the complex argument." } ;
 239
 240 HELP: >polar
 241 { $values { "z" number } { "abs" "a non-negative real number" } { "arg" "a number in the interval " { $snippet "(-pi,pi]" } } }
 242 { $description "Converts a complex number into an absolute value and argument (polar form)." } ;
 243
 244 HELP: cis
 245 { $values { "arg" "a real number" } { "z" "a complex number on the unit circle" } }
 246 { $description "Computes a point on the unit circle using Euler's formula for " { $snippet "e^(arg*i)" } "." } ;
 247
 248 { cis e^ } related-words
 249
 250 HELP: polar>
 251 { $values { "abs" "a non-negative real number" } { "arg" real } { "z" number } }
 252 { $description "Converts an absolute value and argument (polar form) to a complex number." } ;
 253
 254 HELP: [-1,1]?
 255 { $values { "x" number } { "?" boolean } }
 256 { $description "Tests if " { $snippet "x" } " is a real number between -1 and 1, inclusive." } ;
 257
 258 HELP: abs
 259 { $values { "x" number } { "y" "a non-negative real number" } }
 260 { $description "Computes the absolute value of a number." }
 261 { $see-also absq } ;
 262
 263 HELP: absq
 264 { $values { "x" number } { "y" "a non-negative real number" } }
 265 { $description "Computes the squared absolute value of a number. For complex numbers this is marginally more efficient than " { $link abs } "." } ;
 266
 267 HELP: ^
 268 { $values { "x" number } { "y" number } { "x^y" number } }
 269 { $description "Raises " { $snippet "x" } " to the power of " { $snippet "y" } ". If " { $snippet "y" } " is an integer the answer is computed exactly, otherwise a floating point approximation is used." }
 270 { $errors "Throws an error if " { $snippet "x" } " and " { $snippet "y" } " are both integer 0." } ;
 271
 272 HELP: nth-root
 273 { $values { "n" integer } { "x" number } { "y" number } }
 274 { $description "Calculates the nth root of a number, such that " { $snippet "y^n=x" } "." } ;
 275
 276 HELP: 10^
 277 { $values { "x" number } { "10^x" number } }
 278 { $description "Raises 10 to the power of " { $snippet "x" } ". If " { $snippet "x" } " is an integer the answer is computed exactly, otherwise a floating point approximation is used." } ;
 279
 280 HELP: divisor?
 281 { $values { "m" integer } { "n" integer } { "?" boolean } }
 282 { $description "Tests if " { $snippet "n" } " is a divisor of " { $snippet "m" } ". This is the same thing as asking if " { $snippet "m" } " is divisible by " { $snippet "n" } "." }
 283 { $notes "Returns t for both negative and positive divisors, as well as for trivial and non-trivial divisors." } ;
 284
 285 HELP: mod-inv
 286 { $values { "x" integer } { "n" integer } { "y" integer } }
 287 { $description "Outputs an integer " { $snippet "y" } " such that " { $snippet "xy = 1 (mod n)" } "." }
 288 { $errors "Throws an error if " { $snippet "n" } " is not invertible modulo " { $snippet "n" } "." }
 289 { $examples
 290     { $example "USING: math.functions prettyprint ;" "173 1119 mod-inv ." "815" }
 291     { $example "USING: math prettyprint ;" "173 815 * 1119 mod ." "1" }
 292 } ;
 293
 294 HELP: ^mod
 295 { $values { "x" real } { "y" real } { "n" real } { "z" real } }
 296 { $description "Outputs the result of computing " { $snippet "x^y mod n" } "." } ;
 297
 298 HELP: ~
 299 { $values { "x" real } { "y" real } { "epsilon" real } { "?" boolean } }
 300 { $description "Tests if " { $snippet "x" } " and " { $snippet "y" } " are approximately equal to each other. There are three possible comparison tests, chosen based on the sign of " { $snippet "epsilon" } ":"
 301     { $list
 302         { { $snippet "epsilon" } " is zero: exact comparison." }
 303         { { $snippet "epsilon" } " is positive: absolute distance test." }
 304         { { $snippet "epsilon" } " is negative: relative distance test." }
 305     }
 306 } ;
 307
 308 HELP: truncate
 309 { $values { "x" real } { "y" "a whole real number" } }
 310 { $description "Outputs the number that results from subtracting the fractional component of " { $snippet "x" } "." }
 311 { $notes "The result is not necessarily an integer." } ;
 312
 313 HELP: floor
 314 { $values { "x" real } { "y" "a whole real number" } }
 315 { $description "Outputs the greatest whole number smaller than or equal to " { $snippet "x" } "." }
 316 { $notes "The result is not necessarily an integer." } ;
 317
 318 HELP: ceiling
 319 { $values { "x" real } { "y" "a whole real number" } }
 320 { $description "Outputs the least whole number greater than or equal to " { $snippet "x" } "." }
 321 { $notes "The result is not necessarily an integer." } ;
 322
 323 HELP: round
 324 { $values { "x" real } { "y" "a whole real number" } }
 325 { $description "Outputs the whole number closest to " { $snippet "x" } ", rounding out at half." }
 326 { $notes "The result is not necessarily an integer." }
 327 { $examples
 328     { $example "USING: math.functions prettyprint ;" "4.5 round ." "5.0" }
 329     { $example "USING: math.functions prettyprint ;" "4.4 round ." "4.0" }
 330 } ;
 331
 332 HELP: round-to-even
 333 { $values { "x" real } { "y" "a whole real number" } }
 334 { $description "Outputs the whole number closest to " { $snippet "x" } ", rounding out at half, breaking ties towards even numbers. This is also known as banker's rounding or unbiased rounding." }
 335 { $notes "The result is not necessarily an integer." }
 336 { $examples
 337     { $example "USING: math.functions prettyprint ;" "0.5 round-to-even ." "0.0" }
 338     { $example "USING: math.functions prettyprint ;" "1.5 round-to-even ." "2.0" }
 339 } ;
 340
 341 HELP: round-to-odd
 342 { $values { "x" real } { "y" "a whole real number" } }
 343 { $description "Outputs the whole number closest to " { $snippet "x" } ", rounding out at half, breaking ties towards odd numbers." }
 344 { $notes "The result is not necessarily an integer." }
 345 { $examples
 346     { $example "USING: math.functions prettyprint ;" "0.5 round-to-odd ." "1.0" }
 347     { $example "USING: math.functions prettyprint ;" "1.5 round-to-odd ." "1.0" }
 348 } ;
 349
 350 HELP: roots
 351 { $values { "x" number } { "t" integer } { "seq" sequence } }
 352 { $description "Outputs the " { $snippet "t" } " roots of a number " { $snippet "x" } "." }
 353 { $notes "The results are not necessarily real." } ;
 354
 355 HELP: sigmoid
 356 { $values { "x" number } { "y" number } }
 357 { $description "Outputs the sigmoid, an S-shaped \"logistic\" function, from 0 to 1, of the number " { $snippet "x" } "." } ;
 358
 359 HELP: signum
 360 { $values { "x" number } { "y" number } }
 361 { $description "Calculates the signum value. For a real number, " { $snippet "x" } ", this is its sign (-1, 0, or 1). For a complex number, " { $snippet "x" } ", this is the point on the unit circle of the complex plane that is nearest to " { $snippet "x" } "." } ;
 362
 363 HELP: copysign
 364 { $values { "x" number } { "y" number } { "x'" number } }
 365 { $description "Returns " { $snippet "x" } " with the sign of " { $snippet "y" } ", as a " { $link float } "." } ;