doc/info/Polynomials.texi

   1 @c FOR THE FUNCTIONS WHICH RETURN A CRE, BE SURE TO MENTION THAT
   2 @menu
   3 * Introduction to Polynomials::
   4 * Functions and Variables for Polynomials::
   5 @end menu
   6
   7 @c -----------------------------------------------------------------------------
   8 @node Introduction to Polynomials, Functions and Variables for Polynomials
   9 @section Introduction to Polynomials
  10 @c -----------------------------------------------------------------------------
  11
  12 Polynomials are stored in Maxima either in General Form or as Canonical
  13 Rational Expressions (CRE) form. The latter is a standard form, and is
  14 used internally by operations such as @mref{factor}, @mref{ratsimp}, and
  15 so on.
  16
  17 Canonical Rational Expressions constitute a kind of representation
  18 which is especially suitable for expanded polynomials and rational
  19 functions (as well as for partially factored polynomials and rational
  20 functions when @mref{ratfac} is set to @code{true}). In this CRE form an
  21 ordering of variables (from most to least main) is assumed for each
  22 expression.
  23
  24 Polynomials are represented recursively by a list consisting of the main
  25 variable followed by a series of pairs of expressions, one for each term
  26 of the polynomial. The first member of each pair is the exponent of the
  27 main variable in that term and the second member is the coefficient of
  28 that term which could be a number or a polynomial in another variable
  29 again represented in this form. Thus the principal part of the CRE form
  30 of @code{3*x^2-1} is @code{(X 2 3 0 -1)} and that of @code{2*x*y+x-3}
  31 is @code{(Y 1 (X 1 2) 0 (X 1 1 0 -3))} assuming @code{y} is the main
  32 variable, and is @code{(X 1 (Y 1 2 0 1) 0 -3)} assuming @code{x} is the
  33 main variable. "Main"-ness is usually determined by reverse alphabetical
  34 order.
  35
  36 The "variables" of a CRE expression needn't be atomic. In fact any
  37 subexpression whose main operator is not @code{+}, @code{-}, @code{*},
  38 @code{/} or @code{^} with integer power will be considered a "variable"
  39 of the expression (in CRE form) in which it occurs. For example the CRE
  40 variables of the expression @code{x+sin(x+1)+2*sqrt(x)+1} are @code{x},
  41 @code{sqrt(X)}, and @code{sin(x+1)}. If the user does not specify an
  42 ordering of variables by using the @mref{ratvars} function Maxima will
  43 choose an alphabetic one.
  44
  45 In general, CRE's represent rational expressions, that is, ratios of
  46 polynomials, where the numerator and denominator have no common factors,
  47 and the denominator is positive. The internal form is essentially a pair
  48 of polynomials (the numerator and denominator) preceded by the variable
  49 ordering list. If an expression to be displayed is in CRE form or if it
  50 contains any subexpressions in CRE form, the symbol @code{/R/} will follow the
  51 line label.
  52
  53 @c TODO: An example of some code that yields the /R/ form.
  54
  55 See the @mref{rat} function for converting an expression to CRE form.
  56
  57 An extended CRE form is used for the representation of Taylor
  58 series. The notion of a rational expression is extended so that the
  59 exponents of the variables can be positive or negative rational numbers
  60 rather than just positive integers and the coefficients can themselves
  61 be rational expressions as described above rather than just polynomials.
  62 These are represented internally by a recursive polynomial form which is
  63 similar to and is a generalization of CRE form, but carries additional
  64 information such as the degree of truncation. As with CRE form, the
  65 symbol @code{/T/} follows the line label of such expressions.
  66
  67 @c TODO: An example of some code that yields the /T/ form.
  68
  69 @opencatbox{Categories:}
  70 @category{Polynomials}
  71 @category{Rational expressions}
  72 @closecatbox
  73
  74 @c end concepts Polynomials
  75
  76 @c -----------------------------------------------------------------------------
  77 @node Functions and Variables for Polynomials,  , Introduction to Polynomials
  78 @section Functions and Variables for Polynomials
  79 @c -----------------------------------------------------------------------------
  80
  81 @c -----------------------------------------------------------------------------
  82 @anchor{algebraic}
  83 @defvr {Option variable} algebraic
  84 Default value: @code{false}
  85
  86 @code{algebraic} must be set to @code{true} in order for the simplification of
  87 algebraic integers to take effect.
  88
  89 @opencatbox{Categories:}
  90 @category{Simplification flags and variables}
  91 @closecatbox
  92 @end defvr
  93
  94 @anchor{berlefact}
  95 @c -----------------------------------------------------------------------------
  96 @defvr {Option variable} berlefact
  97 Default value: @code{true}
  98
  99 When @code{berlefact} is @code{false} then the Kronecker factoring
 100 algorithm will be used otherwise the Berlekamp algorithm, which is the
 101 default, will be used.
 102
 103 @opencatbox{Categories:}
 104 @category{Polynomials}
 105 @closecatbox
 106 @end defvr
 107
 108 @c WHAT IS THIS ABOUT EXACTLY ??
 109
 110 @c -----------------------------------------------------------------------------
 111 @anchor{bezout}
 112 @deffn {Function} bezout (@var{p1}, @var{p2}, @var{x})
 113
 114 an alternative to the @mref{resultant} command.  It
 115 returns a matrix.  @code{determinant} of this matrix is the desired resultant.
 116
 117 Examples:
 118
 119 @c ===beg===
 120 @c bezout(a*x+b, c*x^2+d, x);
 121 @c determinant(%);
 122 @c resultant(a*x+b, c*x^2+d, x);
 123 @c ===end===
 124 @example
 125 (%i1) bezout(a*x+b, c*x^2+d, x);
 126                          [ b c  - a d ]
 127 (%o1)                    [            ]
 128                          [  a     b   ]
 129 (%i2) determinant(%);
 130                             2      2
 131 (%o2)                      a  d + b  c
 132 (%i3) resultant(a*x+b, c*x^2+d, x);
 133                             2      2
 134 (%o3)                      a  d + b  c
 135 @end example
 136 @opencatbox{Categories:}
 137 @category{Polynomials}
 138 @closecatbox
 139 @end deffn
 140
 141 @c REWORD THIS ITEM -- COULD BE MORE CONCISE
 142
 143 @c -----------------------------------------------------------------------------
 144 @anchor{bothcoef}
 145 @deffn {Function} bothcoef (@var{expr}, @var{x})
 146
 147 Returns a list whose first member is the coefficient of @var{x} in @var{expr}
 148 (as found by @code{ratcoef} if @var{expr} is in CRE form
 149 otherwise by @code{coeff}) and whose second member is the remaining part of
 150 @var{expr}.  That is, @code{[A, B]} where @code{@var{expr} = A*@var{x} + B}.
 151
 152 Example:
 153
 154 @c ===beg===
 155 @c islinear (expr, x) := block ([c],
 156 @c         c: bothcoef (rat (expr, x), x),
 157 @c         is (freeof (x, c) and c[1] # 0))$
 158 @c islinear ((r^2 - (x - r)^2)/x, x);
 159 @c ===end===
 160 @example
 161 (%i1) islinear (expr, x) := block ([c],
 162         c: bothcoef (rat (expr, x), x),
 163         is (freeof (x, c) and c[1] # 0))$
 164 (%i2) islinear ((r^2 - (x - r)^2)/x, x);
 165 (%o2)                         true
 166 @end example
 167
 168 @opencatbox{Categories:}
 169 @category{Polynomials}
 170 @closecatbox
 171 @end deffn
 172
 173 @c -----------------------------------------------------------------------------
 174 @deffn  {Function} coeff @
 175 @fname{coeff} (@var{expr}, @var{x}, @var{n}) @
 176 @fname{coeff} (@var{expr}, @var{x})
 177
 178 Returns the coefficient of @code{@var{x}^@var{n}} in @var{expr},
 179 where @var{expr} is a polynomial or a monomial term in @var{x}.
 180 Other than @mref{ratcoef} @code{coeff} is a strictly syntactical
 181 operation and will only find literal instances of
 182 @code{@var{x}^@var{n}} in the internal representation of @var{expr}.
 183
 184 @code{coeff(@var{expr}, @var{x}^@var{n})} is equivalent
 185 to @code{coeff(@var{expr}, @var{x}, @var{n})}.
 186 @code{coeff(@var{expr}, @var{x}, 0)} returns the remainder of @var{expr}
 187 which is free of @var{x}.
 188 If omitted, @var{n} is assumed to be 1.
 189
 190 @var{x} may be a simple variable or a subscripted variable,
 191 or a subexpression of @var{expr} which
 192 comprises an operator and all of its arguments.
 193
 194 It may be possible to compute coefficients of expressions which are equivalent
 195 to @var{expr} by applying @code{expand} or @code{factor}.  @code{coeff} itself
 196 does not apply @code{expand} or @code{factor} or any other function.
 197
 198 @code{coeff} distributes over lists, matrices, and equations.
 199
 200 See also @mrefdot{ratcoef}
 201
 202 Examples:
 203
 204 @code{coeff} returns the coefficient @code{@var{x}^@var{n}} in @var{expr}.
 205
 206 @c ===beg===
 207 @c coeff (b^3*a^3 + b^2*a^2 + b*a + 1, a^3);
 208 @c ===end===
 209 @example
 210 @group
 211 (%i1) coeff (b^3*a^3 + b^2*a^2 + b*a + 1, a^3);
 212                                 3
 213 (%o1)                          b
 214 @end group
 215 @end example
 216
 217 @code{coeff(@var{expr}, @var{x}^@var{n})} is equivalent
 218 to @code{coeff(@var{expr}, @var{x}, @var{n})}.
 219
 220 @c ===beg===
 221 @c coeff (c[4]*z^4 - c[3]*z^3 - c[2]*z^2 + c[1]*z, z, 3);
 222 @c coeff (c[4]*z^4 - c[3]*z^3 - c[2]*z^2 + c[1]*z, z^3);
 223 @c ===end===
 224 @example
 225 @group
 226 (%i1) coeff (c[4]*z^4 - c[3]*z^3 - c[2]*z^2 + c[1]*z, z, 3);
 227 (%o1)                         - c
 228                                  3
 229 @end group
 230 @group
 231 (%i2) coeff (c[4]*z^4 - c[3]*z^3 - c[2]*z^2 + c[1]*z, z^3);
 232 (%o2)                         - c
 233                                  3
 234 @end group
 235 @end example
 236
 237 @code{coeff(@var{expr}, @var{x}, 0)} returns the remainder of @var{expr}
 238 which is free of @var{x}.
 239
 240 @c ===beg===
 241 @c coeff (a*u + b^2*u^2 + c^3*u^3, b, 0);
 242 @c ===end===
 243 @example
 244 @group
 245 (%i1) coeff (a*u + b^2*u^2 + c^3*u^3, b, 0);
 246                             3  3
 247 (%o1)                      c  u  + a u
 248 @end group
 249 @end example
 250
 251 @var{x} may be a simple variable or a subscripted variable,
 252 or a subexpression of @var{expr} which
 253 comprises an operator and all of its arguments.
 254
 255 @c ===beg===
 256 @c coeff (h^4 - 2*%pi*h^2 + 1, h, 2);
 257 @c coeff (v[1]^4 - 2*%pi*v[1]^2 + 1, v[1], 2);
 258 @c coeff (sin(1+x)*sin(x) + sin(1+x)^3*sin(x)^3, sin(1+x)^3);
 259 @c coeff ((d - a)^2*(b + c)^3 + (a + b)^4*(c - d), a + b, 4);
 260 @c ===end===
 261 @example
 262 @group
 263 (%i1) coeff (h^4 - 2*%pi*h^2 + 1, h, 2);
 264 (%o1)                        - 2 %pi
 265 @end group
 266 @group
 267 (%i2) coeff (v[1]^4 - 2*%pi*v[1]^2 + 1, v[1], 2);
 268 (%o2)                        - 2 %pi
 269 @end group
 270 @group
 271 (%i3) coeff (sin(1+x)*sin(x) + sin(1+x)^3*sin(x)^3, sin(1+x)^3);
 272                                 3
 273 (%o3)                        sin (x)
 274 @end group
 275 @group
 276 (%i4) coeff ((d - a)^2*(b + c)^3 + (a + b)^4*(c - d), a + b, 4);
 277 (%o4)                         c - d
 278 @end group
 279 @end example
 280
 281 @code{coeff} itself does not apply @code{expand} or @code{factor} or any other
 282 function.
 283
 284 @c ===beg===
 285 @c coeff (c*(a + b)^3, a);
 286 @c expand (c*(a + b)^3);
 287 @c coeff (%, a);
 288 @c coeff (b^3*c + 3*a*b^2*c + 3*a^2*b*c + a^3*c, (a + b)^3);
 289 @c factor (b^3*c + 3*a*b^2*c + 3*a^2*b*c + a^3*c);
 290 @c coeff (%, (a + b)^3);
 291 @c ===end===
 292 @example
 293 @group
 294 (%i1) coeff (c*(a + b)^3, a);
 295 (%o1)                           0
 296 @end group
 297 @group
 298 (%i2) expand (c*(a + b)^3);
 299                  3          2        2        3
 300 (%o2)           b  c + 3 a b  c + 3 a  b c + a  c
 301 @end group
 302 @group
 303 (%i3) coeff (%, a);
 304                                 2
 305 (%o3)                        3 b  c
 306 @end group
 307 @group
 308 (%i4) coeff (b^3*c + 3*a*b^2*c + 3*a^2*b*c + a^3*c, (a + b)^3);
 309 (%o4)                           0
 310 @end group
 311 @group
 312 (%i5) factor (b^3*c + 3*a*b^2*c + 3*a^2*b*c + a^3*c);
 313                                   3
 314 (%o5)                      (b + a)  c
 315 @end group
 316 @group
 317 (%i6) coeff (%, (a + b)^3);
 318 (%o6)                           c
 319 @end group
 320 @end example
 321
 322 @code{coeff} distributes over lists, matrices, and equations.
 323
 324 @c ===beg===
 325 @c coeff ([4*a, -3*a, 2*a], a);
 326 @c coeff (matrix ([a*x, b*x], [-c*x, -d*x]), x);
 327 @c coeff (a*u - b*v = 7*u + 3*v, u);
 328 @c ===end===
 329 @example
 330 @group
 331 (%i1) coeff ([4*a, -3*a, 2*a], a);
 332 (%o1)                      [4, - 3, 2]
 333 @end group
 334 @group
 335 (%i2) coeff (matrix ([a*x, b*x], [-c*x, -d*x]), x);
 336                           [  a    b  ]
 337 (%o2)                     [          ]
 338                           [ - c  - d ]
 339 @end group
 340 @group
 341 (%i3) coeff (a*u - b*v = 7*u + 3*v, u);
 342 (%o3)                         a = 7
 343 @end group
 344 @end example
 345
 346 @opencatbox{Categories:}
 347 @category{Polynomials}
 348 @closecatbox
 349 @end deffn
 350
 351 @c -----------------------------------------------------------------------------
 352 @anchor{content}
 353 @deffn {Function} content (@var{p_1}, @var{x_1}, @dots{}, @var{x_n})
 354
 355 Returns a list whose first element is
 356 the greatest common divisor of the coefficients of the terms of the
 357 polynomial @var{p_1} in the variable @var{x_n} (this is the content) and whose
 358 second element is the polynomial @var{p_1} divided by the content.
 359 @c APPEARS TO WORK AS ADVERTISED -- ONLY x_n HAS ANY EFFECT ON THE RESULT
 360 @c WHAT ARE THE OTHER VARIABLES x_1 THROUGH x_{n-1} FOR ??
 361
 362 Examples:
 363
 364 @c ===beg===
 365 @c content (2*x*y + 4*x^2*y^2, y);
 366 @c ===end===
 367 @example
 368 (%i1) content (2*x*y + 4*x^2*y^2, y);
 369 @group
 370                                    2
 371 (%o1)                   [2 x, 2 x y  + y]
 372 @end group
 373 @end example
 374
 375 @opencatbox{Categories:}
 376 @category{Polynomials}
 377 @closecatbox
 378 @end deffn
 379
 380 @c -----------------------------------------------------------------------------
 381 @anchor{denom}
 382 @deffn {Function} denom (@var{expr})
 383
 384 Returns the denominator of the rational expression @var{expr}.
 385
 386 See also @mref{num}
 387
 388 @c ===beg===
 389 @c g1:(x+2)*(x+1)/((x+3)^2);
 390 @c denom(g1);
 391 @c g2:sin(x)/10*cos(x)/y;
 392 @c denom(g2);
 393 @c ===end===
 394 @example
 395 @group
 396 (%i1) g1:(x+2)*(x+1)/((x+3)^2);
 397                          (x + 1) (x + 2)
 398 (%o1)                    ---------------
 399                                    2
 400                             (x + 3)
 401 @end group
 402 @group
 403 (%i2) denom(g1);
 404                                    2
 405 (%o2)                       (x + 3)
 406 @end group
 407 @group
 408 (%i3) g2:sin(x)/10*cos(x)/y;
 409                           cos(x) sin(x)
 410 (%o3)                     -------------
 411                               10 y
 412 @end group
 413 @group
 414 (%i4) denom(g2);
 415 (%o4)                         10 y
 416 @end group
 417 @end example
 418
 419 @opencatbox{Categories:}
 420 @category{Expressions}
 421 @closecatbox
 422 @end deffn
 423
 424 @c -----------------------------------------------------------------------------
 425 @anchor{divide}
 426 @deffn {Function} divide (@var{p_1}, @var{p_2}, @var{x_1}, @dots{}, @var{x_n})
 427
 428 computes the quotient and remainder
 429 of the polynomial @var{p_1} divided by the polynomial @var{p_2}, in a main
 430 polynomial variable, @var{x_n}.
 431 @c SPELL OUT THE PURPOSE OF THE OTHER VARIABLES
 432 The other variables are as in the @code{ratvars} function.
 433 The result is a list whose first element is the quotient
 434 and whose second element is the remainder.
 435
 436 Examples:
 437
 438 @c ===beg===
 439 @c divide (x + y, x - y, x);
 440 @c divide (x + y, x - y);
 441 @c ===end===
 442 @example
 443 (%i1) divide (x + y, x - y, x);
 444 (%o1)                       [1, 2 y]
 445 (%i2) divide (x + y, x - y);
 446 (%o2)                      [- 1, 2 x]
 447 @end example
 448
 449 @noindent
 450 Note that @code{y} is the main variable in the second example.
 451
 452 @opencatbox{Categories:}
 453 @category{Polynomials}
 454 @closecatbox
 455 @end deffn
 456
 457 @anchor{eliminate}
 458 @c -----------------------------------------------------------------------------
 459 @deffn {Function} eliminate ([@var{eqn_1}, @dots{}, @var{eqn_n}], [@var{x_1}, @dots{}, @var{x_k}])
 460
 461 Eliminates variables from equations (or expressions assumed equal to zero) by
 462 taking successive resultants. This returns a list of @code{@var{n} - @var{k}}
 463 expressions with the @var{k} variables @var{x_1}, @dots{}, @var{x_k} eliminated.
 464 First @var{x_1} is eliminated yielding @code{@var{n} - 1} expressions, then
 465 @code{x_2} is eliminated, etc.  If @code{@var{k} = @var{n}} then a single
 466 expression in a list is returned free of the variables @var{x_1}, @dots{},
 467 @var{x_k}.  In this case @code{solve} is called to solve the last resultant for
 468 the last variable.
 469
 470 Example:
 471
 472 @c ===beg===
 473 @c expr1: 2*x^2 + y*x + z;
 474 @c expr2: 3*x + 5*y - z - 1;
 475 @c expr3: z^2 + x - y^2 + 5;
 476 @c eliminate ([expr3, expr2, expr1], [y, z]);
 477 @c ===end===
 478 @example
 479 (%i1) expr1: 2*x^2 + y*x + z;
 480                                       2
 481 (%o1)                    z + x y + 2 x
 482 (%i2) expr2: 3*x + 5*y - z - 1;
 483 (%o2)                  - z + 5 y + 3 x - 1
 484 (%i3) expr3: z^2 + x - y^2 + 5;
 485                           2    2
 486 (%o3)                    z  - y  + x + 5
 487 (%i4) eliminate ([expr3, expr2, expr1], [y, z]);
 488              8         7         6          5          4
 489 (%o4) [7425 x  - 1170 x  + 1299 x  + 12076 x  + 22887 x
 490
 491                                     3         2
 492                             - 5154 x  - 1291 x  + 7688 x + 15376]
 493 @end example
 494
 495 @opencatbox{Categories:}
 496 @category{Polynomials}
 497 @category{Algebraic equations}
 498 @closecatbox
 499 @end deffn
 500
 501 @c -----------------------------------------------------------------------------
 502 @anchor{ezgcd}
 503 @deffn {Function} ezgcd (@var{p_1}, @var{p_2}, @var{p_3}, @dots{})
 504
 505 Returns a list whose first element is the greatest common divisor of the
 506 polynomials @var{p_1}, @var{p_2}, @var{p_3}, @dots{} and whose remaining
 507 elements are the polynomials divided by the greatest common divisor.  This
 508 always uses the @code{ezgcd} algorithm.
 509
 510 See also @mrefcomma{gcd} @mrefcomma{gcdex} @mrefcomma{gcdivide} and
 511 @mrefdot{poly_gcd}
 512
 513 Examples:
 514
 515 The three polynomials have the greatest common divisor @code{2*x-3}.  The
 516 gcd is first calculated with the function @code{gcd} and then with the function
 517 @code{ezgcd}.
 518
 519 @c ===beg===
 520 @c p1 : 6*x^3-17*x^2+14*x-3;
 521 @c p2 : 4*x^4-14*x^3+12*x^2+2*x-3;
 522 @c p3 : -8*x^3+14*x^2-x-3;
 523 @c gcd(p1, gcd(p2, p3));
 524 @c ezgcd(p1, p2, p3);
 525 @c ===end===
 526 @example
 527 (%i1) p1 : 6*x^3-17*x^2+14*x-3;
 528                         3       2
 529 (%o1)                6 x  - 17 x  + 14 x - 3
 530 (%i2) p2 : 4*x^4-14*x^3+12*x^2+2*x-3;
 531                     4       3       2
 532 (%o2)            4 x  - 14 x  + 12 x  + 2 x - 3
 533 (%i3) p3 : -8*x^3+14*x^2-x-3;
 534                           3       2
 535 (%o3)                - 8 x  + 14 x  - x - 3
 536
 537 (%i4) gcd(p1, gcd(p2, p3));
 538 (%o4)                        2 x - 3
 539
 540 (%i5) ezgcd(p1, p2, p3);
 541                    2               3      2           2
 542 (%o5) [2 x - 3, 3 x  - 4 x + 1, 2 x  - 4 x  + 1, - 4 x  + x + 1]
 543 @end example
 544
 545 @opencatbox{Categories:}
 546 @category{Polynomials}
 547 @closecatbox
 548 @end deffn
 549
 550 @c -----------------------------------------------------------------------------
 551 @defvr {Option variable} facexpand
 552 Default value: @code{true}
 553
 554 @code{facexpand} controls whether the irreducible factors returned by
 555 @code{factor} are in expanded (the default) or recursive (normal CRE) form.
 556
 557 @opencatbox{Categories:}
 558 @category{Polynomials}
 559 @closecatbox
 560 @end defvr
 561
 562 @c -----------------------------------------------------------------------------
 563 @anchor{factor}
 564 @deffn  {Function} factor @
 565 @fname{factor} (@var{expr}) @
 566 @fname{factor} (@var{expr}, @var{p})
 567
 568 Factors the expression @var{expr}, containing any number of variables or
 569 functions, into factors irreducible over the integers.
 570 @code{factor (@var{expr}, @var{p})} factors @var{expr} over the field of
 571 rationals with an element adjoined whose minimum polynomial is @var{p}.
 572
 573 @code{factor} uses @mref{ifactors} function for factoring integers.
 574
 575 @mref{factorflag} if @code{false} suppresses the factoring of integer factors
 576 of rational expressions.
 577
 578 @mref{dontfactor} may be set to a list of variables with respect to which
 579 factoring is not to occur.  (It is initially empty).  Factoring also
 580 will not take place with respect to any variables which are less
 581 important (using the variable ordering assumed for CRE form) than
 582 those on the @code{dontfactor} list.
 583
 584 @mref{savefactors} if @code{true} causes the factors of an expression which
 585 is a product of factors to be saved by certain functions in order to
 586 speed up later factorizations of expressions containing some of the
 587 same factors.
 588
 589 @mref{berlefact} if @code{false} then the Kronecker factoring algorithm will
 590 be used otherwise the Berlekamp algorithm, which is the default, will
 591 be used.
 592
 593 @mref{intfaclim} if @code{true} maxima will give up factorization of
 594 integers if no factor is found after trial divisions and Pollard's rho
 595 method.  If set to @code{false} (this is the case when the user calls
 596 @code{factor} explicitly), complete factorization of the integer will be
 597 attempted.  The user's setting of @code{intfaclim} is used for internal
 598 calls to @code{factor}.  Thus, @code{intfaclim} may be reset to prevent
 599 Maxima from taking an inordinately long time factoring large integers.
 600
 601 @mref{factor_max_degree} if set to a positive integer @code{n} will
 602 prevent certain polynomials from being factored if their degree in any
 603 variable exceeds @code{n}.
 604
 605 See also @mref{collectterms} and @mref{sqfr}
 606
 607 Examples:
 608
 609 @c ===beg===
 610 @c factor (2^63 - 1);
 611 @c factor (-8*y - 4*x + z^2*(2*y + x));
 612 @c -1 - 2*x - x^2 + y^2 + 2*x*y^2 + x^2*y^2;
 613 @c block ([dontfactor: [x]], factor (%/36/(1 + 2*y + y^2)));
 614 @c factor (1 + %e^(3*x));
 615 @c factor (1 + x^4, a^2 - 2);
 616 @c factor (-y^2*z^2 - x*z^2 + x^2*y^2 + x^3);
 617 @c (2 + x)/(3 + x)/(b + x)/(c + x)^2;
 618 @c ratsimp (%);
 619 @c partfrac (%, x);
 620 @c map ('factor, %);
 621 @c ratsimp ((x^5 - 1)/(x - 1));
 622 @c subst (a, x, %);
 623 @c factor (%th(2), %);
 624 @c factor (1 + x^12);
 625 @c factor (1 + x^99);
 626 @c ===end===
 627 @example
 628 (%i1) factor (2^63 - 1);
 629                     2
 630 (%o1)              7  73 127 337 92737 649657
 631 (%i2) factor (-8*y - 4*x + z^2*(2*y + x));
 632 (%o2)               (2 y + x) (z - 2) (z + 2)
 633 (%i3) -1 - 2*x - x^2 + y^2 + 2*x*y^2 + x^2*y^2;
 634                 2  2        2    2    2
 635 (%o3)          x  y  + 2 x y  + y  - x  - 2 x - 1
 636 (%i4) block ([dontfactor: [x]], factor (%/36/(1 + 2*y + y^2)));
 637 @group
 638                        2
 639                      (x  + 2 x + 1) (y - 1)
 640 (%o4)                ----------------------
 641                            36 (y + 1)
 642 @end group
 643 (%i5) factor (1 + %e^(3*x));
 644                       x         2 x     x
 645 (%o5)              (%e  + 1) (%e    - %e  + 1)
 646 (%i6) factor (1 + x^4, a^2 - 2);
 647                     2              2
 648 (%o6)             (x  - a x + 1) (x  + a x + 1)
 649 (%i7) factor (-y^2*z^2 - x*z^2 + x^2*y^2 + x^3);
 650                        2
 651 (%o7)              - (y  + x) (z - x) (z + x)
 652 (%i8) (2 + x)/(3 + x)/(b + x)/(c + x)^2;
 653                              x + 2
 654 (%o8)               ------------------------
 655                                            2
 656                     (x + 3) (x + b) (x + c)
 657 (%i9) ratsimp (%);
 658 @group
 659                 4                  3
 660 (%o9) (x + 2)/(x  + (2 c + b + 3) x
 661
 662      2                       2             2                   2
 663  + (c  + (2 b + 6) c + 3 b) x  + ((b + 3) c  + 6 b c) x + 3 b c )
 664 @end group
 665 (%i10) partfrac (%, x);
 666            2                   4                3
 667 (%o10) - (c  - 4 c - b + 6)/((c  + (- 2 b - 6) c
 668
 669      2              2         2                2
 670  + (b  + 12 b + 9) c  + (- 6 b  - 18 b) c + 9 b ) (x + c))
 671
 672                  c - 2
 673  - ---------------------------------
 674      2                             2
 675    (c  + (- b - 3) c + 3 b) (x + c)
 676
 677                          b - 2
 678  + -------------------------------------------------
 679              2             2       3      2
 680    ((b - 3) c  + (6 b - 2 b ) c + b  - 3 b ) (x + b)
 681
 682                          1
 683  - ----------------------------------------------
 684              2
 685    ((b - 3) c  + (18 - 6 b) c + 9 b - 27) (x + 3)
 686 (%i11) map ('factor, %);
 687 @group
 688               2
 689              c  - 4 c - b + 6                 c - 2
 690 (%o11) - ------------------------- - ------------------------
 691                 2        2                                  2
 692          (c - 3)  (c - b)  (x + c)   (c - 3) (c - b) (x + c)
 693
 694                        b - 2                        1
 695             + ------------------------ - ------------------------
 696                              2                          2
 697               (b - 3) (c - b)  (x + b)   (b - 3) (c - 3)  (x + 3)
 698 @end group
 699 (%i12) ratsimp ((x^5 - 1)/(x - 1));
 700                        4    3    2
 701 (%o12)                x  + x  + x  + x + 1
 702 (%i13) subst (a, x, %);
 703                        4    3    2
 704 (%o13)                a  + a  + a  + a + 1
 705 (%i14) factor (%th(2), %);
 706                        2        3        3    2
 707 (%o14)   (x - a) (x - a ) (x - a ) (x + a  + a  + a + 1)
 708 (%i15) factor (1 + x^12);
 709                        4        8    4
 710 (%o15)               (x  + 1) (x  - x  + 1)
 711 (%i16) factor (1 + x^99);
 712                  2            6    3
 713 (%o16) (x + 1) (x  - x + 1) (x  - x  + 1)
 714
 715    10    9    8    7    6    5    4    3    2
 716  (x   - x  + x  - x  + x  - x  + x  - x  + x  - x + 1)
 717
 718    20    19    17    16    14    13    11    10    9    7    6
 719  (x   + x   - x   - x   + x   + x   - x   - x   - x  + x  + x
 720
 721     4    3            60    57    51    48    42    39    33
 722  - x  - x  + x + 1) (x   + x   - x   - x   + x   + x   - x
 723
 724     30    27    21    18    12    9    3
 725  - x   - x   + x   + x   - x   - x  + x  + 1)
 726 @end example
 727
 728 @opencatbox{Categories:}
 729 @category{Polynomials}
 730 @closecatbox
 731 @end deffn
 732
 733 @anchor{factor_max_degree}
 734
 735
 736 @c -----------------------------------------------------------------------------
 737 @defvr {Option variable} factor_max_degree
 738 Default value: @code{1000}
 739
 740 When factor_max_degree is set to a positive integer @code{n}, it will prevent
 741 Maxima from attempting to factor certain polynomials whose degree in any
 742 variable exceeds @code{n}. If @mref{factor_max_degree_print_warning} is true,
 743 a warning message will be printed. @code{factor_max_degree} can be used to
 744 prevent excessive memory usage and/or computation time and stack overflows.
 745 Note that "obvious" factoring of polynomials such as @code{x^2000+x^2001} to
 746 @code{x^2000*(x+1)} will still take place. To disable this behavior, set
 747 @code{factor_max_degree} to @code{0}.
 748
 749 Example:
 750 @c ===beg===
 751 @c factor_max_degree : 100$
 752 @c factor(x^100-1);
 753 @c factor(x^101-1);
 754 @c ===end===
 755 @example
 756 (%i1) factor_max_degree : 100$
 757 @group
 758 (%i2) factor(x^100-1);
 759                         2        4    3    2
 760 (%o2) (x - 1) (x + 1) (x  + 1) (x  - x  + x  - x + 1)
 761    4    3    2            8    6    4    2
 762  (x  + x  + x  + x + 1) (x  - x  + x  - x  + 1)
 763    20    15    10    5        20    15    10    5
 764  (x   - x   + x   - x  + 1) (x   + x   + x   + x  + 1)
 765    40    30    20    10
 766  (x   - x   + x   - x   + 1)
 767 @end group
 768 @group
 769 (%i3) factor(x^101-1);
 770                                101
 771 Refusing to factor polynomial x    - 1
 772                because its degree exceeds factor_max_degree (100)
 773                              101
 774 (%o3)                       x    - 1
 775 @end group
 776 @end example
 777
 778 See also: @mref{factor_max_degree_print_warning}
 779
 780 @opencatbox{Categories:}
 781 @category{Polynomials}
 782 @closecatbox
 783 @end defvr
 784
 785 @anchor{factor_max_degree_print_warning}
 786 @c -----------------------------------------------------------------------------
 787 @defvr {Option variable} factor_max_degree_print_warning
 788 Default value: @code{true}
 789
 790 When factor_max_degree_print_warning is true, then Maxima will print a
 791 warning message when the factoring of a polynomial is prevented because
 792 its degree exceeds the value of factor_max_degree.
 793
 794 See also: @mref{factor_max_degree}
 795
 796 @opencatbox{Categories:}
 797 @category{Polynomials}
 798 @closecatbox
 799 @end defvr
 800
 801 @anchor{factorflag}
 802 @c -----------------------------------------------------------------------------
 803 @defvr {Option variable} factorflag
 804 Default value: @code{false}
 805
 806 @c WHAT IS THIS ABOUT EXACTLY ??
 807 When @code{factorflag} is @code{false}, suppresses the factoring of
 808 integer factors of rational expressions.
 809
 810 @opencatbox{Categories:}
 811 @category{Polynomials}
 812 @closecatbox
 813 @end defvr
 814
 815 @c -----------------------------------------------------------------------------
 816 @anchor{factorout}
 817 @deffn {Function} factorout (@var{expr}, @var{x_1}, @var{x_2}, @dots{})
 818
 819 Rearranges the sum @var{expr} into a sum of terms of the form
 820 @code{f (@var{x_1}, @var{x_2}, @dots{})*g} where @code{g} is a product of
 821 expressions not containing any @var{x_i} and @code{f} is factored.
 822
 823 Note that the option variable @code{keepfloat} is ignored by @code{factorout}.
 824
 825 Example:
 826
 827 @c ===beg===
 828 @c expand (a*(x+1)*(x-1)*(u+1)^2);
 829 @c factorout(%,x);
 830 @c ===end===
 831 @example
 832 @group
 833 (%i1) expand (a*(x+1)*(x-1)*(u+1)^2);
 834              2  2          2      2      2
 835 (%o1)     a u  x  + 2 a u x  + a x  - a u  - 2 a u - a
 836 @end group
 837 @group
 838 (%i2) factorout(%,x);
 839          2
 840 (%o2) a u  (x - 1) (x + 1) + 2 a u (x - 1) (x + 1)
 841                                               + a (x - 1) (x + 1)
 842 @end group
 843 @end example
 844
 845 @opencatbox{Categories:}
 846 @category{Expressions}
 847 @closecatbox
 848 @end deffn
 849
 850 @c -----------------------------------------------------------------------------
 851 @anchor{factorsum}
 852 @deffn {Function} factorsum (@var{expr})
 853
 854 Tries to group terms in factors of @var{expr} which are sums into groups of
 855 terms such that their sum is factorable.  @code{factorsum} can recover the
 856 result of @code{expand ((x + y)^2 + (z + w)^2)} but it can't recover
 857 @code{expand ((x + 1)^2 + (x + y)^2)} because the terms have variables in
 858 common.
 859
 860 Example:
 861
 862 @c ===beg===
 863 @c expand ((x + 1)*((u + v)^2 + a*(w + z)^2));
 864 @c factorsum (%);
 865 @c ===end===
 866 @example
 867 (%i1) expand ((x + 1)*((u + v)^2 + a*(w + z)^2));
 868            2      2                            2      2
 869 (%o1) a x z  + a z  + 2 a w x z + 2 a w z + a w  x + v  x
 870
 871                                      2        2    2            2
 872                         + 2 u v x + u  x + a w  + v  + 2 u v + u
 873 (%i2) factorsum (%);
 874                                    2          2
 875 (%o2)            (x + 1) (a (z + w)  + (v + u) )
 876 @end example
 877
 878 @opencatbox{Categories:}
 879 @category{Expressions}
 880 @closecatbox
 881 @end deffn
 882
 883 @c -----------------------------------------------------------------------------
 884 @anchor{fasttimes}
 885 @deffn {Function} fasttimes (@var{p_1}, @var{p_2})
 886
 887 Returns the product of the polynomials @var{p_1} and @var{p_2} by using a
 888 special algorithm for multiplication of polynomials.  @code{p_1} and @code{p_2}
 889 should be multivariate, dense, and nearly the same size.  Classical
 890 multiplication is of order @code{n_1 n_2} where
 891 @code{n_1} is the degree of @code{p_1}
 892 and @code{n_2} is the degree of @code{p_2}.
 893 @code{fasttimes} is of order @code{max (n_1, n_2)^1.585}.
 894
 895 @opencatbox{Categories:}
 896 @category{Polynomials}
 897 @closecatbox
 898 @end deffn
 899
 900 @c -----------------------------------------------------------------------------
 901 @anchor{fullratsimp}
 902 @deffn {Function} fullratsimp (@var{expr})
 903
 904 @code{fullratsimp} repeatedly
 905 applies @code{ratsimp} followed by non-rational simplification to an
 906 expression until no further change occurs,
 907 and returns the result.
 908
 909 When non-rational expressions are involved, one call
 910 to @code{ratsimp} followed as is usual by non-rational ("general")
 911 simplification may not be sufficient to return a simplified result.
 912 Sometimes, more than one such call may be necessary.
 913 @code{fullratsimp} makes this process convenient.
 914
 915 @code{fullratsimp (@var{expr}, @var{x_1}, ..., @var{x_n})} takes one or more
 916 arguments similar to @code{ratsimp} and @code{rat}.
 917
 918 Example:
 919
 920 @c ===beg===
 921 @c expr: (x^(a/2) + 1)^2*(x^(a/2) - 1)^2/(x^a - 1);
 922 @c ratsimp (expr);
 923 @c fullratsimp (expr);
 924 @c rat (expr);
 925 @c ===end===
 926 @example
 927 (%i1) expr: (x^(a/2) + 1)^2*(x^(a/2) - 1)^2/(x^a - 1);
 928                        a/2     2   a/2     2
 929                      (x    - 1)  (x    + 1)
 930 (%o1)                -----------------------
 931                               a
 932                              x  - 1
 933 (%i2) ratsimp (expr);
 934                           2 a      a
 935                          x    - 2 x  + 1
 936 (%o2)                    ---------------
 937                               a
 938                              x  - 1
 939 (%i3) fullratsimp (expr);
 940                               a
 941 (%o3)                        x  - 1
 942 (%i4) rat (expr);
 943                        a/2 4       a/2 2
 944                      (x   )  - 2 (x   )  + 1
 945 (%o4)/R/             -----------------------
 946                               a
 947                              x  - 1
 948 @end example
 949
 950 @opencatbox{Categories:}
 951 @category{Simplification functions}
 952 @category{Rational expressions}
 953 @closecatbox
 954 @end deffn
 955
 956 @c -----------------------------------------------------------------------------
 957 @anchor{fullratsubst}
 958 @deffn {Function} fullratsubst (@var{new}, @var{old}, @var{expr}) @
 959 @fname{fullratsubst} (@code{@var{old} = @var{new}}, @var{expr}) @
 960 @fname{fullratsubst} (@code{[ @var{old_1} = @var{new_1}, @dots{}, @var{old_n} = @var{new_n} ]}, @var{expr})
 961
 962 @code{fullratsubst} applies @mref{lratsubst} repeatedly until @var{expr}
 963 stops changing (or @mref{lrats_max_iter} is reached). This function is
 964 useful when the replacement expression and the replaced expression have
 965 one or more variables in common.
 966
 967 @code{fullratsubst} accepts its arguments in the format of
 968 @mref{ratsubst} or @mref{lratsubst}.
 969
 970 @c EXPRESSIONS ADAPTED FROM demo ("lrats")
 971
 972 Examples:
 973
 974 @itemize @bullet
 975 @item
 976 @code{subst} can carry out multiple substitutions.
 977 @code{lratsubst} is analogous to @code{subst}.
 978 @end itemize
 979 @c ===beg===
 980 @c subst ([a = b, c = d], a + c);
 981 @c lratsubst ([a^2 = b, c^2 = d], (a + e)*c*(a + c));
 982 @c ===end===
 983 @example
 984 (%i2) subst ([a = b, c = d], a + c);
 985 (%o2)                         d + b
 986 (%i3) lratsubst ([a^2 = b, c^2 = d], (a + e)*c*(a + c));
 987 (%o3)                (d + a c) e + a d + b c
 988 @end example
 989 @itemize @bullet
 990 @item
 991 If only one substitution is desired, then a single
 992 equation may be given as first argument.
 993 @end itemize
 994 @c ===beg===
 995 @c lratsubst (a^2 = b, a^3);
 996 @c ===end===
 997 @example
 998 (%i4) lratsubst (a^2 = b, a^3);
 999 (%o4)                          a b
1000 @end example
1001 @itemize @bullet
1002 @item
1003 @code{fullratsubst} is equivalent to @code{ratsubst}
1004 except that it recurses until its result stops changing.
1005 @end itemize
1006 @c ===beg===
1007 @c ratsubst (b*a, a^2, a^3);
1008 @c fullratsubst (b*a, a^2, a^3);
1009 @c ===end===
1010 @example
1011 (%i5) ratsubst (b*a, a^2, a^3);
1012                                2
1013 (%o5)                         a  b
1014 (%i6) fullratsubst (b*a, a^2, a^3);
1015                                  2
1016 (%o6)                         a b
1017 @end example
1018 @itemize @bullet
1019 @item
1020 @code{fullratsubst} also accepts a list of equations or a single
1021 equation as first argument.
1022 @end itemize
1023 @c ===beg===
1024 @c fullratsubst ([a^2 = b, b^2 = c, c^2 = a], a^3*b*c);
1025 @c fullratsubst (a^2 = b*a, a^3);
1026 @c ===end===
1027 @example
1028 (%i7) fullratsubst ([a^2 = b, b^2 = c, c^2 = a], a^3*b*c);
1029 (%o7)                           b
1030 (%i8) fullratsubst (a^2 = b*a, a^3);
1031                                  2
1032 (%o8)                         a b
1033 @end example
1034 @itemize @bullet
1035 @item
1036 @code{fullratsubst} catches potential infinite recursions. @ref{lrats_max_iter}.
1037 @end itemize
1038 @c ===beg===
1039 @c fullratsubst (b*a^2, a^2, a^3), lrats_max_iter=15;
1040 @c ===end===
1041 @example
1042 (%i9) fullratsubst (b*a^2, a^2, a^3), lrats_max_iter=15;
1043 Warning: fullratsubst1(substexpr,forexpr,expr): reached maximum iterations of 15 . Increase `lrats_max_iter' to increase this limit.
1044                                      3  15
1045 (%o7)                               a  b
1046 @end example
1047
1048 See also @mref{lrats_max_iter} and @mref{fullratsubstflag}.
1049
1050 @opencatbox{Categories:}
1051 @category{Rational expressions}
1052 @closecatbox
1053 @end deffn
1054
1055 @c FULLRATSUBSTFLAG was undocumented until 2020-01
1056
1057 @c -----------------------------------------------------------------------------
1058 @anchor{fullratsubstflag}
1059 @defvr {Option variable} fullratsubstflag
1060 Default value: @code{false}
1061
1062 An option variable that is set to @code{true} in @mref{fullratsubst}.
1063
1064 @opencatbox{Categories:}
1065 @category{Polynomials}
1066 @category{Rational expressions}
1067 @closecatbox
1068 @end defvr
1069
1070
1071
1072 @c GCD IS A VARIABLE AND A FUNCTION
1073 @c THIS ITEM NEEDS A LOT OF WORK
1074
1075 @c -----------------------------------------------------------------------------
1076 @anchor{gcd}
1077 @deffn {Function} gcd (@var{p_1}, @var{p_2}, @var{x_1}, @dots{})
1078
1079 Returns the greatest common divisor of @var{p_1} and @var{p_2}.  The flag
1080 @code{gcd} determines which algorithm is employed.  Setting @code{gcd} to
1081 @code{ez}, @code{subres}, @code{red}, or @code{spmod} selects the @code{ezgcd},
1082 subresultant @code{prs}, reduced, or modular algorithm, respectively.  If
1083 @code{gcd} @code{false} then @code{gcd (@var{p_1}, @var{p_2}, @var{x})} always
1084 returns 1 for all @var{x}.  Many functions (e.g. @mrefcomma{ratsimp}@w{}
1085 @mrefcomma{factor} etc.) cause gcd's to be taken implicitly.  For homogeneous
1086 polynomials it is recommended that @code{gcd} equal to @code{subres} be used.
1087 To take the gcd when an algebraic is present, e.g.,
1088 @code{gcd (@var{x}^2 - 2*sqrt(2)* @var{x} + 2, @var{x} - sqrt(2))}, the option
1089 variable @mref{algebraic} must be @code{true} and @code{gcd} must not be
1090 @code{ez}.
1091
1092 The @code{gcd} flag, default: @code{spmod}, if @code{false} will also prevent
1093 the greatest common divisor from being taken when expressions are converted to
1094 canonical rational expression (CRE) form.  This will sometimes speed the
1095 calculation if gcds are not required.
1096
1097 See also @mrefcomma{ezgcd} @mrefcomma{gcdex} @mrefcomma{gcdivide} and
1098 @mrefdot{poly_gcd}
1099
1100 Example:
1101
1102 @c ===beg===
1103 @c p1:6*x^3+19*x^2+19*x+6;
1104 @c p2:6*x^5+13*x^4+12*x^3+13*x^2+6*x;
1105 @c gcd(p1, p2);
1106 @c p1/gcd(p1, p2), ratsimp;
1107 @c p2/gcd(p1, p2), ratsimp;
1108 @c ===end===
1109 @example
1110 (%i1) p1:6*x^3+19*x^2+19*x+6;
1111                         3       2
1112 (%o1)                6 x  + 19 x  + 19 x + 6
1113 (%i2) p2:6*x^5+13*x^4+12*x^3+13*x^2+6*x;
1114                   5       4       3       2
1115 (%o2)          6 x  + 13 x  + 12 x  + 13 x  + 6 x
1116 (%i3) gcd(p1, p2);
1117                             2
1118 (%o3)                    6 x  + 13 x + 6
1119 (%i4) p1/gcd(p1, p2), ratsimp;
1120 (%o4)                         x + 1
1121 (%i5) p2/gcd(p1, p2), ratsimp;
1122                               3
1123 (%o5)                        x  + x
1124 @end example
1125
1126 @mref{ezgcd} returns a list whose first element is the greatest common divisor
1127 of the polynomials @var{p_1} and @var{p_2}, and whose remaining elements are
1128 the polynomials divided by the greatest common divisor.
1129
1130 @c ===beg===
1131 @c ezgcd(p1, p2);
1132 @c ===end===
1133 @example
1134 (%i6) ezgcd(p1, p2);
1135                     2                     3
1136 (%o6)           [6 x  + 13 x + 6, x + 1, x  + x]
1137 @end example
1138
1139 @opencatbox{Categories:}
1140 @category{Polynomials}
1141 @category{Rational expressions}
1142 @closecatbox
1143 @end deffn
1144
1145 @c IN NEED OF SERIOUS CLARIFICATION HERE
1146
1147 @c -----------------------------------------------------------------------------
1148 @anchor{gcdex}
1149 @deffn  {Function} gcdex @
1150 @fname{gcdex} (@var{f}, @var{g}) @
1151 @fname{gcdex} (@var{f}, @var{g}, @var{x})
1152
1153 Returns a list @code{[@var{a}, @var{b}, @var{u}]} where @var{u} is the greatest
1154 common divisor (gcd) of @var{f} and @var{g}, and @var{u} is equal to
1155 @code{@var{a} @var{f} + @var{b} @var{g}}.  The arguments @var{f} and @var{g}
1156 should be univariate polynomials, or else polynomials in @var{x} a supplied
1157 main variable since we need to be in a principal ideal domain for this to
1158 work.  The gcd means the gcd regarding @var{f} and @var{g} as univariate
1159 polynomials with coefficients being rational functions in the other variables.
1160
1161 @code{gcdex} implements the Euclidean algorithm, where we have a sequence of
1162 @code{L[i]: [a[i], b[i], r[i]]} which are all perpendicular to @code{[f, g, -1]}
1163 and the next one is built as if @code{q = quotient(r[i]/r[i+1])} then
1164 @code{L[i+2]: L[i] - q L[i+1]}, and it terminates at @code{L[i+1]} when the
1165 remainder @code{r[i+2]} is zero.
1166
1167 The arguments @var{f} and @var{g} can be integers.  For this case the function
1168 @mref{igcdex} is called by @code{gcdex}.
1169
1170 See also @mrefcomma{ezgcd} @mrefcomma{gcd} @mrefcomma{gcdivide} and
1171 @mrefdot{poly_gcd}
1172
1173 Examples:
1174
1175 @c ===beg===
1176 @c gcdex (x^2 + 1, x^3 + 4);
1177 @c % . [x^2 + 1, x^3 + 4, -1];
1178 @c ===end===
1179 @example
1180 @group
1181 (%i1) gcdex (x^2 + 1, x^3 + 4);
1182                        2
1183                       x  + 4 x - 1  x + 4
1184 (%o1)/R/           [- ------------, -----, 1]
1185                            17        17
1186 @end group
1187 @group
1188 (%i2) % . [x^2 + 1, x^3 + 4, -1];
1189 (%o2)/R/                        0
1190 @end group
1191 @end example
1192
1193 @c SORRY FOR BEING DENSE BUT WHAT IS THIS ABOUT EXACTLY
1194 Note that the gcd in the following is @code{1} since we work in @code{k(y)[x]},
1195 not the  @code{y+1} we would expect in @code{k[y, x]}.
1196
1197 @c ===beg===
1198 @c gcdex (x*(y + 1), y^2 - 1, x);
1199 @c ===end===
1200 @example
1201 @group
1202 (%i1) gcdex (x*(y + 1), y^2 - 1, x);
1203                                1
1204 (%o1)/R/                 [0, ------, 1]
1205                               2
1206                              y  - 1
1207 @end group
1208 @end example
1209
1210 @opencatbox{Categories:}
1211 @category{Polynomials}
1212 @category{Rational expressions}
1213 @closecatbox
1214 @end deffn
1215
1216 @c CHOOSE ONE CHARACTERIZATION OF "GAUSSIAN INTEGERS" AND USE IT WHERE GAUSSIAN INTEGERS ARE REFERENCED
1217
1218 @c -----------------------------------------------------------------------------
1219 @anchor{gcfactor}
1220 @deffn {Function} gcfactor (@var{n})
1221
1222 Factors the Gaussian integer @var{n} over the Gaussian integers, i.e., numbers
1223 of the form @code{@var{a} + @var{b} @code{%i}} where @var{a} and @var{b} are
1224 rational integers (i.e.,  ordinary integers).  Factors are normalized by making
1225 @var{a} and @var{b} non-negative.
1226 @c NEED EXAMPLES HERE
1227
1228 @opencatbox{Categories:}
1229 @category{Integers}
1230 @closecatbox
1231 @end deffn
1232
1233 @c CHOOSE ONE CHARACTERIZATION OF "GAUSSIAN INTEGERS" AND USE IT WHERE GAUSSIAN INTEGERS ARE REFERENCED
1234
1235 @c -----------------------------------------------------------------------------
1236 @anchor{gfactor}
1237 @deffn {Function} gfactor (@var{expr})
1238
1239 Factors the polynomial @var{expr} over the Gaussian integers
1240 (that is, the integers with the imaginary unit @code{%i} adjoined).
1241 @c "This is like" -- IS IT THE SAME OR NOT ??
1242 This is like @code{factor (@var{expr}, @var{a}^2+1)} where @var{a} is @code{%i}.
1243
1244 Example:
1245
1246 @c ===beg===
1247 @c gfactor (x^4 - 1);
1248 @c ===end===
1249 @example
1250 (%i1) gfactor (x^4 - 1);
1251 (%o1)           (x - 1) (x + 1) (x - %i) (x + %i)
1252 @end example
1253
1254 @opencatbox{Categories:}
1255 @category{Polynomials}
1256 @closecatbox
1257 @end deffn
1258
1259 @c DESCRIBE THIS INDEPENDENTLY OF factorsum
1260 @c THIS ITEM NEEDS MORE WORK
1261
1262 @c -----------------------------------------------------------------------------
1263 @anchor{gfactorsum}
1264 @deffn {Function} gfactorsum (@var{expr})
1265
1266 is similar to @code{factorsum} but applies @code{gfactor} instead
1267 of @code{factor}.
1268
1269 @opencatbox{Categories:}
1270 @category{Expressions}
1271 @closecatbox
1272 @end deffn
1273
1274 @c -----------------------------------------------------------------------------
1275 @anchor{hipow}
1276 @deffn {Function} hipow (@var{expr}, @var{x})
1277
1278 Returns the highest explicit exponent of @var{x} in @var{expr}.
1279 @var{x} may be a variable or a general expression.
1280 If @var{x} does not appear in @var{expr},
1281 @code{hipow} returns @code{0}.
1282
1283 @code{hipow} does not consider expressions equivalent to @code{expr}.  In
1284 particular, @code{hipow} does not expand @code{expr}, so
1285 @code{hipow (@var{expr}, @var{x})} and
1286 @code{hipow (expand (@var{expr}, @var{x}))} may yield different results.
1287
1288 Examples:
1289
1290 @c ===beg===
1291 @c hipow (y^3 * x^2 + x * y^4, x);
1292 @c hipow ((x + y)^5, x);
1293 @c hipow (expand ((x + y)^5), x);
1294 @c hipow ((x + y)^5, x + y);
1295 @c hipow (expand ((x + y)^5), x + y);
1296 @c ===end===
1297 @example
1298 (%i1) hipow (y^3 * x^2 + x * y^4, x);
1299 (%o1)                           2
1300 (%i2) hipow ((x + y)^5, x);
1301 (%o2)                           1
1302 (%i3) hipow (expand ((x + y)^5), x);
1303 (%o3)                           5
1304 (%i4) hipow ((x + y)^5, x + y);
1305 (%o4)                           5
1306 (%i5) hipow (expand ((x + y)^5), x + y);
1307 (%o5)                           0
1308 @end example
1309
1310 @opencatbox{Categories:}
1311 @category{Expressions}
1312 @closecatbox
1313 @end deffn
1314
1315 @c I SUSPECT THE FOLLOWING TEXT IS OUTDATED DUE TO CHANGES IN INTEGER FACTORING CODE
1316
1317 @anchor{intfaclim}
1318 @c -----------------------------------------------------------------------------
1319 @defvr {Option variable} intfaclim
1320 Default value: true
1321
1322 If @code{true}, maxima will give up factorization of
1323 integers if no factor is found after trial divisions and Pollard's rho
1324 method and factorization will not be complete.
1325
1326 When @code{intfaclim} is @code{false} (this is the case when the user
1327 calls @code{factor} explicitly), complete factorization will be
1328 attempted.  @code{intfaclim} is set to @code{false} when factors are
1329 computed in @code{divisors}, @code{divsum} and @code{totient}.
1330 @c ANY OTHERS ??
1331
1332 @c WHAT ARE THESE MYSTERIOUS INTERNAL CALLS ?? (LET'S JUST LIST THE FUNCTIONS INVOLVED)
1333 Internal calls to @code{factor} respect the user-specified value of
1334 @code{intfaclim}.  Setting @code{intfaclim} to @code{true} may reduce
1335 the time spent factoring large integers.
1336 @c NEED EXAMPLES HERE
1337
1338 @opencatbox{Categories:}
1339 @category{Integers}
1340 @closecatbox
1341 @end defvr
1342
1343 @c -----------------------------------------------------------------------------
1344 @defvr {Option variable} keepfloat
1345 Default value: @code{false}
1346
1347 When @code{keepfloat} is @code{true}, prevents floating
1348 point numbers from being rationalized when expressions which contain
1349 them are converted to canonical rational expression (CRE) form.
1350
1351 Note that the function @code{solve} and those functions calling it
1352 (@code{eigenvalues}, for example) currently ignore this flag, converting
1353 floating point numbers anyway.
1354
1355 Examples:
1356
1357 @c ===beg===
1358 @c rat(x/2.0);
1359 @c rat(x/2.0), keepfloat;
1360 @c ===end===
1361 @example
1362 @group
1363 (%i1) rat(x/2.0);
1364
1365 rat: replaced 0.5 by 1/2 = 0.5
1366                                 x
1367 (%o1)/R/                        -
1368                                 2
1369 @end group
1370 @group
1371 (%i2) rat(x/2.0), keepfloat;
1372 (%o2)/R/                      0.5 x
1373 @end group
1374 @end example
1375
1376 @code{solve} ignores @code{keepfloat}:
1377
1378 @c ===beg===
1379 @c solve(1.0-x,x), keepfloat;
1380 @c ===end===
1381 @example
1382 @group
1383 (%i1) solve(1.0-x,x), keepfloat;
1384
1385 rat: replaced 1.0 by 1/1 = 1.0
1386 (%o1)                        [x = 1]
1387 @end group
1388 @end example
1389
1390 @opencatbox{Categories:}
1391 @category{Numerical evaluation}
1392 @closecatbox
1393 @end defvr
1394
1395 @c -----------------------------------------------------------------------------
1396 @anchor{lowpow}
1397 @deffn {Function} lopow (@var{expr}, @var{x})
1398
1399 Returns the lowest exponent of @var{x} which explicitly appears in
1400 @var{expr}.  Thus
1401
1402 @c ===beg===
1403 @c lopow ((x+y)^2 + (x+y)^a, x+y);
1404 @c ===end===
1405 @example
1406 (%i1) lopow ((x+y)^2 + (x+y)^a, x+y);
1407 (%o1)                       min(a, 2)
1408 @end example
1409
1410 @opencatbox{Categories:}
1411 @category{Expressions}
1412 @closecatbox
1413 @end deffn
1414
1415 @c DESCRIBE lratsubst INDEPENDENTLY OF subst
1416 @c THIS ITEM NEEDS MORE WORK
1417
1418 @c -----------------------------------------------------------------------------
1419 @anchor{lratsubst}
1420 @deffn {Function} lratsubst (@var{new}, @var{old}, @var{expr}) @
1421 @fname{lratsubst} (@code{@var{old} = @var{new}}, @var{expr}) @
1422 @fname{lratsubst} (@code{[ @var{old_1} = @var{new_1}, @dots{}, @var{old_n} = @var{new_n} ]}, @var{expr})
1423
1424 @code{lratsubst} is analogous to @mref{subst} except that it uses
1425 @code{ratsubst} to perform substitutions.
1426
1427 The first argument of @code{lratsubst} is an equation, a list of
1428 equations or a list of unit length whose first element is a list of
1429 equations (that is, the first argument is identical in format to that
1430 accepted by @code{subst}). The substitutions are made in the order given
1431 by the list of equations, that is, from left to right.
1432
1433 Examples:
1434
1435 @c EXPRESSIONS ADAPTED FROM demo ("lrats")
1436 @c THIS STUFF CAN PROBABLY STAND REVISION -- EXAMPLES DON'T SEEM VERY ENLIGHTENING
1437
1438 @itemize @bullet
1439 @item
1440 @code{subst} can carry out multiple substitutions.
1441 @code{lratsubst} is analogous to @code{subst}.
1442 @end itemize
1443 @c ===beg===
1444 @c lratsubst ([a = b, c = d], a + c);
1445 @c lratsubst ([a^2 = b, c^2 = d], (a + e)*c*(a + c));
1446 @c ===end===
1447 @example
1448 (%i2) lratsubst ([a = b, c = d], a + c);
1449 (%o2)                         d + b
1450 (%i3) lratsubst ([a^2 = b, c^2 = d], (a + e)*c*(a + c));
1451 (%o3)                (d + a c) e + a d + b c
1452 @end example
1453 @itemize @bullet
1454 @item
1455 If only one substitution is desired, then a single
1456 equation may be given as first argument.
1457 @end itemize
1458 @c ===beg===
1459 @c lratsubst (a^2 = b, a^3);
1460 @c ===end===
1461 @example
1462 (%i4) lratsubst (a^2 = b, a^3);
1463 (%o4)                          a b
1464 @end example
1465 @itemize @bullet
1466 @item
1467 A nested list of substitutions can be used--but it must contain only one list.
1468 @end itemize
1469 @c ===beg===
1470 @c lratsubst ([[a^2=b*a, b=c]], a^3);
1471 @c lratsubst ([[a^2=b*a, b=c],[a=b]], a^3);
1472 @c ===end===
1473 @example
1474 (%i5) lratsubst ([[a^2=b*a, b=c]], a^3);
1475
1476                                       2
1477 (%o5)                               a  c
1478 (%i6) lratsubst ([[a^2=b*a, b=c],[a=b]], a^3);
1479
1480
1481                                  2
1482 lratsubst: improper argument: [[a  = a b, b = c], [a = b]]
1483 #0: lratsubst(listofeqns=[[a^2 = a*b,b = c],[a = b]],expr=a^3)
1484  -- an error. To debug this try: debugmode(true);
1485
1486 @end example
1487
1488 See also @mref{fullratsubst}.
1489
1490 @opencatbox{Categories:}
1491 @category{Polynomials}
1492 @category{Rational expressions}
1493 @closecatbox
1494 @end deffn
1495
1496
1497 @c -----------------------------------------------------------------------------
1498 @anchor{lrats_max_iter}
1499 @defvr {Option variable} lrats_max_iter
1500 Default value: @code{100000}
1501
1502 The upper limit on the number of iterations that @mref{fullratsubst} and
1503 @mref{lratsubst} may perform. It must be set to a positive integer. See
1504 the example for @mref{fullratsubst}.
1505
1506 @opencatbox{Categories:}
1507 @category{Polynomials}
1508 @category{Rational expressions}
1509 @closecatbox
1510 @end defvr
1511
1512
1513 @c -----------------------------------------------------------------------------
1514 @anchor{modulus}
1515 @defvr {Option variable} modulus
1516 Default value: @code{false}
1517
1518 When @code{modulus} is a positive number @var{p}, operations on canonical rational
1519 expressions (CREs, as returned by @code{rat} and related functions) are carried out
1520 modulo @var{p}, using the so-called "balanced" modulus system in which @code{@var{n}
1521 modulo @var{p}} is defined as an integer @var{k} in
1522 @code{[-(@var{p}-1)/2, ..., 0, ..., (@var{p}-1)/2]} when @var{p} is odd, or
1523 @code{[-(@var{p}/2 - 1), ..., 0, ...., @var{p}/2]} when @var{p} is even, such
1524 that @code{@var{a} @var{p} + @var{k}} equals @var{n} for some integer @var{a}.
1525 @c NEED EXAMPLES OF "BALANCED MODULUS" HERE
1526
1527 @c WHAT CAN THIS MEAN ?? IS THE MODULUS STORED WITH THE EXPRESSION ??
1528 @c "... in order to get correct results" -- WHAT DO YOU GET IF YOU DON'T RE-RAT ??
1529 If @var{expr} is already in canonical rational expression (CRE) form when
1530 @code{modulus} is reset, then you may need to re-rat @var{expr}, e.g.,
1531 @code{expr: rat (ratdisrep (expr))}, in order to get correct results.
1532
1533 Typically @code{modulus} is set to a prime number.  If @code{modulus} is set to
1534 a positive non-prime integer, this setting is accepted, but a warning message is
1535 displayed.  Maxima signals an error, when zero or a negative integer is
1536 assigned to @code{modulus}.
1537
1538 Examples:
1539
1540 @c ===beg===
1541 @c modulus:7;
1542 @c polymod([0,1,2,3,4,5,6,7]);
1543 @c modulus:false;
1544 @c poly:x^6+x^2+1;
1545 @c factor(poly);
1546 @c modulus:13;
1547 @c factor(poly);
1548 @c polymod(%);
1549 @c ===end===
1550 @example
1551 (%i1) modulus:7;
1552 (%o1)                           7
1553 (%i2) polymod([0,1,2,3,4,5,6,7]);
1554 (%o2)            [0, 1, 2, 3, - 3, - 2, - 1, 0]
1555 (%i3) modulus:false;
1556 (%o3)                         false
1557 (%i4) poly:x^6+x^2+1;
1558                             6    2
1559 (%o4)                      x  + x  + 1
1560 (%i5) factor(poly);
1561                             6    2
1562 (%o5)                      x  + x  + 1
1563 (%i6) modulus:13;
1564 (%o6)                          13
1565 (%i7) factor(poly);
1566                       2        4      2
1567 (%o7)               (x  + 6) (x  - 6 x  - 2)
1568 (%i8) polymod(%);
1569                             6    2
1570 (%o8)                      x  + x  + 1
1571 @end example
1572 @opencatbox{Categories:}
1573 @category{Integers}
1574 @closecatbox
1575 @end defvr
1576
1577 @c APPARENTLY OBSOLETE: ONLY EFFECT OF $newfac COULD BE TO CAUSE NONEXISTENT FUNCTION NMULTFACT
1578 @c TO BE CALLED (IN FUNCTION FACTOR72 IN src/factor.lisp CIRCA LINE 1400)
1579 @c $newfac NOT USED IN ANY OTHER CONTEXT (ASIDE FROM DECLARATIONS)
1580 @c COMMENT IT OUT NOW, CUT IT ON THE NEXT PASS THROUGH THIS FILE
1581 @c @defvar newfac
1582 @c Default value: @code{false}
1583 @c
1584 @c When @code{newfac} is @code{true}, @code{factor} will use the new factoring
1585 @c routines.
1586 @c
1587 @c @end defvar
1588
1589 @c -----------------------------------------------------------------------------
1590 @anchor{num}
1591 @deffn {Function} num (@var{expr})
1592
1593 Returns the numerator of @var{expr} if it is a ratio.
1594 If @var{expr} is not a ratio, @var{expr} is returned.
1595
1596 @code{num} evaluates its argument.
1597
1598 See also @mref{denom}
1599
1600 @c ===beg===
1601 @c g1:(x+2)*(x+1)/((x+3)^2);
1602 @c num(g1);
1603 @c g2:sin(x)/10*cos(x)/y;
1604 @c num(g2);
1605 @c ===end===
1606 @example
1607 @group
1608 (%i1) g1:(x+2)*(x+1)/((x+3)^2);
1609                          (x + 1) (x + 2)
1610 (%o1)                    ---------------
1611                                    2
1612                             (x + 3)
1613 @end group
1614 @group
1615 (%i2) num(g1);
1616 (%o2)                    (x + 1) (x + 2)
1617 @end group
1618 @group
1619 (%i3) g2:sin(x)/10*cos(x)/y;
1620                           cos(x) sin(x)
1621 (%o3)                     -------------
1622                               10 y
1623 @end group
1624 @group
1625 (%i4) num(g2);
1626 (%o4)                     cos(x) sin(x)
1627 @end group
1628 @end example
1629
1630 @c NEED SOME EXAMPLES HERE
1631 @opencatbox{Categories:}
1632 @category{Expressions}
1633 @closecatbox
1634 @end deffn
1635
1636 @c -----------------------------------------------------------------------------
1637 @anchor{polydecomp}
1638 @deffn {Function} polydecomp (@var{p}, @var{x})
1639
1640 Decomposes the polynomial @var{p} in the variable @var{x}
1641 into the functional composition of polynomials in @var{x}.
1642 @code{polydecomp} returns a list @code{[@var{p_1}, ..., @var{p_n}]} such that
1643
1644 @example
1645 lambda ([x], p_1) (lambda ([x], p_2) (... (lambda ([x], p_n) (x))
1646   ...))
1647 @end example
1648
1649 is equal to @var{p}.
1650 The degree of @var{p_i} is greater than 1 for @var{i} less than @var{n}.
1651
1652 Such a decomposition is not unique.
1653
1654 Examples:
1655
1656 @c ===beg===
1657 @c polydecomp (x^210, x);
1658 @c p : expand (subst (x^3 - x - 1, x, x^2 - a));
1659 @c polydecomp (p, x);
1660 @c ===end===
1661 @example
1662 @group
1663 (%i1) polydecomp (x^210, x);
1664                           7   5   3   2
1665 (%o1)                   [x , x , x , x ]
1666 @end group
1667 @group
1668 (%i2) p : expand (subst (x^3 - x - 1, x, x^2 - a));
1669                 6      4      3    2
1670 (%o2)          x  - 2 x  - 2 x  + x  + 2 x - a + 1
1671 @end group
1672 @group
1673 (%i3) polydecomp (p, x);
1674                         2       3
1675 (%o3)                 [x  - a, x  - x - 1]
1676 @end group
1677 @end example
1678
1679 The following function composes @code{L = [e_1, ..., e_n]} as functions in
1680 @code{x}; it is the inverse of polydecomp:
1681
1682 @c ===beg===
1683 @c compose (L, x) :=
1684 @c   block ([r : x], for e in L do r : subst (e, x, r), r) $
1685 @c ===end===
1686 @example
1687 @group
1688 (%i1) compose (L, x) :=
1689   block ([r : x], for e in L do r : subst (e, x, r), r) $
1690 @end group
1691 @end example
1692
1693 Re-express above example using @code{compose}:
1694
1695 @c ===beg===
1696 @c polydecomp (compose ([x^2 - a, x^3 - x - 1], x), x);
1697 @c ===end===
1698 @example
1699 @group
1700 (%i1) polydecomp (compose ([x^2 - a, x^3 - x - 1], x), x);
1701                           2       3
1702 (%o1)          [compose([x  - a, x  - x - 1], x)]
1703 @end group
1704 @end example
1705
1706 Note that though @code{compose (polydecomp (@var{p}, @var{x}), @var{x})} always
1707 returns @var{p} (unexpanded), @code{polydecomp (compose ([@var{p_1}, ...,
1708 @var{p_n}], @var{x}), @var{x})} does @i{not} necessarily return
1709 @code{[@var{p_1}, ..., @var{p_n}]}:
1710
1711 @c ===beg===
1712 @c polydecomp (compose ([x^2 + 2*x + 3, x^2], x), x);
1713 @c polydecomp (compose ([x^2 + x + 1, x^2 + x + 1], x), x);
1714 @c ===end===
1715 @example
1716 @group
1717 (%i1) polydecomp (compose ([x^2 + 2*x + 3, x^2], x), x);
1718                            2             2
1719 (%o1)           [compose([x  + 2 x + 3, x ], x)]
1720 @end group
1721 @group
1722 (%i2) polydecomp (compose ([x^2 + x + 1, x^2 + x + 1], x), x);
1723                         2           2
1724 (%o2)        [compose([x  + x + 1, x  + x + 1], x)]
1725 @end group
1726 @end example
1727
1728 @opencatbox{Categories:}
1729 @category{Polynomials}
1730 @closecatbox
1731 @end deffn
1732
1733 @c -----------------------------------------------------------------------------
1734 @anchor{polymod}
1735 @deffn  {Function} polymod @
1736 @fname{polymod} (@var{p}) @
1737 @fname{polymod} (@var{p}, @var{m})
1738
1739 Converts the polynomial @var{p} to a modular representation with respect to the
1740 current modulus which is the value of the variable @code{modulus}.
1741
1742 @code{polymod (@var{p}, @var{m})} specifies a modulus @var{m} to be used
1743 instead of the current value of @code{modulus}.
1744
1745 See @mrefdot{modulus}
1746
1747 @opencatbox{Categories:}
1748 @category{Polynomials}
1749 @closecatbox
1750 @end deffn
1751
1752 @c ISN'T THERE AN EQUIVALENT FUNCTION SOMEWHERE ??
1753 @c NEEDS WORK (IF KEPT)
1754
1755 @c -----------------------------------------------------------------------------
1756 @anchor{polynomialp}
1757 @deffn  {Function} polynomialp @
1758 @fname{polynomialp} (@var{p}, @var{L}, @var{coeffp}, @var{exponp}) @
1759 @fname{polynomialp} (@var{p}, @var{L}, @var{coeffp}) @
1760 @fname{polynomialp} (@var{p}, @var{L})
1761
1762 Return @code{true} if @var{p} is a polynomial in the variables in the list
1763 @var{L}.  The predicate @var{coeffp} must evaluate to @code{true} for each
1764 coefficient, and the predicate @var{exponp} must evaluate to @code{true} for all
1765 exponents of the variables in @var{L}.  If you want to use a non-default value
1766 for @var{exponp}, you must supply @var{coeffp} with a value even if you want
1767 to use the default for @var{coeffp}.
1768
1769 @c WORK THE FOLLOWING INTO THE PRECEDING
1770 The command @code{polynomialp (@var{p}, @var{L}, @var{coeffp})} is equivalent to
1771 @code{polynomialp (@var{p}, @var{L}, @var{coeffp}, 'nonnegintegerp)} and the
1772 command @code{polynomialp (@var{p}, @var{L})} is equivalent to
1773 @code{polynomialp (@var{p}, L@var{,} 'constantp, 'nonnegintegerp)}.
1774
1775 The polynomial needn't be expanded:
1776
1777 @c ===beg===
1778 @c polynomialp ((x + 1)*(x + 2), [x]);
1779 @c polynomialp ((x + 1)*(x + 2)^a, [x]);
1780 @c ===end===
1781 @example
1782 (%i1) polynomialp ((x + 1)*(x + 2), [x]);
1783 (%o1)                         true
1784 (%i2) polynomialp ((x + 1)*(x + 2)^a, [x]);
1785 (%o2)                         false
1786 @end example
1787
1788 An example using non-default values for coeffp and exponp:
1789
1790 @c ===beg===
1791 @c polynomialp ((x + 1)*(x + 2)^(3/2), [x], numberp, numberp);
1792 @c polynomialp ((x^(1/2) + 1)*(x + 2)^(3/2), [x], numberp,
1793 @c                                                        numberp);
1794 @c ===end===
1795 @example
1796 (%i1) polynomialp ((x + 1)*(x + 2)^(3/2), [x], numberp, numberp);
1797 (%o1)                         true
1798 (%i2) polynomialp ((x^(1/2) + 1)*(x + 2)^(3/2), [x], numberp,
1799                                                         numberp);
1800 (%o2)                         true
1801 @end example
1802
1803 Polynomials with two variables:
1804
1805 @c ===beg===
1806 @c polynomialp (x^2 + 5*x*y + y^2, [x]);
1807 @c polynomialp (x^2 + 5*x*y + y^2, [x, y]);
1808 @c ===end===
1809 @example
1810 (%i1) polynomialp (x^2 + 5*x*y + y^2, [x]);
1811 (%o1)                         false
1812 (%i2) polynomialp (x^2 + 5*x*y + y^2, [x, y]);
1813 (%o2)                         true
1814 @end example
1815
1816 @opencatbox{Categories:}
1817 @category{Predicate functions}
1818 @category{Polynomials}
1819 @closecatbox
1820 @end deffn
1821
1822 @c -----------------------------------------------------------------------------
1823 @anchor{quotient}
1824 @deffn  {Function} quotient @
1825 @fname{quotient} (@var{p_1}, @var{p_2}) @
1826 @fname{quotient} (@var{p_1}, @var{p_2}, @var{x_1}, @dots{}, @var{x_n})
1827
1828 Returns the polynomial @var{p_1} divided by the polynomial @var{p_2}.  The
1829 arguments @var{x_1}, @dots{}, @var{x_n} are interpreted as in @code{ratvars}.
1830
1831 @code{quotient} returns the first element of the two-element list returned by
1832 @mref{divide}.
1833
1834 @c NEED SOME EXAMPLES HERE
1835 @opencatbox{Categories:}
1836 @category{Polynomials}
1837 @closecatbox
1838 @end deffn
1839
1840 @c THIS ITEM CAN PROBABLY BE IMPROVED
1841
1842 @c -----------------------------------------------------------------------------
1843 @anchor{rat}
1844 @deffn  {Function} rat @
1845 @fname{rat} (@var{expr}) @
1846 @fname{rat} (@var{expr}, @var{x_1}, @dots{}, @var{x_n})
1847
1848 Converts @var{expr} to canonical rational expression (CRE) form by expanding and
1849 combining all terms over a common denominator and cancelling out the
1850 greatest common divisor of the numerator and denominator, as well as
1851 converting floating point numbers to rational numbers within a
1852 tolerance of @code{ratepsilon}.
1853 The variables are ordered according
1854 to the @var{x_1}, @dots{}, @var{x_n}, if specified, as in @code{ratvars}.
1855
1856 @code{rat} does not generally simplify functions other than addition @code{+},
1857 subtraction @code{-}, multiplication @code{*}, division @code{/}, and
1858 exponentiation to an integer power,
1859 whereas @code{ratsimp} does handle those cases.
1860 Note that atoms (numbers and variables) in CRE form are not the
1861 same as they are in the general form.
1862 For example, @code{rat(x)- x} yields
1863 @code{rat(0)} which has a different internal representation than 0.
1864
1865 @c WHAT'S THIS ABOUT EXACTLY ??
1866 When @code{ratfac} is @code{true}, @code{rat} yields a partially factored
1867 form for CRE.  During rational operations the expression is
1868 maintained as fully factored as possible without an actual call to the
1869 factor package.  This should always save space and may save some time
1870 in some computations.  The numerator and denominator are still made
1871 relatively prime
1872 (e.g.,  @code{rat((x^2 - 1)^4/(x + 1)^2)} yields @code{(x - 1)^4 (x + 1)^2}
1873 when @code{ratfac} is @code{true}),
1874 but the factors within each part may not be relatively prime.
1875
1876 @code{ratprint} if @code{false} suppresses the printout of the message
1877 informing the user of the conversion of floating point numbers to
1878 rational numbers.
1879
1880 @code{keepfloat} if @code{true} prevents floating point numbers from being
1881 converted to rational numbers.
1882
1883 See also @code{ratexpand} and  @code{ratsimp}.
1884
1885 Examples:
1886 @c ===beg===
1887 @c ((x - 2*y)^4/(x^2 - 4*y^2)^2 + 1)*(y + a)*(2*y + x) /
1888 @c       (4*y^2 + x^2);
1889 @c rat (%, y, a, x);
1890 @c ===end===
1891 @example
1892 @group
1893 (%i1) ((x - 2*y)^4/(x^2 - 4*y^2)^2 + 1)*(y + a)*(2*y + x) /
1894       (4*y^2 + x^2);
1895                                            4
1896                                   (x - 2 y)
1897               (y + a) (2 y + x) (------------ + 1)
1898                                    2      2 2
1899                                  (x  - 4 y )
1900 (%o1)         ------------------------------------
1901                               2    2
1902                            4 y  + x
1903 @end group
1904 @group
1905 (%i2) rat (%, y, a, x);
1906                             2 a + 2 y
1907 (%o2)/R/                    ---------
1908                              x + 2 y
1909 @end group
1910 @end example
1911
1912 @opencatbox{Categories:}
1913 @category{Rational expressions}
1914 @closecatbox
1915 @end deffn
1916
1917 @defvr {Option variable} ratalgdenom
1918 Default value: @code{true}
1919
1920 When @code{ratalgdenom} is @code{true}, allows rationalization of denominators
1921 with respect to radicals to take effect.  @code{ratalgdenom} has an effect only
1922 when canonical rational expressions (CRE) are used in algebraic mode.
1923
1924 @opencatbox{Categories:}
1925 @category{Simplification flags and variables}
1926 @closecatbox
1927 @end defvr
1928
1929 @c THIS ITEM NEEDS MORE WORK
1930
1931 @c -----------------------------------------------------------------------------
1932 @anchor{ratcoef}
1933 @deffn  {Function} ratcoef @
1934 @fname{ratcoef} (@var{expr}, @var{x}, @var{n}) @
1935 @fname{ratcoef} (@var{expr}, @var{x})
1936
1937 Returns the coefficient of the expression @code{@var{x}^@var{n}}
1938 in the expression @var{expr}.
1939 If omitted, @var{n} is assumed to be 1.
1940
1941 The return value is free
1942 (except possibly in a non-rational sense) of the variables in @var{x}.
1943 If no coefficient of this type exists, 0 is returned.
1944
1945 @code{ratcoef}
1946 expands and rationally simplifies its first argument and thus it may
1947 produce answers different from those of @code{coeff} which is purely
1948 syntactic.
1949 @c MOVE THIS TO EXAMPLES SECTION
1950 Thus @code{ratcoef ((x + 1)/y + x, x)} returns @code{(y + 1)/y} whereas
1951 @code{coeff} returns 1.
1952
1953 @code{ratcoef (@var{expr}, @var{x}, 0)}, viewing @var{expr} as a sum,
1954 returns a sum of those terms which do not contain @var{x}.
1955 @c "SHOULD NOT" -- WHAT DOES THIS MEAN ??
1956 Therefore if @var{x} occurs to any negative powers, @code{ratcoef} should not
1957 be used.
1958
1959 @c WHAT IS THE INTENT HERE ??
1960 Since @var{expr} is rationally
1961 simplified before it is examined, coefficients may not appear quite
1962 the way they were envisioned.
1963
1964 Example:
1965
1966 @c ===beg===
1967 @c s: a*x + b*x + 5$
1968 @c ratcoef (s, a + b);
1969 @c ===end===
1970 @example
1971 (%i1) s: a*x + b*x + 5$
1972 (%i2) ratcoef (s, a + b);
1973 (%o2)                           x
1974 @end example
1975 @c NEED MORE EXAMPLES HERE
1976
1977 @opencatbox{Categories:}
1978 @category{Polynomials}
1979 @category{Rational expressions}
1980 @closecatbox
1981 @end deffn
1982
1983 @c -----------------------------------------------------------------------------
1984 @anchor{ratdenom}
1985 @deffn {Function} ratdenom (@var{expr})
1986
1987 Returns the denominator of @var{expr},
1988 after coercing @var{expr} to a canonical rational expression (CRE).
1989 The return value is a CRE.
1990
1991 @c ACTUALLY THE CONVERSION IS CARRIED OUT BY ratf BUT THAT'S WHAT $rat CALLS
1992 @var{expr} is coerced to a CRE by @code{rat}
1993 if it is not already a CRE.
1994 This conversion may change the form of @var{expr} by putting all terms
1995 over a common denominator.
1996
1997 @code{denom} is similar, but returns an ordinary expression instead of a CRE.
1998 Also, @code{denom} does not attempt to place all terms over a common
1999 denominator, and thus some expressions which are considered ratios by
2000 @code{ratdenom} are not considered ratios by @code{denom}.
2001
2002 @c NEEDS AN EXAMPLE HERE
2003 @opencatbox{Categories:}
2004 @category{Rational expressions}
2005 @closecatbox
2006 @end deffn
2007
2008 @c -----------------------------------------------------------------------------
2009 @defvr {Option variable} ratdenomdivide
2010 Default value: @code{true}
2011
2012 When @code{ratdenomdivide} is @code{true},
2013 @code{ratexpand} expands a ratio in which the numerator is a sum
2014 into a sum of ratios,
2015 all having a common denominator.
2016 Otherwise, @code{ratexpand} collapses a sum of ratios into a single ratio,
2017 the numerator of which is the sum of the numerators of each ratio.
2018
2019 Examples:
2020
2021 @c ===beg===
2022 @c expr: (x^2 + x + 1)/(y^2 + 7);
2023 @c ratdenomdivide: true$
2024 @c ratexpand (expr);
2025 @c ratdenomdivide: false$
2026 @c ratexpand (expr);
2027 @c expr2: a^2/(b^2 + 3) + b/(b^2 + 3);
2028 @c ratexpand (expr2);
2029 @c ===end===
2030 @example
2031 (%i1) expr: (x^2 + x + 1)/(y^2 + 7);
2032                             2
2033                            x  + x + 1
2034 (%o1)                      ----------
2035                               2
2036                              y  + 7
2037 (%i2) ratdenomdivide: true$
2038 (%i3) ratexpand (expr);
2039                        2
2040                       x        x        1
2041 (%o3)               ------ + ------ + ------
2042                      2        2        2
2043                     y  + 7   y  + 7   y  + 7
2044 (%i4) ratdenomdivide: false$
2045 (%i5) ratexpand (expr);
2046 @group
2047                             2
2048                            x  + x + 1
2049 (%o5)                      ----------
2050                               2
2051                              y  + 7
2052 @end group
2053 (%i6) expr2: a^2/(b^2 + 3) + b/(b^2 + 3);
2054                                      2
2055                            b        a
2056 (%o6)                    ------ + ------
2057                           2        2
2058                          b  + 3   b  + 3
2059 (%i7) ratexpand (expr2);
2060                                   2
2061                              b + a
2062 (%o7)                        ------
2063                               2
2064                              b  + 3
2065 @end example
2066
2067 @opencatbox{Categories:}
2068 @category{Simplification flags and variables}
2069 @category{Rational expressions}
2070 @closecatbox
2071 @end defvr
2072
2073 @c -----------------------------------------------------------------------------
2074 @anchor{ratdiff}
2075 @deffn {Function} ratdiff (@var{expr}, @var{x})
2076
2077 Differentiates the rational expression @var{expr} with respect to @var{x}.
2078 @var{expr} must be a ratio of polynomials or a polynomial in @var{x}.
2079 The argument @var{x} may be a variable or a subexpression of @var{expr}.
2080 @c NOT CLEAR (FROM READING CODE) HOW x OTHER THAN A VARIABLE IS HANDLED --
2081 @c LOOKS LIKE (a+b), 10*(a+b), (a+b)^2 ARE ALL TREATED LIKE (a+b);
2082 @c HOW TO DESCRIBE THAT ??
2083
2084 The result is equivalent to @code{diff}, although perhaps in a different form.
2085 @code{ratdiff} may be faster than @code{diff}, for rational expressions.
2086
2087 @code{ratdiff} returns a canonical rational expression (CRE) if @code{expr} is
2088 a CRE.  Otherwise, @code{ratdiff} returns a general expression.
2089
2090 @code{ratdiff} considers only the dependence of @var{expr} on @var{x},
2091 and ignores any dependencies established by @code{depends}.
2092
2093 @c WHAT THIS IS ABOUT -- ratdiff (rat (factor (expr)), x) AND ratdiff (factor (rat (expr)), x) BOTH SUCCEED
2094 @c COMMENTING THIS OUT UNTIL SOMEONE CAN ESTABLISH SOME CRE'S FOR WHICH ratdiff FAILS
2095 @c However, @code{ratdiff} should not be used on factored CRE forms;
2096 @c use @code{diff} instead for such expressions.
2097
2098 Example:
2099
2100 @c ===beg===
2101 @c expr: (4*x^3 + 10*x - 11)/(x^5 + 5);
2102 @c ratdiff (expr, x);
2103 @c expr: f(x)^3 - f(x)^2 + 7;
2104 @c ratdiff (expr, f(x));
2105 @c expr: (a + b)^3 + (a + b)^2;
2106 @c ratdiff (expr, a + b);
2107 @c ===end===
2108 @example
2109 (%i1) expr: (4*x^3 + 10*x - 11)/(x^5 + 5);
2110 @group
2111                            3
2112                         4 x  + 10 x - 11
2113 (%o1)                   ----------------
2114                               5
2115                              x  + 5
2116 @end group
2117 (%i2) ratdiff (expr, x);
2118                     7       5       4       2
2119                  8 x  + 40 x  - 55 x  - 60 x  - 50
2120 (%o2)          - ---------------------------------
2121                           10       5
2122                          x   + 10 x  + 25
2123 (%i3) expr: f(x)^3 - f(x)^2 + 7;
2124                          3       2
2125 (%o3)                   f (x) - f (x) + 7
2126 (%i4) ratdiff (expr, f(x));
2127                            2
2128 (%o4)                   3 f (x) - 2 f(x)
2129 (%i5) expr: (a + b)^3 + (a + b)^2;
2130                               3          2
2131 (%o5)                  (b + a)  + (b + a)
2132 (%i6) ratdiff (expr, a + b);
2133                     2                    2
2134 (%o6)            3 b  + (6 a + 2) b + 3 a  + 2 a
2135 @end example
2136
2137 @opencatbox{Categories:}
2138 @category{Rational expressions}
2139 @closecatbox
2140 @end deffn
2141
2142 @c -----------------------------------------------------------------------------
2143 @anchor{ratdisrep}
2144 @deffn {Function} ratdisrep (@var{expr})
2145
2146 Returns its argument as a general expression.
2147 If @var{expr} is a general expression, it is returned unchanged.
2148
2149 Typically @code{ratdisrep} is called to convert a canonical rational expression
2150 (CRE) into a general expression.
2151 @c NOT REALLY FOND OF YOU-CAN-DO-THIS-YOU-CAN-DO-THAT STATEMENTS
2152 This is sometimes convenient if one wishes to stop the "contagion", or
2153 use rational functions in non-rational contexts.
2154
2155 See also @mrefdot{totaldisrep}
2156
2157 @opencatbox{Categories:}
2158 @category{Rational expressions}
2159 @closecatbox
2160 @end deffn
2161
2162 @c -----------------------------------------------------------------------------
2163 @anchor{ratexpand}
2164 @deffn  {Function} ratexpand (@var{expr})
2165 @deffnx {Option variable} ratexpand
2166
2167 Expands @var{expr} by multiplying out products of sums and
2168 exponentiated sums, combining fractions over a common denominator,
2169 cancelling the greatest common divisor of the numerator and
2170 denominator, then splitting the numerator (if a sum) into its
2171 respective terms divided by the denominator.
2172
2173 The return value of @code{ratexpand} is a general expression,
2174 even if @var{expr} is a canonical rational expression (CRE).
2175
2176 @c WHAT DOES THE FOLLOWING MEAN EXACTLY ??
2177 The switch @code{ratexpand} if @code{true} will cause CRE
2178 expressions to be fully expanded when they are converted back to
2179 general form or displayed, while if it is @code{false} then they will be put
2180 into a recursive form.
2181 See also @mrefdot{ratsimp}
2182
2183 When @code{ratdenomdivide} is @code{true},
2184 @code{ratexpand} expands a ratio in which the numerator is a sum
2185 into a sum of ratios,
2186 all having a common denominator.
2187 Otherwise, @code{ratexpand} collapses a sum of ratios into a single ratio,
2188 the numerator of which is the sum of the numerators of each ratio.
2189
2190 When @code{keepfloat} is @code{true}, prevents floating
2191 point numbers from being rationalized when expressions which contain
2192 them are converted to canonical rational expression (CRE) form.
2193
2194 Examples:
2195
2196 @c ===beg===
2197 @c ratexpand ((2*x - 3*y)^3);
2198 @c expr: (x - 1)/(x + 1)^2 + 1/(x - 1);
2199 @c expand (expr);
2200 @c ratexpand (expr);
2201 @c ===end===
2202 @example
2203 (%i1) ratexpand ((2*x - 3*y)^3);
2204                      3         2       2        3
2205 (%o1)          - 27 y  + 54 x y  - 36 x  y + 8 x
2206 (%i2) expr: (x - 1)/(x + 1)^2 + 1/(x - 1);
2207                          x - 1       1
2208 (%o2)                   -------- + -----
2209                                2   x - 1
2210                         (x + 1)
2211 (%i3) expand (expr);
2212 @group
2213                     x              1           1
2214 (%o3)          ------------ - ------------ + -----
2215                 2              2             x - 1
2216                x  + 2 x + 1   x  + 2 x + 1
2217 @end group
2218 (%i4) ratexpand (expr);
2219                         2
2220                      2 x                 2
2221 (%o4)           --------------- + ---------------
2222                  3    2            3    2
2223                 x  + x  - x - 1   x  + x  - x - 1
2224 @end example
2225
2226 @opencatbox{Categories:}
2227 @category{Rational expressions}
2228 @closecatbox
2229 @end deffn
2230
2231 @c -----------------------------------------------------------------------------
2232 @anchor{ratfac}
2233 @defvr {Option variable} ratfac
2234 Default value: @code{false}
2235
2236 When @code{ratfac} is @code{true}, canonical rational expressions (CRE) are
2237 manipulated in a partially factored form.
2238
2239 During rational operations the expression is maintained as fully factored as
2240 possible without calling @code{factor}.
2241 This should always save space and may save time in some computations.
2242 The numerator and denominator are made relatively prime, for example
2243 @code{factor ((x^2 - 1)^4/(x + 1)^2)} yields @code{(x - 1)^4 (x + 1)^2},
2244 but the factors within each part may not be relatively prime.
2245
2246 In the @code{ctensor} (Component Tensor Manipulation) package,
2247 Ricci, Einstein, Riemann, and Weyl tensors and the scalar curvature
2248 are factored automatically when @code{ratfac} is @code{true}.
2249 @i{@code{ratfac} should only be
2250 set for cases where the tensorial components are known to consist of
2251 few terms.}
2252
2253 The @code{ratfac} and @code{ratweight} schemes are incompatible and may not
2254 both be used at the same time.
2255
2256 @c NEED EXAMPLES HERE
2257 @opencatbox{Categories:}
2258 @category{Rational expressions}
2259 @closecatbox
2260 @end defvr
2261
2262 @c -----------------------------------------------------------------------------
2263 @anchor{ratnumer}
2264 @deffn {Function} ratnumer (@var{expr})
2265
2266 Returns the numerator of @var{expr},
2267 after coercing @var{expr} to a canonical rational expression (CRE).
2268 The return value is a CRE.
2269
2270 @c ACTUALLY THE CONVERSION IS CARRIED OUT BY ratf BUT THAT'S WHAT $rat CALLS
2271 @var{expr} is coerced to a CRE by @code{rat}
2272 if it is not already a CRE.
2273 This conversion may change the form of @var{expr} by putting all terms
2274 over a common denominator.
2275
2276 @code{num} is similar, but returns an ordinary expression instead of a CRE.
2277 Also, @code{num} does not attempt to place all terms over a common denominator,
2278 and thus some expressions which are considered ratios by @code{ratnumer}
2279 are not considered ratios by @code{num}.
2280
2281 @c NEEDS AN EXAMPLE HERE
2282 @opencatbox{Categories:}
2283 @category{Rational expressions}
2284 @closecatbox
2285 @end deffn
2286
2287 @c -----------------------------------------------------------------------------
2288 @anchor{ratp}
2289 @deffn {Function} ratp (@var{expr})
2290
2291 Returns @code{true} if @var{expr} is a canonical rational expression (CRE) or
2292 extended CRE, otherwise @code{false}.
2293
2294 CRE are created by @code{rat} and related functions.
2295 Extended CRE are created by @code{taylor} and related functions.
2296
2297 @opencatbox{Categories:}
2298 @category{Predicate functions}
2299 @category{Rational expressions}
2300 @closecatbox
2301 @end deffn
2302
2303 @c -----------------------------------------------------------------------------
2304 @defvr {Option variable} ratprint
2305 Default value: @code{true}
2306
2307 When @code{ratprint} is @code{true},
2308 a message informing the user of the conversion of floating point numbers
2309 to rational numbers is displayed.
2310
2311 @opencatbox{Categories:}
2312 @category{Rational expressions}
2313 @category{Numerical evaluation}
2314 @category{Console interaction}
2315 @closecatbox
2316 @end defvr
2317
2318 @c -----------------------------------------------------------------------------
2319 @anchor{ratsimp}
2320 @deffn  {Function} ratsimp (@var{expr})
2321 @deffnx {Function} ratsimp (@var{expr}, @var{x_1}, @dots{}, @var{x_n})
2322
2323 Simplifies the expression @var{expr} and all of its subexpressions, including
2324 the arguments to non-rational functions.  The result is returned as the quotient
2325 of two polynomials in a recursive form, that is, the coefficients of the main
2326 variable are polynomials in the other variables.  Variables may include
2327 non-rational functions (e.g., @code{sin (x^2 + 1)}) and the arguments to any
2328 such functions are also rationally simplified.
2329
2330 @code{ratsimp (@var{expr}, @var{x_1}, ..., @var{x_n})}
2331 enables rational simplification with the
2332 specification of variable ordering as in @code{ratvars}.
2333
2334 When @code{ratsimpexpons} is @code{true},
2335 @code{ratsimp} is applied to the exponents of expressions during simplification.
2336
2337 See also @mrefdot{ratexpand}
2338 Note that @code{ratsimp} is affected by some of the
2339 flags which affect @code{ratexpand}.
2340
2341 Examples:
2342
2343 @c ===beg===
2344 @c sin (x/(x^2 + x)) = exp ((log(x) + 1)^2 - log(x)^2);
2345 @c ratsimp (%);
2346 @c ((x - 1)^(3/2) - (x + 1)*sqrt(x - 1))/sqrt((x - 1)*(x + 1));
2347 @c ratsimp (%);
2348 @c x^(a + 1/a), ratsimpexpons: true;
2349 @c ===end===
2350 @example
2351 (%i1) sin (x/(x^2 + x)) = exp ((log(x) + 1)^2 - log(x)^2);
2352 @group
2353                                          2      2
2354                    x         (log(x) + 1)  - log (x)
2355 (%o1)        sin(------) = %e
2356                   2
2357                  x  + x
2358 @end group
2359 (%i2) ratsimp (%);
2360                              1          2
2361 (%o2)                  sin(-----) = %e x
2362                            x + 1
2363 (%i3) ((x - 1)^(3/2) - (x + 1)*sqrt(x - 1))/sqrt((x - 1)*(x + 1));
2364 @group
2365                        3/2
2366                 (x - 1)    - sqrt(x - 1) (x + 1)
2367 (%o3)           --------------------------------
2368                      sqrt((x - 1) (x + 1))
2369 @end group
2370 (%i4) ratsimp (%);
2371                            2 sqrt(x - 1)
2372 (%o4)                    - -------------
2373                                  2
2374                            sqrt(x  - 1)
2375 (%i5) x^(a + 1/a), ratsimpexpons: true;
2376                                2
2377                               a  + 1
2378                               ------
2379                                 a
2380 (%o5)                        x
2381 @end example
2382
2383 @opencatbox{Categories:}
2384 @category{Simplification functions}
2385 @category{Rational expressions}
2386 @closecatbox
2387 @end deffn
2388
2389 @c -----------------------------------------------------------------------------
2390 @defvr {Option variable} ratsimpexpons
2391 Default value: @code{false}
2392
2393 When @code{ratsimpexpons} is @code{true},
2394 @code{ratsimp} is applied to the exponents of expressions during simplification.
2395
2396 @c NEED AN EXAMPLE HERE -- RECYCLE THE ratsimpexpons EXAMPLE FROM ratsimp ABOVE
2397 @opencatbox{Categories:}
2398 @category{Simplification flags and variables}
2399 @category{Rational expressions}
2400 @closecatbox
2401 @end defvr
2402
2403 @c -----------------------------------------------------------------------------
2404 @anchor{radsubstflag}
2405 @defvr {Option variable} radsubstflag
2406 Default value: @code{false}
2407
2408 @code{radsubstflag}, if @code{true}, permits @code{ratsubst} to make
2409 substitutions such as @code{u} for @code{sqrt (x)} in @code{x}.
2410
2411 @opencatbox{Categories:}
2412 @category{Simplification flags and variables}
2413 @closecatbox
2414 @end defvr
2415
2416 @c -----------------------------------------------------------------------------
2417 @anchor{ratsubst}
2418 @deffn {Function} ratsubst (@var{a}, @var{b}, @var{c})
2419
2420 Substitutes @var{a} for @var{b} in @var{c} and returns the resulting expression.
2421 @c "ETC" SUGGESTS THE READER KNOWS WHAT ELSE GOES THERE -- NOT LIKELY THE CASE
2422 @var{b} may be a sum, product, power, etc.
2423
2424 @c WHAT, EXACTLY, DOES ratsubst KNOW ??
2425 @code{ratsubst} knows something of the meaning of expressions
2426 whereas @code{subst} does a purely syntactic substitution.
2427 Thus @code{subst (a, x + y, x + y + z)} returns @code{x + y + z}
2428 whereas @code{ratsubst} returns @code{z + a}.
2429
2430 When @code{radsubstflag} is @code{true},
2431 @code{ratsubst} makes substitutions for radicals in expressions
2432 which don't explicitly contain them.
2433
2434 @code{ratsubst} ignores the value @code{true} of the option variables
2435 @code{keepfloat}, @code{float}, and @code{numer}.
2436
2437 Examples:
2438
2439 @c EXAMPLES BELOW ADAPTED FROM examples (ratsubst)
2440 @c WITH SOME ADDITIONAL STUFF
2441
2442 @c ===beg===
2443 @c ratsubst (a, x*y^2, x^4*y^3 + x^4*y^8);
2444 @c cos(x)^4 + cos(x)^3 + cos(x)^2 + cos(x) + 1;
2445 @c ratsubst (1 - sin(x)^2, cos(x)^2, %);
2446 @c ratsubst (1 - cos(x)^2, sin(x)^2, sin(x)^4);
2447 @c radsubstflag: false$
2448 @c ratsubst (u, sqrt(x), x);
2449 @c radsubstflag: true$
2450 @c ratsubst (u, sqrt(x), x);
2451 @c ===end===
2452 @example
2453 @group
2454 (%i1) ratsubst (a, x*y^2, x^4*y^3 + x^4*y^8);
2455                               3      4
2456 (%o1)                      a x  y + a
2457 @end group
2458 @group
2459 (%i2) cos(x)^4 + cos(x)^3 + cos(x)^2 + cos(x) + 1;
2460                4         3         2
2461 (%o2)       cos (x) + cos (x) + cos (x) + cos(x) + 1
2462 @end group
2463 @group
2464 (%i3) ratsubst (1 - sin(x)^2, cos(x)^2, %);
2465             4           2                     2
2466 (%o3)    sin (x) - 3 sin (x) + cos(x) (2 - sin (x)) + 3
2467 @end group
2468 @group
2469 (%i4) ratsubst (1 - cos(x)^2, sin(x)^2, sin(x)^4);
2470                         4           2
2471 (%o4)                cos (x) - 2 cos (x) + 1
2472 @end group
2473 (%i5) radsubstflag: false$
2474 @group
2475 (%i6) ratsubst (u, sqrt(x), x);
2476 (%o6)                           x
2477 @end group
2478 (%i7) radsubstflag: true$
2479 @group
2480 (%i8) ratsubst (u, sqrt(x), x);
2481                                 2
2482 (%o8)                          u
2483 @end group
2484 @end example
2485
2486 @opencatbox{Categories:}
2487 @category{Rational expressions}
2488 @closecatbox
2489 @end deffn
2490
2491 @c -----------------------------------------------------------------------------
2492 @anchor{ratvars}
2493 @deffn  {Function} ratvars (@var{x_1}, @dots{}, @var{x_n})
2494 @deffnx {Function} ratvars ()
2495 @deffnx {System variable} ratvars
2496
2497 Declares main variables @var{x_1}, @dots{}, @var{x_n} for rational expressions.
2498 @var{x_n}, if present in a rational expression, is considered the main variable.
2499 Otherwise, @var{x_[n-1]} is considered the main variable if present, and so on
2500 through the preceding variables to @var{x_1}, which is considered the main
2501 variable only if none of the succeeding variables are present.
2502
2503 If a variable in a rational expression is not present in the @code{ratvars}
2504 list, it is given a lower priority than @var{x_1}.
2505
2506 The arguments to @code{ratvars} can be either variables or non-rational
2507 functions such as @code{sin(x)}.
2508
2509 The variable @code{ratvars} is a list of the arguments of
2510 the function @code{ratvars} when it was called most recently.
2511 Each call to the function @code{ratvars} resets the list.
2512 @code{ratvars ()} clears the list.
2513
2514 @c NEED EXAMPLES HERE
2515 @opencatbox{Categories:}
2516 @category{Rational expressions}
2517 @closecatbox
2518 @end deffn
2519
2520 @c -----------------------------------------------------------------------------
2521 @defvr {Option variable} ratvarswitch
2522 Default value: @code{true}
2523
2524 Maxima keeps an internal list in the Lisp variable @code{VARLIST} of the main
2525 variables for rational expressions.  If @code{ratvarswitch} is @code{true},
2526 every evaluation starts with a fresh list @code{VARLIST}.  This is the default
2527 behavior.  Otherwise, the main variables from previous evaluations are not
2528 removed from the internal list @code{VARLIST}.
2529
2530 The main variables, which are declared with the function @code{ratvars} are
2531 not affected by the option variable @code{ratvarswitch}.
2532
2533 Examples:
2534
2535 If @code{ratvarswitch} is @code{true}, every evaluation starts with a fresh
2536 list @code{VARLIST}.
2537
2538 @c ===beg===
2539 @c ratvarswitch:true$
2540 @c rat(2*x+y^2);
2541 @c :lisp varlist
2542 @c rat(2*a+b^2);
2543 @c :lisp varlist
2544 @c ===end===
2545 @example
2546 (%i1) ratvarswitch:true$
2547
2548 (%i2) rat(2*x+y^2);
2549                              2
2550 (%o2)/R/                    y  + 2 x
2551 (%i3) :lisp varlist
2552 ($X $Y)
2553
2554 (%i3) rat(2*a+b^2);
2555                              2
2556 (%o3)/R/                    b  + 2 a
2557
2558 (%i4) :lisp varlist
2559 ($A $B)
2560 @end example
2561
2562 If @code{ratvarswitch} is @code{false}, the main variables from the last
2563 evaluation are still present.
2564
2565 @c ===beg===
2566 @c ratvarswitch:false$
2567 @c rat(2*x+y^2);
2568 @c :lisp varlist
2569 @c rat(2*a+b^2);
2570 @c :lisp varlist
2571 @c ===end===
2572 @example
2573 (%i4) ratvarswitch:false$
2574
2575 (%i5) rat(2*x+y^2);
2576                              2
2577 (%o5)/R/                    y  + 2 x
2578 (%i6) :lisp varlist
2579 ($X $Y)
2580
2581 (%i6) rat(2*a+b^2);
2582                              2
2583 (%o6)/R/                    b  + 2 a
2584
2585 (%i7) :lisp varlist
2586 ($A $B $X $Y)
2587 @end example
2588
2589 @opencatbox{Categories:}
2590 @category{Rational expressions}
2591 @category{Global flags}
2592 @closecatbox
2593 @end defvr
2594
2595 @c -----------------------------------------------------------------------------
2596 @deffn  {Function} ratweight @
2597 @fname{ratweight} (@var{x_1}, @var{w_1}, @dots{}, @var{x_n}, @var{w_n}) @
2598 @fname{ratweight} ()
2599
2600 Assigns a weight @var{w_i} to the variable @var{x_i}.
2601 This causes a term to be replaced by 0 if its weight exceeds the
2602 value of the variable @code{ratwtlvl} (default yields no truncation).
2603 The weight of a term is the sum of the products of the
2604 weight of a variable in the term times its power.
2605 For example, the weight of @code{3 x_1^2 x_2} is @code{2 w_1 + w_2}.
2606 Truncation according to @code{ratwtlvl} is carried out only when multiplying
2607 or exponentiating canonical rational expressions (CRE).
2608
2609 @code{ratweight ()} returns the cumulative list of weight assignments.
2610
2611 Note: The @code{ratfac} and @code{ratweight} schemes are incompatible and may
2612 not both be used at the same time.
2613
2614 Examples:
2615
2616 @c ===beg===
2617 @c ratweight (a, 1, b, 1);
2618 @c expr1: rat(a + b + 1)$
2619 @c expr1^2;
2620 @c ratwtlvl: 1$
2621 @c expr1^2;
2622 @c ===end===
2623 @example
2624 (%i1) ratweight (a, 1, b, 1);
2625 (%o1)                     [a, 1, b, 1]
2626 (%i2) expr1: rat(a + b + 1)$
2627 (%i3) expr1^2;
2628                   2                  2
2629 (%o3)/R/         b  + (2 a + 2) b + a  + 2 a + 1
2630 (%i4) ratwtlvl: 1$
2631 (%i5) expr1^2;
2632 (%o5)/R/                  2 b + 2 a + 1
2633 @end example
2634
2635 @opencatbox{Categories:}
2636 @category{Rational expressions}
2637 @closecatbox
2638 @end deffn
2639
2640 @c -----------------------------------------------------------------------------
2641 @defvr {System variable} ratweights
2642 Default value: @code{[]}
2643
2644 @code{ratweights} is the list of weights assigned by @code{ratweight}.
2645 The list is cumulative:
2646 each call to @code{ratweight} places additional items in the list.
2647
2648 @c DO WE REALLY NEED TO MENTION THIS ??
2649 @code{kill (ratweights)} and @code{save (ratweights)} both work as expected.
2650
2651 @opencatbox{Categories:}
2652 @category{Rational expressions}
2653 @closecatbox
2654 @end defvr
2655
2656 @c -----------------------------------------------------------------------------
2657 @need 1000
2658 @defvr {Option variable} ratwtlvl
2659 Default value: @code{false}
2660
2661 @code{ratwtlvl} is used in combination with the @code{ratweight}
2662 function to control the truncation of canonical rational expressions (CRE).
2663 For the default value of @code{false}, no truncation occurs.
2664
2665 @opencatbox{Categories:}
2666 @category{Rational expressions}
2667 @closecatbox
2668 @end defvr
2669
2670 @c -----------------------------------------------------------------------------
2671 @deffn  {Function} remainder @
2672 @fname{remainder} (@var{p_1}, @var{p_2}) @
2673 @fname{remainder} (@var{p_1}, @var{p_2}, @var{x_1}, @dots{}, @var{x_n})
2674
2675 Returns the remainder of the polynomial @var{p_1} divided by the polynomial
2676 @var{p_2}.  The arguments @var{x_1}, @dots{}, @var{x_n} are interpreted as in
2677 @code{ratvars}.
2678
2679 @code{remainder} returns the second element
2680 of the two-element list returned by @code{divide}.
2681
2682 @c NEED SOME EXAMPLES HERE
2683 @opencatbox{Categories:}
2684 @category{Polynomials}
2685 @closecatbox
2686 @end deffn
2687
2688 @c -----------------------------------------------------------------------------
2689 @anchor{resultant}
2690 @deffn {Function} resultant (@var{p_1}, @var{p_2}, @var{x})
2691
2692 The function @code{resultant} computes the resultant of the two polynomials
2693 @var{p_1} and @var{p_2}, eliminating the variable @var{x}.  The resultant is a
2694 determinant of the coefficients of @var{x} in @var{p_1} and @var{p_2}, which
2695 equals zero if and only if @var{p_1} and @var{p_2} have a non-constant factor
2696 in common.
2697
2698 If @var{p_1} or @var{p_2} can be factored, it may be desirable to call
2699 @mref{factor} before calling @code{resultant}.
2700
2701 The option variable @code{resultant} controls which algorithm will be used to
2702 compute the resultant.  See the option variable
2703 @mxrefdot{option_resultant, resultant}
2704
2705 The function @mref{bezout} takes the same arguments as @code{resultant} and
2706 returns a matrix.  The determinant of the return value is the desired resultant.
2707
2708 Examples:
2709
2710 @c ===beg===
2711 @c resultant(2*x^2+3*x+1, 2*x^2+x+1, x);
2712 @c resultant(x+1, x+1, x);
2713 @c resultant((x+1)*x, (x+1), x);
2714 @c resultant(a*x^2+b*x+1, c*x + 2, x);
2715 @c bezout(a*x^2+b*x+1, c*x+2, x);
2716 @c determinant(%);
2717 @c ===end===
2718 @example
2719 (%i1) resultant(2*x^2+3*x+1, 2*x^2+x+1, x);
2720 (%o1)                           8
2721 (%i2) resultant(x+1, x+1, x);
2722 (%o2)                           0
2723 (%i3) resultant((x+1)*x, (x+1), x);
2724 (%o3)                           0
2725 (%i4) resultant(a*x^2+b*x+1, c*x + 2, x);
2726                          2
2727 (%o4)                   c  - 2 b c + 4 a
2728
2729 (%i5) bezout(a*x^2+b*x+1, c*x+2, x);
2730 @group
2731                         [ 2 a  2 b - c ]
2732 (%o5)                   [              ]
2733                         [  c      2    ]
2734 @end group
2735 (%i6) determinant(%);
2736 (%o6)                   4 a - (2 b - c) c
2737 @end example
2738 @opencatbox{Categories:}
2739 @category{Polynomials}
2740 @closecatbox
2741 @end deffn
2742
2743 @c -----------------------------------------------------------------------------
2744 @anchor{option_resultant}
2745 @defvr {Option variable} resultant
2746 Default value: @code{subres}
2747
2748 The option variable @code{resultant} controls which algorithm will be used to
2749 compute the resultant with the function @mrefdot{resultant}  The possible
2750 values are:
2751
2752 @table @code
2753 @item subres
2754 for the subresultant polynomial remainder sequence (PRS) algorithm,
2755 @item mod
2756 (not enabled) for the modular resultant algorithm, and
2757 @item red
2758 for the reduced polynomial remainder sequence (PRS) algorithm.
2759 @end table
2760
2761 On most problems the default value @code{subres} should be best.
2762 @c On some large degree univariate or bivariate problems @code{mod}
2763 @c may be better.
2764
2765 @opencatbox{Categories:}
2766 @category{Polynomials}
2767 @closecatbox
2768 @end defvr
2769
2770 @anchor{savefactors}
2771 @c -----------------------------------------------------------------------------
2772 @defvr {Option variable} savefactors
2773 Default value: @code{false}
2774
2775 @c "certain functions" -- WHICH ONES ??
2776 When @code{savefactors} is @code{true}, causes the factors of an
2777 expression which is a product of factors to be saved by certain
2778 functions in order to speed up later factorizations of expressions
2779 containing some of the same factors.
2780
2781 @opencatbox{Categories:}
2782 @category{Polynomials}
2783 @closecatbox
2784 @end defvr
2785
2786 @c -----------------------------------------------------------------------------
2787 @anchor{showratvars}
2788 @deffn {Function} showratvars (@var{expr})
2789
2790 Returns a list of the canonical rational expression (CRE) variables in
2791 expression @code{expr}.
2792
2793 See also @mrefdot{ratvars}
2794
2795 @opencatbox{Categories:}
2796 @category{Rational expressions}
2797 @category{Display functions}
2798 @closecatbox
2799 @end deffn
2800
2801 @c I CAN'T TELL WHAT THIS IS SUPPOSED TO BE ABOUT
2802
2803 @c -----------------------------------------------------------------------------
2804 @anchor{sqfr}
2805 @deffn {Function} sqfr (@var{expr})
2806
2807 is similar to @mref{factor} except that the polynomial factors are
2808 "square-free."  That is, they have factors only of degree one.
2809 This algorithm, which is also used by the first stage of @mrefcomma{factor} utilizes
2810 the fact that a polynomial has in common with its n'th derivative all
2811 its factors of degree greater than n.  Thus by taking greatest common divisors
2812 with the polynomial of
2813 the derivatives with respect to each variable in the polynomial, all
2814 factors of degree greater than 1 can be found.
2815
2816 Example:
2817
2818 @c ===beg===
2819 @c sqfr (4*x^4 + 4*x^3 - 3*x^2 - 4*x - 1);
2820 @c ===end===
2821 @example
2822 (%i1) sqfr (4*x^4 + 4*x^3 - 3*x^2 - 4*x - 1);
2823                                 2   2
2824 (%o1)                  (2 x + 1)  (x  - 1)
2825 @end example
2826
2827 @opencatbox{Categories:}
2828 @category{Polynomials}
2829 @closecatbox
2830 @end deffn
2831
2832 @c THIS ITEM STILL NEEDS WORK
2833
2834 @c -----------------------------------------------------------------------------
2835 @deffn  {Function} tellrat @
2836 @fname{tellrat} (@var{p_1}, @dots{}, @var{p_n}) @
2837 @fname{tellrat} ()
2838
2839 Adds to the ring of algebraic integers known to Maxima
2840 the elements which are the solutions of the polynomials @var{p_1}, @dots{},
2841 @var{p_n}.  Each argument @var{p_i} is a polynomial with integer coefficients.
2842
2843 @code{tellrat (@var{x})} effectively means substitute 0 for @var{x} in rational
2844 functions.
2845
2846 @code{tellrat ()} returns a list of the current substitutions.
2847
2848 @code{algebraic} must be set to @code{true} in order for the simplification of
2849 algebraic integers to take effect.
2850
2851 Maxima initially knows about the imaginary unit @code{%i}
2852 and all roots of integers.
2853
2854 There is a command @code{untellrat} which takes kernels and
2855 removes @code{tellrat} properties.
2856
2857 When @code{tellrat}'ing a multivariate
2858 polynomial, e.g., @code{tellrat (x^2 - y^2)}, there would be an ambiguity as to
2859 whether to substitute @code{@var{y}^2} for @code{@var{x}^2}
2860 or vice versa.
2861 Maxima picks a particular ordering, but if the user wants to specify which, e.g.
2862 @code{tellrat (y^2 = x^2)} provides a syntax which says replace
2863 @code{@var{y}^2} by @code{@var{x}^2}.
2864
2865 @c CAN'T TELL WHAT THIS IS ABOUT -- tellrat(w^3-1)$ algebraic:true$ rat(1/(w^2-w));
2866 @c DOES NOT YIELD AN ERROR, SO WHAT IS THE POINT ABOUT ratalgdenom ??
2867 @c When you @code{tellrat} reducible polynomials, you want to be careful not to
2868 @c attempt to rationalize a denominator with a zero divisor.  E.g.
2869 @c tellrat(w^3-1)$ algebraic:true$ rat(1/(w^2-w)); will give "quotient by
2870 @c zero".  This error can be avoided by setting @code{ratalgdenom} to @code{false}.
2871
2872 Examples:
2873
2874 @c ===beg===
2875 @c 10*(%i + 1)/(%i + 3^(1/3));
2876 @c ev (ratdisrep (rat(%)), algebraic);
2877 @c tellrat (1 + a + a^2);
2878 @c 1/(a*sqrt(2) - 1) + a/(sqrt(3) + sqrt(2));
2879 @c ev (ratdisrep (rat(%)), algebraic);
2880 @c tellrat (y^2 = x^2);
2881 @c ===end===
2882 @example
2883 (%i1) 10*(%i + 1)/(%i + 3^(1/3));
2884                            10 (%i + 1)
2885 (%o1)                      -----------
2886                                   1/3
2887                             %i + 3
2888 (%i2) ev (ratdisrep (rat(%)), algebraic);
2889              2/3      1/3              2/3      1/3
2890 (%o2)    (4 3    - 2 3    - 4) %i + 2 3    + 4 3    - 2
2891 (%i3) tellrat (1 + a + a^2);
2892                             2
2893 (%o3)                     [a  + a + 1]
2894 (%i4) 1/(a*sqrt(2) - 1) + a/(sqrt(3) + sqrt(2));
2895                       1                 a
2896 (%o4)           ------------- + -----------------
2897                 sqrt(2) a - 1   sqrt(3) + sqrt(2)
2898 (%i5) ev (ratdisrep (rat(%)), algebraic);
2899          (7 sqrt(3) - 10 sqrt(2) + 2) a - 2 sqrt(2) - 1
2900 (%o5)    ----------------------------------------------
2901                                7
2902 (%i6) tellrat (y^2 = x^2);
2903                         2    2   2
2904 (%o6)                 [y  - x , a  + a + 1]
2905 @end example
2906
2907 @opencatbox{Categories:}
2908 @category{Polynomials}
2909 @category{Rational expressions}
2910 @closecatbox
2911 @end deffn
2912
2913 @c -----------------------------------------------------------------------------
2914 @anchor{totaldisrep}
2915 @deffn {Function} totaldisrep (@var{expr})
2916
2917 Converts every subexpression of @var{expr} from canonical rational expressions
2918 (CRE) to general form and returns the result.
2919 If @var{expr} is itself in CRE form then @code{totaldisrep} is identical to
2920 @code{ratdisrep}.
2921
2922 @code{totaldisrep} may be useful for
2923 ratdisrepping expressions such as equations, lists, matrices, etc., which
2924 have some subexpressions in CRE form.
2925
2926 @c NEED EXAMPLES HERE
2927 @opencatbox{Categories:}
2928 @category{Rational expressions}
2929 @closecatbox
2930 @end deffn
2931
2932 @c -----------------------------------------------------------------------------
2933 @anchor{untelltat}
2934 @deffn {Function} untellrat (@var{x_1}, @dots{}, @var{x_n})
2935
2936 Removes @code{tellrat} properties from @var{x_1}, @dots{}, @var{x_n}.
2937
2938 @c NEED EXAMPLES HERE
2939 @opencatbox{Categories:}
2940 @category{Polynomials}
2941 @category{Rational expressions}
2942 @closecatbox
2943 @end deffn
2944