help/poly

   1 NAME
   2     poly - evaluate a polynomial
   3
   4 SYNOPSIS
   5     poly(a, b, ..., x)
   6     poly(clist, x, y, ...)
   7
   8 TYPES
   9     For first case:
  10
  11     a, b, ...   Arithmetic
  12
  13     x           Arithmetic
  14
  15     return      Depends on argument types
  16
  17     For second case:
  18
  19     clist       List of coefficients
  20
  21     x, y, ...   Coefficients
  22
  23     return      Depends on argument types
  24
  25     Here an arithmetic type is one for which the required + and *
  26     operations are defined, e.g. real or complex numbers or square
  27     matrices of the same size.  A coefficient is either of arithmetic
  28     type or a list of coefficients.
  29
  30 DESCRIPTION
  31     If the first argument is not a list, and the necessary operations are
  32     defined:
  33
  34         poly(a_0, a_1, ..., a_n, x)
  35
  36      returns the value of:
  37
  38         a_n + (a_n-1 + ... + (a_1 + a_0 * x) * x ...) * x
  39
  40     If the coefficients a_0, a_1, ..., a_n and x are elements of a
  41     commutative ring, e.g. if the coefficients and x are real or complex
  42     numbers, this is the value of the polynomial:
  43
  44         a_0 * x^n + a_1 * x^(n-1) + ... + a_(n-1) * x + a_n.
  45
  46     For other structures (e.g. if addition is not commutative),
  47     the order of operations may be relevant.
  48
  49     In particular:
  50
  51         poly(a, x) returns the value of a.
  52
  53         poly(a, b, x) returns the value of b + a * x
  54
  55         poly(a, b, c, x) returns the value of c + (b + a * x) * x
  56
  57
  58     If the first argument is a list as if defined by:
  59
  60         clist = list(a_0, a_1, ..., a_n)
  61
  62     and the coefficients a_i and x are are of arithmetic type,
  63     poly(clist, x) returns:
  64
  65         a_0 + (a_1 + (a_2 + ... + a_n * x) * x)
  66
  67     which for a commutative ring, expands to:
  68
  69         a_0 + a_1 * x + ... + a_n * x^n.
  70
  71     If clist is the empty list, the value returned is the number 0.
  72
  73     Note that the order of the coefficients for the list case is the
  74     reverse of that for the non-list case.
  75
  76     If one or more elements of clist is a list and there are more than
  77     one arithmetic arguments x, y, ..., the coefficient corresponding
  78     to such an element is the value of poly for that list and the next
  79     argument in x, y, ...  For example:
  80
  81         poly(list(list(a,b,c), list(d,e), f), x, y)
  82
  83     returns:
  84
  85          (a + b * y + c * y^2) + (d + e * y) * x + f * x^2.
  86
  87     Arguments in excess of those required for clist are ignored, e.g.:
  88
  89         poly(list(1,2,3), x, y)
  90
  91     returns the same as poly(list(1,2,3), x).  If the number of
  92     arguments is less than greatest depth of lists in clist, the
  93     "missing" arguments are deemed to be zero.  E.g.:
  94
  95         poly(list(list(1,2), list(3,4), 5), x)
  96
  97     returns the same as:
  98
  99         poly(list(1, 3, 5), x).
 100
 101     If in the clist case, one or more of x, y, ... is a list, the
 102     arguments to be applied to the polynomial are the successive
 103     non-list values in the list or sublists.  For example, if the x_i
 104     are not lists:
 105
 106         poly(clist, list(x_0, x_1), x_2, list(list(x_3, x_4), x_5))
 107
 108     returns the same as:
 109
 110         poly(clist, x_0, x_1, x_2, x_3, x_4, x_5).
 111
 112 EXAMPLE
 113     > print poly(2, 3, 5, 7), poly(list(5, 3, 2), 7), 5 + 3 * 7 + 2 * 7^2
 114     124 124 124
 115
 116     > mat A[2,2] = {1,2,3,4}
 117     > mat I[2,2] = {1,0,0,1}
 118     print poly(2 * I, 3 * I, 5 * I, A)
 119
 120     mat [2,2] (4 elements, 4 nonzero)
 121       [0,0] = 22
 122       [0,1] = 26
 123       [1,0] = 39
 124       [1,1] = 61
 125
 126     > P = list(list(0,0,1), list(0,2), 3); x = 4; y = 5
 127     > print poly(P,x,y), poly(P, list(x,y)), y^2 + 2 * y * x + 3 * x^2
 128     113 113 113
 129
 130 LIMITS
 131     The number of arguments is not to exceed 100
 132
 133 LINK LIBRARY
 134     BOOL evalpoly(LIST *clist, LISTELEM *x, VALUE *result);
 135
 136 SEE ALSO
 137     XXX - fill in
 138