help/sqrt

   1 NAME
   2     sqrt - evaluate exactly or approximate a square root
   3
   4 SYNOPSIS
   5     sqrt(x [, eps[, z]])
   6
   7 TYPES
   8     If x is an object of type tt, or if x is not an object but y
   9     is an object of type tt, and the user-defined function
  10     tt_round has been defined, the types for x, y, z are as
  11     required for tt_round, the value returned, if any, is as
  12     specified in tt_round.  For object x or y, z defaults to a
  13     null value.
  14
  15     For other argument types:
  16
  17     x           real or complex
  18     eps         nonzero real
  19     z           integer
  20
  21     return      real or complex
  22
  23 DESCRIPTION
  24     For real or complex x, sqrt(x, y, z) returns either the exact
  25     value of a square root of x (which is possible only if this
  26     square root is rational) or a number for which the real and
  27     imaginary parts are either exact or the nearest below or nearest
  28     above to the exact values.
  29
  30     The argument, eps, specifies the epsilon/error value to be
  31     used during calculations.  By default, this value is epsilon().
  32
  33     The seven lowest bits of z are used to control the signs of the
  34     result and the type of any rounding:
  35
  36     z bit 6    ((z & 64) > 0)
  37
  38         0:      principal square root
  39
  40         1:      negative principal square root
  41
  42     z bit 5    ((z & 32) > 0)
  43
  44         0:      return aprox square root
  45
  46         1:      return exact square root when real & imaginary are rational
  47
  48     z bits 5-0  (z & 31)
  49
  50         0:      round down or up according as y is positive or negative,
  51                 sgn(r) = sgn(y)
  52
  53         1:      round up or down according as y is positive or negative,
  54                 sgn(r) = -sgn(y)
  55
  56         2:      round towards zero, sgn(r) = sgn(x)
  57
  58         3:      round away from zero, sgn(r) = -sgn(x)
  59
  60         4:      round down
  61
  62         5:      round up
  63
  64         6:      round towards or from zero according as y is positive or
  65                 negative, sgn(r) = sgn(x/y)
  66
  67         7:      round from or towards zero according as y is positive or
  68                 negative, sgn(r) = -sgn(x/y)
  69
  70         8:      a/y is even
  71
  72         9:      a/y is odd
  73
  74         10:     a/y is even or odd according as x/y is positive or negative
  75
  76         11:     a/y is odd or even according as x/y is positive or negative
  77
  78         12:     a/y is even or odd according as y is positive or negative
  79
  80         13:     a/y is odd or even according as y is positive or negative
  81
  82         14:     a/y is even or odd according as x is positive or negative
  83
  84         15:     a/y is odd or even according as x is positive or negative
  85
  86     The value of y and lowest 5 bits of z are used in the same way as
  87     y and z in appr(x, y, z): for either the real or imaginary part
  88     of the square root, if this is a multiple of y, it is returned
  89     exactly; otherwise the value returned for the part is the
  90     multiple of y nearest below or nearest above the true value.
  91     For z = 0, the remainder has the sign of y;  changing bit 0
  92     changes to the other possibility; for z = 2, the remainder has the
  93     sign of the true value, i.e. the rounding is towards zero; for
  94     z = 4, the remainder is always positive, i.e. the rounding is down;
  95     for z = 8, the rounding is to the nearest even multiple of y;
  96     if 16 <= z < 32, the rounding is to the nearest multiple of y when
  97     this is uniquely determined and otherwise is as if z were replaced
  98     by z - 16.
  99
 100     With the initial default values, 1e-20 for epsilon() and 24 for
 101     config("sqrt"), sqrt(x) returns the principal square root with
 102     real and imaginary parts rounded to 20 decimal places, the 20th
 103     decimal digit being even when the part differs from a multiple
 104     of 1e-20 by 1/2 * 1e-20.
 105
 106
 107 EXAMPLE
 108     > eps = 1e-4
 109     > print sqrt(4,eps,0), sqrt(4,eps,64), sqrt(8i,eps,0), sqrt(8i, eps, 64)
 110     2 -2 2+2i -2-2i
 111
 112     > print sqrt(2,eps,0), sqrt(2,eps,1), sqrt(2,eps,24)
 113     1.4142 1.4143 1.4142
 114
 115     > x = 1.2345678^2
 116     > print sqrt(x,eps,24), sqrt(x,eps,32), sqrt(x,eps,96)
 117     1.2346 1.2345678 -1.2345678
 118
 119     > print sqrt(.00005^2, eps, 24), sqrt(.00015^2, eps, 24)
 120     0 .0002
 121
 122 LIMITS
 123     none
 124
 125 LINK LIBRARY
 126     COMPLEX *csqrt(COMPLEX *x, NUMBER *ep, long z)
 127     NUMBER *qisqrt(NUMBER *q)
 128     NUMBER *qsqrt(NUMBER *x, NUMBER *ep, long z)
 129     FLAG zsqrt(ZVALUE x, ZVALUE *result, long z)
 130
 131 SEE ALSO
 132    appr, epsilon
 133