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
  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
  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
 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
 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
 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
 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
 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
 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
 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
 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
 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
 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
 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
 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
 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
 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
 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
 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
 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
 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 Examples:
 971
 972 @c EXPRESSIONS ADAPTED FROM demo ("lrats")
 973 @c ===beg===
 974 @c subst ([a = b, c = d], a + c);
 975 @c lratsubst ([a^2 = b, c^2 = d], (a + e)*c*(a + c));
 976 @c lratsubst (a^2 = b, a^3);
 977 @c ratsubst (b*a, a^2, a^3);
 978 @c fullratsubst (b*a, a^2, a^3);
 979 @c fullratsubst ([a^2 = b, b^2 = c, c^2 = a], a^3*b*c);
 980 @c fullratsubst (a^2 = b*a, a^3);
 981 @c ===end===
 982 @itemize @bullet
 983 @item
 984 @code{subst} can carry out multiple substitutions.
 985 @code{lratsubst} is analogous to @code{subst}.
 986 @end itemize
 987 @example
 988 (%i2) subst ([a = b, c = d], a + c);
 989 (%o2)                         d + b
 990 (%i3) lratsubst ([a^2 = b, c^2 = d], (a + e)*c*(a + c));
 991 (%o3)                (d + a c) e + a d + b c
 992 @end example
 993 @itemize @bullet
 994 @item
 995 If only one substitution is desired, then a single
 996 equation may be given as first argument.
 997 @end itemize
 998 @example
 999 (%i4) lratsubst (a^2 = b, a^3);
1000 (%o4)                          a b
1001 @end example
1002 @itemize @bullet
1003 @item
1004 @code{fullratsubst} is equivalent to @code{ratsubst}
1005 except that it recurses until its result stops changing.
1006 @end itemize
1007 @example
1008 (%i5) ratsubst (b*a, a^2, a^3);
1009                                2
1010 (%o5)                         a  b
1011 (%i6) fullratsubst (b*a, a^2, a^3);
1012                                  2
1013 (%o6)                         a b
1014 @end example
1015 @itemize @bullet
1016 @item
1017 @code{fullratsubst} also accepts a list of equations or a single
1018 equation as first argument.
1019 @end itemize
1020 @example
1021 (%i7) fullratsubst ([a^2 = b, b^2 = c, c^2 = a], a^3*b*c);
1022 (%o7)                           b
1023 (%i8) fullratsubst (a^2 = b*a, a^3);
1024                                  2
1025 (%o8)                         a b
1026 @end example
1027 @itemize @bullet
1028 @item
1029 @code{fullratsubst} catches potential infinite recursions. @ref{lrats_max_iter}.
1030 @end itemize
1031 @example
1032 (%i9) fullratsubst (b*a^2, a^2, a^3), lrats_max_iter=15;
1033 Warning: fullratsubst1(substexpr,forexpr,expr): reached maximum iterations of 15 . Increase `lrats_max_iter' to increase this limit.
1034                                      3  15
1035 (%o7)                               a  b
1036 @end example
1037
1038 See also @mref{lrats_max_iter} and @mref{fullratsubstflag}.
1039
1040 @opencatbox
1041 @category{Rational expressions}
1042 @closecatbox
1043 @end deffn
1044
1045 @c FULLRATSUBSTFLAG was undocumented until 2020-01
1046
1047 @c -----------------------------------------------------------------------------
1048 @anchor{fullratsubstflag}
1049 @defvr {Option variable} fullratsubstflag
1050 Default value: @code{false}
1051
1052 An option variable that is set to @code{true} in @mref{fullratsubst}.
1053
1054 @opencatbox
1055 @category{Polynomials}
1056 @category{Rational expressions}
1057 @closecatbox
1058 @end defvr
1059
1060
1061
1062 @c GCD IS A VARIABLE AND A FUNCTION
1063 @c THIS ITEM NEEDS A LOT OF WORK
1064
1065 @c -----------------------------------------------------------------------------
1066 @anchor{gcd}
1067 @deffn {Function} gcd (@var{p_1}, @var{p_2}, @var{x_1}, @dots{})
1068
1069 Returns the greatest common divisor of @var{p_1} and @var{p_2}.  The flag
1070 @code{gcd} determines which algorithm is employed.  Setting @code{gcd} to
1071 @code{ez}, @code{subres}, @code{red}, or @code{spmod} selects the @code{ezgcd},
1072 subresultant @code{prs}, reduced, or modular algorithm, respectively.  If
1073 @code{gcd} @code{false} then @code{gcd (@var{p_1}, @var{p_2}, @var{x})} always
1074 returns 1 for all @var{x}.  Many functions (e.g. @mrefcomma{ratsimp}@w{}
1075 @mrefcomma{factor} etc.) cause gcd's to be taken implicitly.  For homogeneous
1076 polynomials it is recommended that @code{gcd} equal to @code{subres} be used.
1077 To take the gcd when an algebraic is present, e.g.,
1078 @code{gcd (@var{x}^2 - 2*sqrt(2)* @var{x} + 2, @var{x} - sqrt(2))}, the option
1079 variable @mref{algebraic} must be @code{true} and @code{gcd} must not be
1080 @code{ez}.
1081
1082 The @code{gcd} flag, default: @code{spmod}, if @code{false} will also prevent
1083 the greatest common divisor from being taken when expressions are converted to
1084 canonical rational expression (CRE) form.  This will sometimes speed the
1085 calculation if gcds are not required.
1086
1087 See also @mrefcomma{ezgcd} @mrefcomma{gcdex} @mrefcomma{gcdivide} and
1088 @mrefdot{poly_gcd}
1089
1090 Example:
1091
1092 @c ===beg===
1093 @c p1:6*x^3+19*x^2+19*x+6;
1094 @c p2:6*x^5+13*x^4+12*x^3+13*x^2+6*x;
1095 @c gcd(p1, p2);
1096 @c p1/gcd(p1, p2), ratsimp;
1097 @c p2/gcd(p1, p2), ratsimp;
1098 @c ===end===
1099 @example
1100 (%i1) p1:6*x^3+19*x^2+19*x+6;
1101                         3       2
1102 (%o1)                6 x  + 19 x  + 19 x + 6
1103 (%i2) p2:6*x^5+13*x^4+12*x^3+13*x^2+6*x;
1104                   5       4       3       2
1105 (%o2)          6 x  + 13 x  + 12 x  + 13 x  + 6 x
1106 (%i3) gcd(p1, p2);
1107                             2
1108 (%o3)                    6 x  + 13 x + 6
1109 (%i4) p1/gcd(p1, p2), ratsimp;
1110 (%o4)                         x + 1
1111 (%i5) p2/gcd(p1, p2), ratsimp;
1112                               3
1113 (%o5)                        x  + x
1114 @end example
1115
1116 @mref{ezgcd} returns a list whose first element is the greatest common divisor
1117 of the polynomials @var{p_1} and @var{p_2}, and whose remaining elements are
1118 the polynomials divided by the greatest common divisor.
1119
1120 @c ===beg===
1121 @c ezgcd(p1, p2);
1122 @c ===end===
1123 @example
1124 (%i6) ezgcd(p1, p2);
1125                     2                     3
1126 (%o6)           [6 x  + 13 x + 6, x + 1, x  + x]
1127 @end example
1128
1129 @opencatbox
1130 @category{Polynomials}
1131 @category{Rational expressions}
1132 @closecatbox
1133 @end deffn
1134
1135 @c IN NEED OF SERIOUS CLARIFICATION HERE
1136
1137 @c -----------------------------------------------------------------------------
1138 @anchor{gcdex}
1139 @deffn  {Function} gcdex @
1140 @fname{gcdex} (@var{f}, @var{g}) @
1141 @fname{gcdex} (@var{f}, @var{g}, @var{x})
1142
1143 Returns a list @code{[@var{a}, @var{b}, @var{u}]} where @var{u} is the greatest
1144 common divisor (gcd) of @var{f} and @var{g}, and @var{u} is equal to
1145 @code{@var{a} @var{f} + @var{b} @var{g}}.  The arguments @var{f} and @var{g}
1146 should be univariate polynomials, or else polynomials in @var{x} a supplied
1147 main variable since we need to be in a principal ideal domain for this to
1148 work.  The gcd means the gcd regarding @var{f} and @var{g} as univariate
1149 polynomials with coefficients being rational functions in the other variables.
1150
1151 @code{gcdex} implements the Euclidean algorithm, where we have a sequence of
1152 @code{L[i]: [a[i], b[i], r[i]]} which are all perpendicular to @code{[f, g, -1]}
1153 and the next one is built as if @code{q = quotient(r[i]/r[i+1])} then
1154 @code{L[i+2]: L[i] - q L[i+1]}, and it terminates at @code{L[i+1]} when the
1155 remainder @code{r[i+2]} is zero.
1156
1157 The arguments @var{f} and @var{g} can be integers.  For this case the function
1158 @mref{igcdex} is called by @code{gcdex}.
1159
1160 See also @mrefcomma{ezgcd} @mrefcomma{gcd} @mrefcomma{gcdivide} and
1161 @mrefdot{poly_gcd}
1162
1163 Examples:
1164
1165 @c ===beg===
1166 @c gcdex (x^2 + 1, x^3 + 4);
1167 @c % . [x^2 + 1, x^3 + 4, -1];
1168 @c ===end===
1169 @example
1170 @group
1171 (%i1) gcdex (x^2 + 1, x^3 + 4);
1172                        2
1173                       x  + 4 x - 1  x + 4
1174 (%o1)/R/           [- ------------, -----, 1]
1175                            17        17
1176 @end group
1177 @group
1178 (%i2) % . [x^2 + 1, x^3 + 4, -1];
1179 (%o2)/R/                        0
1180 @end group
1181 @end example
1182
1183 @c SORRY FOR BEING DENSE BUT WHAT IS THIS ABOUT EXACTLY
1184 Note that the gcd in the following is @code{1} since we work in @code{k(y)[x]},
1185 not the  @code{y+1} we would expect in @code{k[y, x]}.
1186
1187 @c ===beg===
1188 @c gcdex (x*(y + 1), y^2 - 1, x);
1189 @c ===end===
1190 @example
1191 @group
1192 (%i1) gcdex (x*(y + 1), y^2 - 1, x);
1193                                1
1194 (%o1)/R/                 [0, ------, 1]
1195                               2
1196                              y  - 1
1197 @end group
1198 @end example
1199
1200 @opencatbox
1201 @category{Polynomials}
1202 @category{Rational expressions}
1203 @closecatbox
1204 @end deffn
1205
1206 @c CHOOSE ONE CHARACTERIZATION OF "GAUSSIAN INTEGERS" AND USE IT WHERE GAUSSIAN INTEGERS ARE REFERENCED
1207
1208 @c -----------------------------------------------------------------------------
1209 @anchor{gcfactor}
1210 @deffn {Function} gcfactor (@var{n})
1211
1212 Factors the Gaussian integer @var{n} over the Gaussian integers, i.e., numbers
1213 of the form @code{@var{a} + @var{b} @code{%i}} where @var{a} and @var{b} are
1214 rational integers (i.e.,  ordinary integers).  Factors are normalized by making
1215 @var{a} and @var{b} non-negative.
1216 @c NEED EXAMPLES HERE
1217
1218 @opencatbox
1219 @category{Integers}
1220 @closecatbox
1221 @end deffn
1222
1223 @c CHOOSE ONE CHARACTERIZATION OF "GAUSSIAN INTEGERS" AND USE IT WHERE GAUSSIAN INTEGERS ARE REFERENCED
1224
1225 @c -----------------------------------------------------------------------------
1226 @anchor{gfactor}
1227 @deffn {Function} gfactor (@var{expr})
1228
1229 Factors the polynomial @var{expr} over the Gaussian integers
1230 (that is, the integers with the imaginary unit @code{%i} adjoined).
1231 @c "This is like" -- IS IT THE SAME OR NOT ??
1232 This is like @code{factor (@var{expr}, @var{a}^2+1)} where @var{a} is @code{%i}.
1233
1234 Example:
1235
1236 @c ===beg===
1237 @c gfactor (x^4 - 1);
1238 @c ===end===
1239 @example
1240 (%i1) gfactor (x^4 - 1);
1241 (%o1)           (x - 1) (x + 1) (x - %i) (x + %i)
1242 @end example
1243
1244 @opencatbox
1245 @category{Polynomials}
1246 @closecatbox
1247 @end deffn
1248
1249 @c DESCRIBE THIS INDEPENDENTLY OF factorsum
1250 @c THIS ITEM NEEDS MORE WORK
1251
1252 @c -----------------------------------------------------------------------------
1253 @anchor{gfactorsum}
1254 @deffn {Function} gfactorsum (@var{expr})
1255
1256 is similar to @code{factorsum} but applies @code{gfactor} instead
1257 of @code{factor}.
1258
1259 @opencatbox
1260 @category{Expressions}
1261 @closecatbox
1262 @end deffn
1263
1264 @c -----------------------------------------------------------------------------
1265 @anchor{hipow}
1266 @deffn {Function} hipow (@var{expr}, @var{x})
1267
1268 Returns the highest explicit exponent of @var{x} in @var{expr}.
1269 @var{x} may be a variable or a general expression.
1270 If @var{x} does not appear in @var{expr},
1271 @code{hipow} returns @code{0}.
1272
1273 @code{hipow} does not consider expressions equivalent to @code{expr}.  In
1274 particular, @code{hipow} does not expand @code{expr}, so
1275 @code{hipow (@var{expr}, @var{x})} and
1276 @code{hipow (expand (@var{expr}, @var{x}))} may yield different results.
1277
1278 Examples:
1279
1280 @c ===beg===
1281 @c hipow (y^3 * x^2 + x * y^4, x);
1282 @c hipow ((x + y)^5, x);
1283 @c hipow (expand ((x + y)^5), x);
1284 @c hipow ((x + y)^5, x + y);
1285 @c hipow (expand ((x + y)^5), x + y);
1286 @c ===end===
1287 @example
1288 (%i1) hipow (y^3 * x^2 + x * y^4, x);
1289 (%o1)                           2
1290 (%i2) hipow ((x + y)^5, x);
1291 (%o2)                           1
1292 (%i3) hipow (expand ((x + y)^5), x);
1293 (%o3)                           5
1294 (%i4) hipow ((x + y)^5, x + y);
1295 (%o4)                           5
1296 (%i5) hipow (expand ((x + y)^5), x + y);
1297 (%o5)                           0
1298 @end example
1299
1300 @opencatbox
1301 @category{Expressions}
1302 @closecatbox
1303 @end deffn
1304
1305 @c I SUSPECT THE FOLLOWING TEXT IS OUTDATED DUE TO CHANGES IN INTEGER FACTORING CODE
1306
1307 @anchor{intfaclim}
1308 @c -----------------------------------------------------------------------------
1309 @defvr {Option variable} intfaclim
1310 Default value: true
1311
1312 If @code{true}, maxima will give up factorization of
1313 integers if no factor is found after trial divisions and Pollard's rho
1314 method and factorization will not be complete.
1315
1316 When @code{intfaclim} is @code{false} (this is the case when the user
1317 calls @code{factor} explicitly), complete factorization will be
1318 attempted.  @code{intfaclim} is set to @code{false} when factors are
1319 computed in @code{divisors}, @code{divsum} and @code{totient}.
1320 @c ANY OTHERS ??
1321
1322 @c WHAT ARE THESE MYSTERIOUS INTERNAL CALLS ?? (LET'S JUST LIST THE FUNCTIONS INVOLVED)
1323 Internal calls to @code{factor} respect the user-specified value of
1324 @code{intfaclim}.  Setting @code{intfaclim} to @code{true} may reduce
1325 the time spent factoring large integers.
1326 @c NEED EXAMPLES HERE
1327
1328 @opencatbox
1329 @category{Integers}
1330 @closecatbox
1331 @end defvr
1332
1333 @c -----------------------------------------------------------------------------
1334 @defvr {Option variable} keepfloat
1335 Default value: @code{false}
1336
1337 When @code{keepfloat} is @code{true}, prevents floating
1338 point numbers from being rationalized when expressions which contain
1339 them are converted to canonical rational expression (CRE) form.
1340
1341 Note that the function @code{solve} and those functions calling it
1342 (@code{eigenvalues}, for example) currently ignore this flag, converting
1343 floating point numbers anyway.
1344
1345 Examples:
1346
1347 @c ===beg===
1348 @c rat(x/2.0);
1349 @c rat(x/2.0), keepfloat;
1350 @c ===end===
1351 @example
1352 @group
1353 (%i1) rat(x/2.0);
1354
1355 rat: replaced 0.5 by 1/2 = 0.5
1356                                 x
1357 (%o1)/R/                        -
1358                                 2
1359 @end group
1360 @group
1361 (%i2) rat(x/2.0), keepfloat;
1362 (%o2)/R/                      0.5 x
1363 @end group
1364 @end example
1365
1366 @code{solve} ignores @code{keepfloat}:
1367
1368 @c ===beg===
1369 @c solve(1.0-x,x), keepfloat;
1370 @c ===end===
1371 @example
1372 @group
1373 (%i1) solve(1.0-x,x), keepfloat;
1374
1375 rat: replaced 1.0 by 1/1 = 1.0
1376 (%o1)                        [x = 1]
1377 @end group
1378 @end example
1379
1380 @opencatbox
1381 @category{Numerical evaluation}
1382 @closecatbox
1383 @end defvr
1384
1385 @c -----------------------------------------------------------------------------
1386 @anchor{lowpow}
1387 @deffn {Function} lopow (@var{expr}, @var{x})
1388
1389 Returns the lowest exponent of @var{x} which explicitly appears in
1390 @var{expr}.  Thus
1391
1392 @c ===beg===
1393 @c lopow ((x+y)^2 + (x+y)^a, x+y);
1394 @c ===end===
1395 @example
1396 (%i1) lopow ((x+y)^2 + (x+y)^a, x+y);
1397 (%o1)                       min(a, 2)
1398 @end example
1399
1400 @opencatbox
1401 @category{Expressions}
1402 @closecatbox
1403 @end deffn
1404
1405 @c DESCRIBE lratsubst INDEPENDENTLY OF subst
1406 @c THIS ITEM NEEDS MORE WORK
1407
1408 @c -----------------------------------------------------------------------------
1409 @anchor{lratsubst}
1410 @deffn {Function} lratsubst (@var{new}, @var{old}, @var{expr}) @
1411 @fname{lratsubst} (@code{@var{old} = @var{new}}, @var{expr}) @
1412 @fname{lratsubst} (@code{[ @var{old_1} = @var{new_1}, @dots{}, @var{old_n} = @var{new_n} ]}, @var{expr})
1413
1414 @code{lratsubst} is analogous to @mref{subst} except that it uses
1415 @code{ratsubst} to perform substitutions.
1416
1417 The first argument of @code{lratsubst} is an equation, a list of
1418 equations or a list of unit length whose first element is a list of
1419 equations (that is, the first argument is identical in format to that
1420 accepted by @code{subst}). The substitutions are made in the order given
1421 by the list of equations, that is, from left to right.
1422
1423 Examples:
1424
1425 @c EXPRESSIONS ADAPTED FROM demo ("lrats")
1426 @c THIS STUFF CAN PROBABLY STAND REVISION -- EXAMPLES DON'T SEEM VERY ENLIGHTENING
1427
1428 @c ===beg===
1429 @c lratsubst ([a = b, c = d], a + c);
1430 @c lratsubst ([a^2 = b, c^2 = d], (a + e)*c*(a + c));
1431 @c lratsubst (a^2 = b, a^3);
1432 @c lratsubst ([[a^2=b*a, b=c]], a^3);
1433 @c errcatch(lratsubst ([[a^2=b*a, b=c],[a=b]], a^3));
1434 @c ===end===
1435
1436 @itemize @bullet
1437 @item
1438 @code{subst} can carry out multiple substitutions.
1439 @code{lratsubst} is analogous to @code{subst}.
1440 @end itemize
1441 @example
1442 (%i2) lratsubst ([a = b, c = d], a + c);
1443 (%o2)                         d + b
1444 (%i3) lratsubst ([a^2 = b, c^2 = d], (a + e)*c*(a + c));
1445 (%o3)                (d + a c) e + a d + b c
1446 @end example
1447 @itemize @bullet
1448 @item
1449 If only one substitution is desired, then a single
1450 equation may be given as first argument.
1451 @end itemize
1452 @example
1453 (%i4) lratsubst (a^2 = b, a^3);
1454 (%o4)                          a b
1455 @end example
1456 @itemize @bullet
1457 @item
1458 A nested list of substitutions can be used--but it must contain only one list.
1459 @end itemize
1460 @example
1461 (%i5) lratsubst ([[a^2=b*a, b=c]], a^3);
1462
1463                                       2
1464 (%o5)                               a  c
1465 (%i6) lratsubst ([[a^2=b*a, b=c],[a=b]], a^3);
1466
1467
1468                                  2
1469 lratsubst: improper argument: [[a  = a b, b = c], [a = b]]
1470 #0: lratsubst(listofeqns=[[a^2 = a*b,b = c],[a = b]],expr=a^3)
1471  -- an error. To debug this try: debugmode(true);
1472
1473 @end example
1474
1475 See also @mref{fullratsubst}.
1476
1477 @opencatbox
1478 @category{Polynomials}
1479 @category{Rational expressions}
1480 @closecatbox
1481 @end deffn
1482
1483
1484 @c -----------------------------------------------------------------------------
1485 @anchor{lrats_max_iter}
1486 @defvr {Option variable} lrats_max_iter
1487 Default value: @code{100000}
1488
1489 The upper limit on the number of iterations that @mref{fullratsubst} and
1490 @mref{lratsubst} may perform. It must be set to a positive integer. See
1491 the example for @mref{fullratsubst}.
1492
1493 @opencatbox
1494 @category{Polynomials}
1495 @category{Rational expressions}
1496 @closecatbox
1497 @end defvr
1498
1499
1500 @c -----------------------------------------------------------------------------
1501 @anchor{modulus}
1502 @defvr {Option variable} modulus
1503 Default value: @code{false}
1504
1505 When @code{modulus} is a positive number @var{p}, operations on canonical rational
1506 expressions (CREs, as returned by @code{rat} and related functions) are carried out
1507 modulo @var{p}, using the so-called "balanced" modulus system in which @code{@var{n}
1508 modulo @var{p}} is defined as an integer @var{k} in
1509 @code{[-(@var{p}-1)/2, ..., 0, ..., (@var{p}-1)/2]} when @var{p} is odd, or
1510 @code{[-(@var{p}/2 - 1), ..., 0, ...., @var{p}/2]} when @var{p} is even, such
1511 that @code{@var{a} @var{p} + @var{k}} equals @var{n} for some integer @var{a}.
1512 @c NEED EXAMPLES OF "BALANCED MODULUS" HERE
1513
1514 @c WHAT CAN THIS MEAN ?? IS THE MODULUS STORED WITH THE EXPRESSION ??
1515 @c "... in order to get correct results" -- WHAT DO YOU GET IF YOU DON'T RE-RAT ??
1516 If @var{expr} is already in canonical rational expression (CRE) form when
1517 @code{modulus} is reset, then you may need to re-rat @var{expr}, e.g.,
1518 @code{expr: rat (ratdisrep (expr))}, in order to get correct results.
1519
1520 Typically @code{modulus} is set to a prime number.  If @code{modulus} is set to
1521 a positive non-prime integer, this setting is accepted, but a warning message is
1522 displayed.  Maxima signals an error, when zero or a negative integer is
1523 assigned to @code{modulus}.
1524
1525 Examples:
1526
1527 @c ===beg===
1528 @c modulus:7;
1529 @c polymod([0,1,2,3,4,5,6,7]);
1530 @c modulus:false;
1531 @c poly:x^6+x^2+1;
1532 @c factor(poly);
1533 @c modulus:13;
1534 @c factor(poly);
1535 @c polymod(%);
1536 @c ===end===
1537 @example
1538 (%i1) modulus:7;
1539 (%o1)                           7
1540 (%i2) polymod([0,1,2,3,4,5,6,7]);
1541 (%o2)            [0, 1, 2, 3, - 3, - 2, - 1, 0]
1542 (%i3) modulus:false;
1543 (%o3)                         false
1544 (%i4) poly:x^6+x^2+1;
1545                             6    2
1546 (%o4)                      x  + x  + 1
1547 (%i5) factor(poly);
1548                             6    2
1549 (%o5)                      x  + x  + 1
1550 (%i6) modulus:13;
1551 (%o6)                          13
1552 (%i7) factor(poly);
1553                       2        4      2
1554 (%o7)               (x  + 6) (x  - 6 x  - 2)
1555 (%i8) polymod(%);
1556                             6    2
1557 (%o8)                      x  + x  + 1
1558 @end example
1559 @opencatbox
1560 @category{Integers}
1561 @closecatbox
1562 @end defvr
1563
1564 @c APPARENTLY OBSOLETE: ONLY EFFECT OF $newfac COULD BE TO CAUSE NONEXISTENT FUNCTION NMULTFACT
1565 @c TO BE CALLED (IN FUNCTION FACTOR72 IN src/factor.lisp CIRCA LINE 1400)
1566 @c $newfac NOT USED IN ANY OTHER CONTEXT (ASIDE FROM DECLARATIONS)
1567 @c COMMENT IT OUT NOW, CUT IT ON THE NEXT PASS THROUGH THIS FILE
1568 @c @defvar newfac
1569 @c Default value: @code{false}
1570 @c
1571 @c When @code{newfac} is @code{true}, @code{factor} will use the new factoring
1572 @c routines.
1573 @c
1574 @c @end defvar
1575
1576 @c -----------------------------------------------------------------------------
1577 @anchor{num}
1578 @deffn {Function} num (@var{expr})
1579
1580 Returns the numerator of @var{expr} if it is a ratio.
1581 If @var{expr} is not a ratio, @var{expr} is returned.
1582
1583 @code{num} evaluates its argument.
1584
1585 See also @mref{denom}
1586
1587 @c ===beg===
1588 @c g1:(x+2)*(x+1)/((x+3)^2);
1589 @c num(g1);
1590 @c g2:sin(x)/10*cos(x)/y;
1591 @c num(g2);
1592 @c ===end===
1593 @example
1594 @group
1595 (%i1) g1:(x+2)*(x+1)/((x+3)^2);
1596                          (x + 1) (x + 2)
1597 (%o1)                    ---------------
1598                                    2
1599                             (x + 3)
1600 @end group
1601 @group
1602 (%i2) num(g1);
1603 (%o2)                    (x + 1) (x + 2)
1604 @end group
1605 @group
1606 (%i3) g2:sin(x)/10*cos(x)/y;
1607                           cos(x) sin(x)
1608 (%o3)                     -------------
1609                               10 y
1610 @end group
1611 @group
1612 (%i4) num(g2);
1613 (%o4)                     cos(x) sin(x)
1614 @end group
1615 @end example
1616
1617 @c NEED SOME EXAMPLES HERE
1618 @opencatbox
1619 @category{Expressions}
1620 @closecatbox
1621 @end deffn
1622
1623 @c -----------------------------------------------------------------------------
1624 @anchor{polydecomp}
1625 @deffn {Function} polydecomp (@var{p}, @var{x})
1626
1627 Decomposes the polynomial @var{p} in the variable @var{x}
1628 into the functional composition of polynomials in @var{x}.
1629 @code{polydecomp} returns a list @code{[@var{p_1}, ..., @var{p_n}]} such that
1630
1631 @example
1632 lambda ([x], p_1) (lambda ([x], p_2) (... (lambda ([x], p_n) (x))
1633   ...))
1634 @end example
1635
1636 is equal to @var{p}.
1637 The degree of @var{p_i} is greater than 1 for @var{i} less than @var{n}.
1638
1639 Such a decomposition is not unique.
1640
1641 Examples:
1642
1643 @c ===beg===
1644 @c polydecomp (x^210, x);
1645 @c p : expand (subst (x^3 - x - 1, x, x^2 - a));
1646 @c polydecomp (p, x);
1647 @c ===end===
1648 @example
1649 @group
1650 (%i1) polydecomp (x^210, x);
1651                           7   5   3   2
1652 (%o1)                   [x , x , x , x ]
1653 @end group
1654 @group
1655 (%i2) p : expand (subst (x^3 - x - 1, x, x^2 - a));
1656                 6      4      3    2
1657 (%o2)          x  - 2 x  - 2 x  + x  + 2 x - a + 1
1658 @end group
1659 @group
1660 (%i3) polydecomp (p, x);
1661                         2       3
1662 (%o3)                 [x  - a, x  - x - 1]
1663 @end group
1664 @end example
1665
1666 The following function composes @code{L = [e_1, ..., e_n]} as functions in
1667 @code{x}; it is the inverse of polydecomp:
1668
1669 @c ===beg===
1670 @c compose (L, x) :=
1671 @c   block ([r : x], for e in L do r : subst (e, x, r), r) $
1672 @c ===end===
1673 @example
1674 @group
1675 (%i1) compose (L, x) :=
1676   block ([r : x], for e in L do r : subst (e, x, r), r) $
1677 @end group
1678 @end example
1679
1680 Re-express above example using @code{compose}:
1681
1682 @c ===beg===
1683 @c polydecomp (compose ([x^2 - a, x^3 - x - 1], x), x);
1684 @c ===end===
1685 @example
1686 @group
1687 (%i1) polydecomp (compose ([x^2 - a, x^3 - x - 1], x), x);
1688                           2       3
1689 (%o1)          [compose([x  - a, x  - x - 1], x)]
1690 @end group
1691 @end example
1692
1693 Note that though @code{compose (polydecomp (@var{p}, @var{x}), @var{x})} always
1694 returns @var{p} (unexpanded), @code{polydecomp (compose ([@var{p_1}, ...,
1695 @var{p_n}], @var{x}), @var{x})} does @i{not} necessarily return
1696 @code{[@var{p_1}, ..., @var{p_n}]}:
1697
1698 @c ===beg===
1699 @c polydecomp (compose ([x^2 + 2*x + 3, x^2], x), x);
1700 @c polydecomp (compose ([x^2 + x + 1, x^2 + x + 1], x), x);
1701 @c ===end===
1702 @example
1703 @group
1704 (%i1) polydecomp (compose ([x^2 + 2*x + 3, x^2], x), x);
1705                            2             2
1706 (%o1)           [compose([x  + 2 x + 3, x ], x)]
1707 @end group
1708 @group
1709 (%i2) polydecomp (compose ([x^2 + x + 1, x^2 + x + 1], x), x);
1710                         2           2
1711 (%o2)        [compose([x  + x + 1, x  + x + 1], x)]
1712 @end group
1713 @end example
1714
1715 @opencatbox
1716 @category{Polynomials}
1717 @closecatbox
1718 @end deffn
1719
1720 @c -----------------------------------------------------------------------------
1721 @anchor{polymod}
1722 @deffn  {Function} polymod @
1723 @fname{polymod} (@var{p}) @
1724 @fname{polymod} (@var{p}, @var{m})
1725
1726 Converts the polynomial @var{p} to a modular representation with respect to the
1727 current modulus which is the value of the variable @code{modulus}.
1728
1729 @code{polymod (@var{p}, @var{m})} specifies a modulus @var{m} to be used
1730 instead of the current value of @code{modulus}.
1731
1732 See @mrefdot{modulus}
1733
1734 @opencatbox
1735 @category{Polynomials}
1736 @closecatbox
1737 @end deffn
1738
1739 @c ISN'T THERE AN EQUIVALENT FUNCTION SOMEWHERE ??
1740 @c NEEDS WORK (IF KEPT)
1741
1742 @c -----------------------------------------------------------------------------
1743 @anchor{polynomialp}
1744 @deffn  {Function} polynomialp @
1745 @fname{polynomialp} (@var{p}, @var{L}, @var{coeffp}, @var{exponp}) @
1746 @fname{polynomialp} (@var{p}, @var{L}, @var{coeffp}) @
1747 @fname{polynomialp} (@var{p}, @var{L})
1748
1749 Return @code{true} if @var{p} is a polynomial in the variables in the list
1750 @var{L}.  The predicate @var{coeffp} must evaluate to @code{true} for each
1751 coefficient, and the predicate @var{exponp} must evaluate to @code{true} for all
1752 exponents of the variables in @var{L}.  If you want to use a non-default value
1753 for @var{exponp}, you must supply @var{coeffp} with a value even if you want
1754 to use the default for @var{coeffp}.
1755
1756 @c WORK THE FOLLOWING INTO THE PRECEDING
1757 The command @code{polynomialp (@var{p}, @var{L}, @var{coeffp})} is equivalent to
1758 @code{polynomialp (@var{p}, @var{L}, @var{coeffp}, 'nonnegintegerp)} and the
1759 command @code{polynomialp (@var{p}, @var{L})} is equivalent to
1760 @code{polynomialp (@var{p}, L@var{,} 'constantp, 'nonnegintegerp)}.
1761
1762 The polynomial needn't be expanded:
1763
1764 @c ===beg===
1765 @c polynomialp ((x + 1)*(x + 2), [x]);
1766 @c polynomialp ((x + 1)*(x + 2)^a, [x]);
1767 @c ===end===
1768 @example
1769 (%i1) polynomialp ((x + 1)*(x + 2), [x]);
1770 (%o1)                         true
1771 (%i2) polynomialp ((x + 1)*(x + 2)^a, [x]);
1772 (%o2)                         false
1773 @end example
1774
1775 An example using non-default values for coeffp and exponp:
1776
1777 @c ===beg===
1778 @c polynomialp ((x + 1)*(x + 2)^(3/2), [x], numberp, numberp);
1779 @c polynomialp ((x^(1/2) + 1)*(x + 2)^(3/2), [x], numberp,
1780 @c                                                        numberp);
1781 @c ===end===
1782 @example
1783 (%i1) polynomialp ((x + 1)*(x + 2)^(3/2), [x], numberp, numberp);
1784 (%o1)                         true
1785 (%i2) polynomialp ((x^(1/2) + 1)*(x + 2)^(3/2), [x], numberp,
1786                                                         numberp);
1787 (%o2)                         true
1788 @end example
1789
1790 Polynomials with two variables:
1791
1792 @c ===beg===
1793 @c polynomialp (x^2 + 5*x*y + y^2, [x]);
1794 @c polynomialp (x^2 + 5*x*y + y^2, [x, y]);
1795 @c ===end===
1796 @example
1797 (%i1) polynomialp (x^2 + 5*x*y + y^2, [x]);
1798 (%o1)                         false
1799 (%i2) polynomialp (x^2 + 5*x*y + y^2, [x, y]);
1800 (%o2)                         true
1801 @end example
1802
1803 @opencatbox
1804 @category{Predicate functions}
1805 @category{Polynomials}
1806 @closecatbox
1807 @end deffn
1808
1809 @c -----------------------------------------------------------------------------
1810 @anchor{quotient}
1811 @deffn  {Function} quotient @
1812 @fname{quotient} (@var{p_1}, @var{p_2}) @
1813 @fname{quotient} (@var{p_1}, @var{p_2}, @var{x_1}, @dots{}, @var{x_n})
1814
1815 Returns the polynomial @var{p_1} divided by the polynomial @var{p_2}.  The
1816 arguments @var{x_1}, @dots{}, @var{x_n} are interpreted as in @code{ratvars}.
1817
1818 @code{quotient} returns the first element of the two-element list returned by
1819 @mref{divide}.
1820
1821 @c NEED SOME EXAMPLES HERE
1822 @opencatbox
1823 @category{Polynomials}
1824 @closecatbox
1825 @end deffn
1826
1827 @c THIS ITEM CAN PROBABLY BE IMPROVED
1828
1829 @c -----------------------------------------------------------------------------
1830 @anchor{rat}
1831 @deffn  {Function} rat @
1832 @fname{rat} (@var{expr}) @
1833 @fname{rat} (@var{expr}, @var{x_1}, @dots{}, @var{x_n})
1834
1835 Converts @var{expr} to canonical rational expression (CRE) form by expanding and
1836 combining all terms over a common denominator and cancelling out the
1837 greatest common divisor of the numerator and denominator, as well as
1838 converting floating point numbers to rational numbers within a
1839 tolerance of @code{ratepsilon}.
1840 The variables are ordered according
1841 to the @var{x_1}, @dots{}, @var{x_n}, if specified, as in @code{ratvars}.
1842
1843 @code{rat} does not generally simplify functions other than addition @code{+},
1844 subtraction @code{-}, multiplication @code{*}, division @code{/}, and
1845 exponentiation to an integer power,
1846 whereas @code{ratsimp} does handle those cases.
1847 Note that atoms (numbers and variables) in CRE form are not the
1848 same as they are in the general form.
1849 For example, @code{rat(x)- x} yields
1850 @code{rat(0)} which has a different internal representation than 0.
1851
1852 @c WHAT'S THIS ABOUT EXACTLY ??
1853 When @code{ratfac} is @code{true}, @code{rat} yields a partially factored
1854 form for CRE.  During rational operations the expression is
1855 maintained as fully factored as possible without an actual call to the
1856 factor package.  This should always save space and may save some time
1857 in some computations.  The numerator and denominator are still made
1858 relatively prime
1859 (e.g.,  @code{rat((x^2 - 1)^4/(x + 1)^2)} yields @code{(x - 1)^4 (x + 1)^2}
1860 when @code{ratfac} is @code{true}),
1861 but the factors within each part may not be relatively prime.
1862
1863 @code{ratprint} if @code{false} suppresses the printout of the message
1864 informing the user of the conversion of floating point numbers to
1865 rational numbers.
1866
1867 @code{keepfloat} if @code{true} prevents floating point numbers from being
1868 converted to rational numbers.
1869
1870 See also @code{ratexpand} and  @code{ratsimp}.
1871
1872 Examples:
1873 @c ===beg===
1874 @c ((x - 2*y)^4/(x^2 - 4*y^2)^2 + 1)*(y + a)*(2*y + x) /
1875 @c       (4*y^2 + x^2);
1876 @c rat (%, y, a, x);
1877 @c ===end===
1878 @example
1879 @group
1880 (%i1) ((x - 2*y)^4/(x^2 - 4*y^2)^2 + 1)*(y + a)*(2*y + x) /
1881       (4*y^2 + x^2);
1882                                            4
1883                                   (x - 2 y)
1884               (y + a) (2 y + x) (------------ + 1)
1885                                    2      2 2
1886                                  (x  - 4 y )
1887 (%o1)         ------------------------------------
1888                               2    2
1889                            4 y  + x
1890 @end group
1891 @group
1892 (%i2) rat (%, y, a, x);
1893                             2 a + 2 y
1894 (%o2)/R/                    ---------
1895                              x + 2 y
1896 @end group
1897 @end example
1898
1899 @opencatbox
1900 @category{Rational expressions}
1901 @closecatbox
1902 @end deffn
1903
1904 @defvr {Option variable} ratalgdenom
1905 Default value: @code{true}
1906
1907 When @code{ratalgdenom} is @code{true}, allows rationalization of denominators
1908 with respect to radicals to take effect.  @code{ratalgdenom} has an effect only
1909 when canonical rational expressions (CRE) are used in algebraic mode.
1910
1911 @opencatbox
1912 @category{Simplification flags and variables}
1913 @closecatbox
1914 @end defvr
1915
1916 @c THIS ITEM NEEDS MORE WORK
1917
1918 @c -----------------------------------------------------------------------------
1919 @anchor{ratcoef}
1920 @deffn  {Function} ratcoef @
1921 @fname{ratcoef} (@var{expr}, @var{x}, @var{n}) @
1922 @fname{ratcoef} (@var{expr}, @var{x})
1923
1924 Returns the coefficient of the expression @code{@var{x}^@var{n}}
1925 in the expression @var{expr}.
1926 If omitted, @var{n} is assumed to be 1.
1927
1928 The return value is free
1929 (except possibly in a non-rational sense) of the variables in @var{x}.
1930 If no coefficient of this type exists, 0 is returned.
1931
1932 @code{ratcoef}
1933 expands and rationally simplifies its first argument and thus it may
1934 produce answers different from those of @code{coeff} which is purely
1935 syntactic.
1936 @c MOVE THIS TO EXAMPLES SECTION
1937 Thus @code{ratcoef ((x + 1)/y + x, x)} returns @code{(y + 1)/y} whereas
1938 @code{coeff} returns 1.
1939
1940 @code{ratcoef (@var{expr}, @var{x}, 0)}, viewing @var{expr} as a sum,
1941 returns a sum of those terms which do not contain @var{x}.
1942 @c "SHOULD NOT" -- WHAT DOES THIS MEAN ??
1943 Therefore if @var{x} occurs to any negative powers, @code{ratcoef} should not
1944 be used.
1945
1946 @c WHAT IS THE INTENT HERE ??
1947 Since @var{expr} is rationally
1948 simplified before it is examined, coefficients may not appear quite
1949 the way they were envisioned.
1950
1951 Example:
1952
1953 @c ===beg===
1954 @c s: a*x + b*x + 5$
1955 @c ratcoef (s, a + b);
1956 @c ===end===
1957 @example
1958 (%i1) s: a*x + b*x + 5$
1959 (%i2) ratcoef (s, a + b);
1960 (%o2)                           x
1961 @end example
1962 @c NEED MORE EXAMPLES HERE
1963
1964 @opencatbox
1965 @category{Polynomials}
1966 @category{Rational expressions}
1967 @closecatbox
1968 @end deffn
1969
1970 @c -----------------------------------------------------------------------------
1971 @anchor{ratdenom}
1972 @deffn {Function} ratdenom (@var{expr})
1973
1974 Returns the denominator of @var{expr},
1975 after coercing @var{expr} to a canonical rational expression (CRE).
1976 The return value is a CRE.
1977
1978 @c ACTUALLY THE CONVERSION IS CARRIED OUT BY ratf BUT THAT'S WHAT $rat CALLS
1979 @var{expr} is coerced to a CRE by @code{rat}
1980 if it is not already a CRE.
1981 This conversion may change the form of @var{expr} by putting all terms
1982 over a common denominator.
1983
1984 @code{denom} is similar, but returns an ordinary expression instead of a CRE.
1985 Also, @code{denom} does not attempt to place all terms over a common
1986 denominator, and thus some expressions which are considered ratios by
1987 @code{ratdenom} are not considered ratios by @code{denom}.
1988
1989 @c NEEDS AN EXAMPLE HERE
1990 @opencatbox
1991 @category{Rational expressions}
1992 @closecatbox
1993 @end deffn
1994
1995 @c -----------------------------------------------------------------------------
1996 @defvr {Option variable} ratdenomdivide
1997 Default value: @code{true}
1998
1999 When @code{ratdenomdivide} is @code{true},
2000 @code{ratexpand} expands a ratio in which the numerator is a sum
2001 into a sum of ratios,
2002 all having a common denominator.
2003 Otherwise, @code{ratexpand} collapses a sum of ratios into a single ratio,
2004 the numerator of which is the sum of the numerators of each ratio.
2005
2006 Examples:
2007
2008 @c ===beg===
2009 @c expr: (x^2 + x + 1)/(y^2 + 7);
2010 @c ratdenomdivide: true$
2011 @c ratexpand (expr);
2012 @c ratdenomdivide: false$
2013 @c ratexpand (expr);
2014 @c expr2: a^2/(b^2 + 3) + b/(b^2 + 3);
2015 @c ratexpand (expr2);
2016 @c ===end===
2017 @example
2018 (%i1) expr: (x^2 + x + 1)/(y^2 + 7);
2019                             2
2020                            x  + x + 1
2021 (%o1)                      ----------
2022                               2
2023                              y  + 7
2024 (%i2) ratdenomdivide: true$
2025 (%i3) ratexpand (expr);
2026                        2
2027                       x        x        1
2028 (%o3)               ------ + ------ + ------
2029                      2        2        2
2030                     y  + 7   y  + 7   y  + 7
2031 (%i4) ratdenomdivide: false$
2032 (%i5) ratexpand (expr);
2033 @group
2034                             2
2035                            x  + x + 1
2036 (%o5)                      ----------
2037                               2
2038                              y  + 7
2039 @end group
2040 (%i6) expr2: a^2/(b^2 + 3) + b/(b^2 + 3);
2041                                      2
2042                            b        a
2043 (%o6)                    ------ + ------
2044                           2        2
2045                          b  + 3   b  + 3
2046 (%i7) ratexpand (expr2);
2047                                   2
2048                              b + a
2049 (%o7)                        ------
2050                               2
2051                              b  + 3
2052 @end example
2053
2054 @opencatbox
2055 @category{Simplification flags and variables}
2056 @category{Rational expressions}
2057 @closecatbox
2058 @end defvr
2059
2060 @c -----------------------------------------------------------------------------
2061 @anchor{ratdiff}
2062 @deffn {Function} ratdiff (@var{expr}, @var{x})
2063
2064 Differentiates the rational expression @var{expr} with respect to @var{x}.
2065 @var{expr} must be a ratio of polynomials or a polynomial in @var{x}.
2066 The argument @var{x} may be a variable or a subexpression of @var{expr}.
2067 @c NOT CLEAR (FROM READING CODE) HOW x OTHER THAN A VARIABLE IS HANDLED --
2068 @c LOOKS LIKE (a+b), 10*(a+b), (a+b)^2 ARE ALL TREATED LIKE (a+b);
2069 @c HOW TO DESCRIBE THAT ??
2070
2071 The result is equivalent to @code{diff}, although perhaps in a different form.
2072 @code{ratdiff} may be faster than @code{diff}, for rational expressions.
2073
2074 @code{ratdiff} returns a canonical rational expression (CRE) if @code{expr} is
2075 a CRE.  Otherwise, @code{ratdiff} returns a general expression.
2076
2077 @code{ratdiff} considers only the dependence of @var{expr} on @var{x},
2078 and ignores any dependencies established by @code{depends}.
2079
2080 @c WHAT THIS IS ABOUT -- ratdiff (rat (factor (expr)), x) AND ratdiff (factor (rat (expr)), x) BOTH SUCCEED
2081 @c COMMENTING THIS OUT UNTIL SOMEONE CAN ESTABLISH SOME CRE'S FOR WHICH ratdiff FAILS
2082 @c However, @code{ratdiff} should not be used on factored CRE forms;
2083 @c use @code{diff} instead for such expressions.
2084
2085 Example:
2086
2087 @c ===beg===
2088 @c expr: (4*x^3 + 10*x - 11)/(x^5 + 5);
2089 @c ratdiff (expr, x);
2090 @c expr: f(x)^3 - f(x)^2 + 7;
2091 @c ratdiff (expr, f(x));
2092 @c expr: (a + b)^3 + (a + b)^2;
2093 @c ratdiff (expr, a + b);
2094 @c ===end===
2095 @example
2096 (%i1) expr: (4*x^3 + 10*x - 11)/(x^5 + 5);
2097 @group
2098                            3
2099                         4 x  + 10 x - 11
2100 (%o1)                   ----------------
2101                               5
2102                              x  + 5
2103 @end group
2104 (%i2) ratdiff (expr, x);
2105                     7       5       4       2
2106                  8 x  + 40 x  - 55 x  - 60 x  - 50
2107 (%o2)          - ---------------------------------
2108                           10       5
2109                          x   + 10 x  + 25
2110 (%i3) expr: f(x)^3 - f(x)^2 + 7;
2111                          3       2
2112 (%o3)                   f (x) - f (x) + 7
2113 (%i4) ratdiff (expr, f(x));
2114                            2
2115 (%o4)                   3 f (x) - 2 f(x)
2116 (%i5) expr: (a + b)^3 + (a + b)^2;
2117                               3          2
2118 (%o5)                  (b + a)  + (b + a)
2119 (%i6) ratdiff (expr, a + b);
2120                     2                    2
2121 (%o6)            3 b  + (6 a + 2) b + 3 a  + 2 a
2122 @end example
2123
2124 @opencatbox
2125 @category{Rational expressions}
2126 @closecatbox
2127 @end deffn
2128
2129 @c -----------------------------------------------------------------------------
2130 @anchor{ratdisrep}
2131 @deffn {Function} ratdisrep (@var{expr})
2132
2133 Returns its argument as a general expression.
2134 If @var{expr} is a general expression, it is returned unchanged.
2135
2136 Typically @code{ratdisrep} is called to convert a canonical rational expression
2137 (CRE) into a general expression.
2138 @c NOT REALLY FOND OF YOU-CAN-DO-THIS-YOU-CAN-DO-THAT STATEMENTS
2139 This is sometimes convenient if one wishes to stop the "contagion", or
2140 use rational functions in non-rational contexts.
2141
2142 See also @mrefdot{totaldisrep}
2143
2144 @opencatbox
2145 @category{Rational expressions}
2146 @closecatbox
2147 @end deffn
2148
2149 @c -----------------------------------------------------------------------------
2150 @anchor{ratexpand}
2151 @deffn  {Function} ratexpand (@var{expr})
2152 @deffnx {Option variable} ratexpand
2153
2154 Expands @var{expr} by multiplying out products of sums and
2155 exponentiated sums, combining fractions over a common denominator,
2156 cancelling the greatest common divisor of the numerator and
2157 denominator, then splitting the numerator (if a sum) into its
2158 respective terms divided by the denominator.
2159
2160 The return value of @code{ratexpand} is a general expression,
2161 even if @var{expr} is a canonical rational expression (CRE).
2162
2163 @c WHAT DOES THE FOLLOWING MEAN EXACTLY ??
2164 The switch @code{ratexpand} if @code{true} will cause CRE
2165 expressions to be fully expanded when they are converted back to
2166 general form or displayed, while if it is @code{false} then they will be put
2167 into a recursive form.
2168 See also @mrefdot{ratsimp}
2169
2170 When @code{ratdenomdivide} is @code{true},
2171 @code{ratexpand} expands a ratio in which the numerator is a sum
2172 into a sum of ratios,
2173 all having a common denominator.
2174 Otherwise, @code{ratexpand} collapses a sum of ratios into a single ratio,
2175 the numerator of which is the sum of the numerators of each ratio.
2176
2177 When @code{keepfloat} is @code{true}, prevents floating
2178 point numbers from being rationalized when expressions which contain
2179 them are converted to canonical rational expression (CRE) form.
2180
2181 Examples:
2182
2183 @c ===beg===
2184 @c ratexpand ((2*x - 3*y)^3);
2185 @c expr: (x - 1)/(x + 1)^2 + 1/(x - 1);
2186 @c expand (expr);
2187 @c ratexpand (expr);
2188 @c ===end===
2189 @example
2190 (%i1) ratexpand ((2*x - 3*y)^3);
2191                      3         2       2        3
2192 (%o1)          - 27 y  + 54 x y  - 36 x  y + 8 x
2193 (%i2) expr: (x - 1)/(x + 1)^2 + 1/(x - 1);
2194                          x - 1       1
2195 (%o2)                   -------- + -----
2196                                2   x - 1
2197                         (x + 1)
2198 (%i3) expand (expr);
2199 @group
2200                     x              1           1
2201 (%o3)          ------------ - ------------ + -----
2202                 2              2             x - 1
2203                x  + 2 x + 1   x  + 2 x + 1
2204 @end group
2205 (%i4) ratexpand (expr);
2206                         2
2207                      2 x                 2
2208 (%o4)           --------------- + ---------------
2209                  3    2            3    2
2210                 x  + x  - x - 1   x  + x  - x - 1
2211 @end example
2212
2213 @opencatbox
2214 @category{Rational expressions}
2215 @closecatbox
2216 @end deffn
2217
2218 @c -----------------------------------------------------------------------------
2219 @anchor{ratfac}
2220 @defvr {Option variable} ratfac
2221 Default value: @code{false}
2222
2223 When @code{ratfac} is @code{true}, canonical rational expressions (CRE) are
2224 manipulated in a partially factored form.
2225
2226 During rational operations the expression is maintained as fully factored as
2227 possible without calling @code{factor}.
2228 This should always save space and may save time in some computations.
2229 The numerator and denominator are made relatively prime, for example
2230 @code{factor ((x^2 - 1)^4/(x + 1)^2)} yields @code{(x - 1)^4 (x + 1)^2},
2231 but the factors within each part may not be relatively prime.
2232
2233 In the @code{ctensor} (Component Tensor Manipulation) package,
2234 Ricci, Einstein, Riemann, and Weyl tensors and the scalar curvature
2235 are factored automatically when @code{ratfac} is @code{true}.
2236 @i{@code{ratfac} should only be
2237 set for cases where the tensorial components are known to consist of
2238 few terms.}
2239
2240 The @code{ratfac} and @code{ratweight} schemes are incompatible and may not
2241 both be used at the same time.
2242
2243 @c NEED EXAMPLES HERE
2244 @opencatbox
2245 @category{Rational expressions}
2246 @closecatbox
2247 @end defvr
2248
2249 @c -----------------------------------------------------------------------------
2250 @anchor{ratnumer}
2251 @deffn {Function} ratnumer (@var{expr})
2252
2253 Returns the numerator of @var{expr},
2254 after coercing @var{expr} to a canonical rational expression (CRE).
2255 The return value is a CRE.
2256
2257 @c ACTUALLY THE CONVERSION IS CARRIED OUT BY ratf BUT THAT'S WHAT $rat CALLS
2258 @var{expr} is coerced to a CRE by @code{rat}
2259 if it is not already a CRE.
2260 This conversion may change the form of @var{expr} by putting all terms
2261 over a common denominator.
2262
2263 @code{num} is similar, but returns an ordinary expression instead of a CRE.
2264 Also, @code{num} does not attempt to place all terms over a common denominator,
2265 and thus some expressions which are considered ratios by @code{ratnumer}
2266 are not considered ratios by @code{num}.
2267
2268 @c NEEDS AN EXAMPLE HERE
2269 @opencatbox
2270 @category{Rational expressions}
2271 @closecatbox
2272 @end deffn
2273
2274 @c -----------------------------------------------------------------------------
2275 @anchor{ratp}
2276 @deffn {Function} ratp (@var{expr})
2277
2278 Returns @code{true} if @var{expr} is a canonical rational expression (CRE) or
2279 extended CRE, otherwise @code{false}.
2280
2281 CRE are created by @code{rat} and related functions.
2282 Extended CRE are created by @code{taylor} and related functions.
2283
2284 @opencatbox
2285 @category{Predicate functions}
2286 @category{Rational expressions}
2287 @closecatbox
2288 @end deffn
2289
2290 @c -----------------------------------------------------------------------------
2291 @defvr {Option variable} ratprint
2292 Default value: @code{true}
2293
2294 When @code{ratprint} is @code{true},
2295 a message informing the user of the conversion of floating point numbers
2296 to rational numbers is displayed.
2297
2298 @opencatbox
2299 @category{Rational expressions}
2300 @category{Numerical evaluation}
2301 @category{Console interaction}
2302 @closecatbox
2303 @end defvr
2304
2305 @c -----------------------------------------------------------------------------
2306 @anchor{ratsimp}
2307 @deffn  {Function} ratsimp (@var{expr})
2308 @deffnx {Function} ratsimp (@var{expr}, @var{x_1}, @dots{}, @var{x_n})
2309
2310 Simplifies the expression @var{expr} and all of its subexpressions, including
2311 the arguments to non-rational functions.  The result is returned as the quotient
2312 of two polynomials in a recursive form, that is, the coefficients of the main
2313 variable are polynomials in the other variables.  Variables may include
2314 non-rational functions (e.g., @code{sin (x^2 + 1)}) and the arguments to any
2315 such functions are also rationally simplified.
2316
2317 @code{ratsimp (@var{expr}, @var{x_1}, ..., @var{x_n})}
2318 enables rational simplification with the
2319 specification of variable ordering as in @code{ratvars}.
2320
2321 When @code{ratsimpexpons} is @code{true},
2322 @code{ratsimp} is applied to the exponents of expressions during simplification.
2323
2324 See also @mrefdot{ratexpand}
2325 Note that @code{ratsimp} is affected by some of the
2326 flags which affect @code{ratexpand}.
2327
2328 Examples:
2329
2330 @c ===beg===
2331 @c sin (x/(x^2 + x)) = exp ((log(x) + 1)^2 - log(x)^2);
2332 @c ratsimp (%);
2333 @c ((x - 1)^(3/2) - (x + 1)*sqrt(x - 1))/sqrt((x - 1)*(x + 1));
2334 @c ratsimp (%);
2335 @c x^(a + 1/a), ratsimpexpons: true;
2336 @c ===end===
2337 @example
2338 (%i1) sin (x/(x^2 + x)) = exp ((log(x) + 1)^2 - log(x)^2);
2339 @group
2340                                          2      2
2341                    x         (log(x) + 1)  - log (x)
2342 (%o1)        sin(------) = %e
2343                   2
2344                  x  + x
2345 @end group
2346 (%i2) ratsimp (%);
2347                              1          2
2348 (%o2)                  sin(-----) = %e x
2349                            x + 1
2350 (%i3) ((x - 1)^(3/2) - (x + 1)*sqrt(x - 1))/sqrt((x - 1)*(x + 1));
2351 @group
2352                        3/2
2353                 (x - 1)    - sqrt(x - 1) (x + 1)
2354 (%o3)           --------------------------------
2355                      sqrt((x - 1) (x + 1))
2356 @end group
2357 (%i4) ratsimp (%);
2358                            2 sqrt(x - 1)
2359 (%o4)                    - -------------
2360                                  2
2361                            sqrt(x  - 1)
2362 (%i5) x^(a + 1/a), ratsimpexpons: true;
2363                                2
2364                               a  + 1
2365                               ------
2366                                 a
2367 (%o5)                        x
2368 @end example
2369
2370 @opencatbox
2371 @category{Simplification functions}
2372 @category{Rational expressions}
2373 @closecatbox
2374 @end deffn
2375
2376 @c -----------------------------------------------------------------------------
2377 @defvr {Option variable} ratsimpexpons
2378 Default value: @code{false}
2379
2380 When @code{ratsimpexpons} is @code{true},
2381 @code{ratsimp} is applied to the exponents of expressions during simplification.
2382
2383 @c NEED AN EXAMPLE HERE -- RECYCLE THE ratsimpexpons EXAMPLE FROM ratsimp ABOVE
2384 @opencatbox
2385 @category{Simplification flags and variables}
2386 @category{Rational expressions}
2387 @closecatbox
2388 @end defvr
2389
2390 @c -----------------------------------------------------------------------------
2391 @anchor{radsubstflag}
2392 @defvr {Option variable} radsubstflag
2393 Default value: @code{false}
2394
2395 @code{radsubstflag}, if @code{true}, permits @code{ratsubst} to make
2396 substitutions such as @code{u} for @code{sqrt (x)} in @code{x}.
2397
2398 @opencatbox
2399 @category{Simplification flags and variables}
2400 @closecatbox
2401 @end defvr
2402
2403 @c -----------------------------------------------------------------------------
2404 @anchor{ratsubst}
2405 @deffn {Function} ratsubst (@var{a}, @var{b}, @var{c})
2406
2407 Substitutes @var{a} for @var{b} in @var{c} and returns the resulting expression.
2408 @c "ETC" SUGGESTS THE READER KNOWS WHAT ELSE GOES THERE -- NOT LIKELY THE CASE
2409 @var{b} may be a sum, product, power, etc.
2410
2411 @c WHAT, EXACTLY, DOES ratsubst KNOW ??
2412 @code{ratsubst} knows something of the meaning of expressions
2413 whereas @code{subst} does a purely syntactic substitution.
2414 Thus @code{subst (a, x + y, x + y + z)} returns @code{x + y + z}
2415 whereas @code{ratsubst} returns @code{z + a}.
2416
2417 When @code{radsubstflag} is @code{true},
2418 @code{ratsubst} makes substitutions for radicals in expressions
2419 which don't explicitly contain them.
2420
2421 @code{ratsubst} ignores the value @code{true} of the option variables
2422 @code{keepfloat}, @code{float}, and @code{numer}.
2423
2424 Examples:
2425
2426 @c EXAMPLES BELOW ADAPTED FROM examples (ratsubst)
2427 @c WITH SOME ADDITIONAL STUFF
2428
2429 @c ===beg===
2430 @c ratsubst (a, x*y^2, x^4*y^3 + x^4*y^8);
2431 @c cos(x)^4 + cos(x)^3 + cos(x)^2 + cos(x) + 1;
2432 @c ratsubst (1 - sin(x)^2, cos(x)^2, %);
2433 @c ratsubst (1 - cos(x)^2, sin(x)^2, sin(x)^4);
2434 @c radsubstflag: false$
2435 @c ratsubst (u, sqrt(x), x);
2436 @c radsubstflag: true$
2437 @c ratsubst (u, sqrt(x), x);
2438 @c ===end===
2439 @example
2440 @group
2441 (%i1) ratsubst (a, x*y^2, x^4*y^3 + x^4*y^8);
2442                               3      4
2443 (%o1)                      a x  y + a
2444 @end group
2445 @group
2446 (%i2) cos(x)^4 + cos(x)^3 + cos(x)^2 + cos(x) + 1;
2447                4         3         2
2448 (%o2)       cos (x) + cos (x) + cos (x) + cos(x) + 1
2449 @end group
2450 @group
2451 (%i3) ratsubst (1 - sin(x)^2, cos(x)^2, %);
2452             4           2                     2
2453 (%o3)    sin (x) - 3 sin (x) + cos(x) (2 - sin (x)) + 3
2454 @end group
2455 @group
2456 (%i4) ratsubst (1 - cos(x)^2, sin(x)^2, sin(x)^4);
2457                         4           2
2458 (%o4)                cos (x) - 2 cos (x) + 1
2459 @end group
2460 (%i5) radsubstflag: false$
2461 @group
2462 (%i6) ratsubst (u, sqrt(x), x);
2463 (%o6)                           x
2464 @end group
2465 (%i7) radsubstflag: true$
2466 @group
2467 (%i8) ratsubst (u, sqrt(x), x);
2468                                 2
2469 (%o8)                          u
2470 @end group
2471 @end example
2472
2473 @opencatbox
2474 @category{Rational expressions}
2475 @closecatbox
2476 @end deffn
2477
2478 @c -----------------------------------------------------------------------------
2479 @anchor{ratvars}
2480 @deffn  {Function} ratvars (@var{x_1}, @dots{}, @var{x_n})
2481 @deffnx {Function} ratvars ()
2482 @deffnx {System variable} ratvars
2483
2484 Declares main variables @var{x_1}, @dots{}, @var{x_n} for rational expressions.
2485 @var{x_n}, if present in a rational expression, is considered the main variable.
2486 Otherwise, @var{x_[n-1]} is considered the main variable if present, and so on
2487 through the preceding variables to @var{x_1}, which is considered the main
2488 variable only if none of the succeeding variables are present.
2489
2490 If a variable in a rational expression is not present in the @code{ratvars}
2491 list, it is given a lower priority than @var{x_1}.
2492
2493 The arguments to @code{ratvars} can be either variables or non-rational
2494 functions such as @code{sin(x)}.
2495
2496 The variable @code{ratvars} is a list of the arguments of
2497 the function @code{ratvars} when it was called most recently.
2498 Each call to the function @code{ratvars} resets the list.
2499 @code{ratvars ()} clears the list.
2500
2501 @c NEED EXAMPLES HERE
2502 @opencatbox
2503 @category{Rational expressions}
2504 @closecatbox
2505 @end deffn
2506
2507 @c -----------------------------------------------------------------------------
2508 @defvr {Option variable} ratvarswitch
2509 Default value: @code{true}
2510
2511 Maxima keeps an internal list in the Lisp variable @code{VARLIST} of the main
2512 variables for rational expressions.  If @code{ratvarswitch} is @code{true},
2513 every evaluation starts with a fresh list @code{VARLIST}.  This is the default
2514 behavior.  Otherwise, the main variables from previous evaluations are not
2515 removed from the internal list @code{VARLIST}.
2516
2517 The main variables, which are declared with the function @code{ratvars} are
2518 not affected by the option variable @code{ratvarswitch}.
2519
2520 Examples:
2521
2522 If @code{ratvarswitch} is @code{true}, every evaluation starts with a fresh
2523 list @code{VARLIST}.
2524
2525 @c ===beg===
2526 @c ratvarswitch:true$
2527 @c rat(2*x+y^2);
2528 @c :lisp varlist
2529 @c rat(2*a+b^2);
2530 @c :lisp varlist
2531 @c ===end===
2532 @example
2533 (%i1) ratvarswitch:true$
2534
2535 (%i2) rat(2*x+y^2);
2536                              2
2537 (%o2)/R/                    y  + 2 x
2538 (%i3) :lisp varlist
2539 ($X $Y)
2540
2541 (%i3) rat(2*a+b^2);
2542                              2
2543 (%o3)/R/                    b  + 2 a
2544
2545 (%i4) :lisp varlist
2546 ($A $B)
2547 @end example
2548
2549 If @code{ratvarswitch} is @code{false}, the main variables from the last
2550 evaluation are still present.
2551
2552 @c ===beg===
2553 @c ratvarswitch:false$
2554 @c rat(2*x+y^2);
2555 @c :lisp varlist
2556 @c rat(2*a+b^2);
2557 @c :lisp varlist
2558 @c ===end===
2559 @example
2560 (%i4) ratvarswitch:false$
2561
2562 (%i5) rat(2*x+y^2);
2563                              2
2564 (%o5)/R/                    y  + 2 x
2565 (%i6) :lisp varlist
2566 ($X $Y)
2567
2568 (%i6) rat(2*a+b^2);
2569                              2
2570 (%o6)/R/                    b  + 2 a
2571
2572 (%i7) :lisp varlist
2573 ($A $B $X $Y)
2574 @end example
2575
2576 @opencatbox
2577 @category{Rational expressions}
2578 @category{Global flags}
2579 @closecatbox
2580 @end defvr
2581
2582 @c -----------------------------------------------------------------------------
2583 @deffn  {Function} ratweight @
2584 @fname{ratweight} (@var{x_1}, @var{w_1}, @dots{}, @var{x_n}, @var{w_n}) @
2585 @fname{ratweight} ()
2586
2587 Assigns a weight @var{w_i} to the variable @var{x_i}.
2588 This causes a term to be replaced by 0 if its weight exceeds the
2589 value of the variable @code{ratwtlvl} (default yields no truncation).
2590 The weight of a term is the sum of the products of the
2591 weight of a variable in the term times its power.
2592 For example, the weight of @code{3 x_1^2 x_2} is @code{2 w_1 + w_2}.
2593 Truncation according to @code{ratwtlvl} is carried out only when multiplying
2594 or exponentiating canonical rational expressions (CRE).
2595
2596 @code{ratweight ()} returns the cumulative list of weight assignments.
2597
2598 Note: The @code{ratfac} and @code{ratweight} schemes are incompatible and may
2599 not both be used at the same time.
2600
2601 Examples:
2602
2603 @c ===beg===
2604 @c ratweight (a, 1, b, 1);
2605 @c expr1: rat(a + b + 1)$
2606 @c expr1^2;
2607 @c ratwtlvl: 1$
2608 @c expr1^2;
2609 @c ===end===
2610 @example
2611 (%i1) ratweight (a, 1, b, 1);
2612 (%o1)                     [a, 1, b, 1]
2613 (%i2) expr1: rat(a + b + 1)$
2614 (%i3) expr1^2;
2615                   2                  2
2616 (%o3)/R/         b  + (2 a + 2) b + a  + 2 a + 1
2617 (%i4) ratwtlvl: 1$
2618 (%i5) expr1^2;
2619 (%o5)/R/                  2 b + 2 a + 1
2620 @end example
2621
2622 @opencatbox
2623 @category{Rational expressions}
2624 @closecatbox
2625 @end deffn
2626
2627 @c -----------------------------------------------------------------------------
2628 @defvr {System variable} ratweights
2629 Default value: @code{[]}
2630
2631 @code{ratweights} is the list of weights assigned by @code{ratweight}.
2632 The list is cumulative:
2633 each call to @code{ratweight} places additional items in the list.
2634
2635 @c DO WE REALLY NEED TO MENTION THIS ??
2636 @code{kill (ratweights)} and @code{save (ratweights)} both work as expected.
2637
2638 @opencatbox
2639 @category{Rational expressions}
2640 @closecatbox
2641 @end defvr
2642
2643 @c -----------------------------------------------------------------------------
2644 @need 1000
2645 @defvr {Option variable} ratwtlvl
2646 Default value: @code{false}
2647
2648 @code{ratwtlvl} is used in combination with the @code{ratweight}
2649 function to control the truncation of canonical rational expressions (CRE).
2650 For the default value of @code{false}, no truncation occurs.
2651
2652 @opencatbox
2653 @category{Rational expressions}
2654 @closecatbox
2655 @end defvr
2656
2657 @c -----------------------------------------------------------------------------
2658 @deffn  {Function} remainder @
2659 @fname{remainder} (@var{p_1}, @var{p_2}) @
2660 @fname{remainder} (@var{p_1}, @var{p_2}, @var{x_1}, @dots{}, @var{x_n})
2661
2662 Returns the remainder of the polynomial @var{p_1} divided by the polynomial
2663 @var{p_2}.  The arguments @var{x_1}, @dots{}, @var{x_n} are interpreted as in
2664 @code{ratvars}.
2665
2666 @code{remainder} returns the second element
2667 of the two-element list returned by @code{divide}.
2668
2669 @c NEED SOME EXAMPLES HERE
2670 @opencatbox
2671 @category{Polynomials}
2672 @closecatbox
2673 @end deffn
2674
2675 @c -----------------------------------------------------------------------------
2676 @anchor{resultant}
2677 @deffn {Function} resultant (@var{p_1}, @var{p_2}, @var{x})
2678
2679 The function @code{resultant} computes the resultant of the two polynomials
2680 @var{p_1} and @var{p_2}, eliminating the variable @var{x}.  The resultant is a
2681 determinant of the coefficients of @var{x} in @var{p_1} and @var{p_2}, which
2682 equals zero if and only if @var{p_1} and @var{p_2} have a non-constant factor
2683 in common.
2684
2685 If @var{p_1} or @var{p_2} can be factored, it may be desirable to call
2686 @mref{factor} before calling @code{resultant}.
2687
2688 The option variable @code{resultant} controls which algorithm will be used to
2689 compute the resultant.  See the option variable
2690 @mxrefdot{option_resultant, resultant}
2691
2692 The function @mref{bezout} takes the same arguments as @code{resultant} and
2693 returns a matrix.  The determinant of the return value is the desired resultant.
2694
2695 Examples:
2696
2697 @c ===beg===
2698 @c resultant(2*x^2+3*x+1, 2*x^2+x+1, x);
2699 @c resultant(x+1, x+1, x);
2700 @c resultant((x+1)*x, (x+1), x);
2701 @c resultant(a*x^2+b*x+1, c*x + 2, x);
2702 @c bezout(a*x^2+b*x+1, c*x+2, x);
2703 @c determinant(%);
2704 @c ===end===
2705 @example
2706 (%i1) resultant(2*x^2+3*x+1, 2*x^2+x+1, x);
2707 (%o1)                           8
2708 (%i2) resultant(x+1, x+1, x);
2709 (%o2)                           0
2710 (%i3) resultant((x+1)*x, (x+1), x);
2711 (%o3)                           0
2712 (%i4) resultant(a*x^2+b*x+1, c*x + 2, x);
2713                          2
2714 (%o4)                   c  - 2 b c + 4 a
2715
2716 (%i5) bezout(a*x^2+b*x+1, c*x+2, x);
2717 @group
2718                         [ 2 a  2 b - c ]
2719 (%o5)                   [              ]
2720                         [  c      2    ]
2721 @end group
2722 (%i6) determinant(%);
2723 (%o6)                   4 a - (2 b - c) c
2724 @end example
2725 @opencatbox
2726 @category{Polynomials}
2727 @closecatbox
2728 @end deffn
2729
2730 @c -----------------------------------------------------------------------------
2731 @anchor{option_resultant}
2732 @defvr {Option variable} resultant
2733 Default value: @code{subres}
2734
2735 The option variable @code{resultant} controls which algorithm will be used to
2736 compute the resultant with the function @mrefdot{resultant}  The possible
2737 values are:
2738
2739 @table @code
2740 @item subres
2741 for the subresultant polynomial remainder sequence (PRS) algorithm,
2742 @item mod
2743 (not enabled) for the modular resultant algorithm, and
2744 @item red
2745 for the reduced polynomial remainder sequence (PRS) algorithm.
2746 @end table
2747
2748 On most problems the default value @code{subres} should be best.
2749 @c On some large degree univariate or bivariate problems @code{mod}
2750 @c may be better.
2751
2752 @opencatbox
2753 @category{Polynomials}
2754 @closecatbox
2755 @end defvr
2756
2757 @anchor{savefactors}
2758 @c -----------------------------------------------------------------------------
2759 @defvr {Option variable} savefactors
2760 Default value: @code{false}
2761
2762 @c "certain functions" -- WHICH ONES ??
2763 When @code{savefactors} is @code{true}, causes the factors of an
2764 expression which is a product of factors to be saved by certain
2765 functions in order to speed up later factorizations of expressions
2766 containing some of the same factors.
2767
2768 @opencatbox
2769 @category{Polynomials}
2770 @closecatbox
2771 @end defvr
2772
2773 @c -----------------------------------------------------------------------------
2774 @anchor{showratvars}
2775 @deffn {Function} showratvars (@var{expr})
2776
2777 Returns a list of the canonical rational expression (CRE) variables in
2778 expression @code{expr}.
2779
2780 See also @mrefdot{ratvars}
2781
2782 @opencatbox
2783 @category{Rational expressions}
2784 @category{Display functions}
2785 @closecatbox
2786 @end deffn
2787
2788 @c I CAN'T TELL WHAT THIS IS SUPPOSED TO BE ABOUT
2789
2790 @c -----------------------------------------------------------------------------
2791 @anchor{sqfr}
2792 @deffn {Function} sqfr (@var{expr})
2793
2794 is similar to @mref{factor} except that the polynomial factors are
2795 "square-free."  That is, they have factors only of degree one.
2796 This algorithm, which is also used by the first stage of @mrefcomma{factor} utilizes
2797 the fact that a polynomial has in common with its n'th derivative all
2798 its factors of degree greater than n.  Thus by taking greatest common divisors
2799 with the polynomial of
2800 the derivatives with respect to each variable in the polynomial, all
2801 factors of degree greater than 1 can be found.
2802
2803 Example:
2804
2805 @c ===beg===
2806 @c sqfr (4*x^4 + 4*x^3 - 3*x^2 - 4*x - 1);
2807 @c ===end===
2808 @example
2809 (%i1) sqfr (4*x^4 + 4*x^3 - 3*x^2 - 4*x - 1);
2810                                 2   2
2811 (%o1)                  (2 x + 1)  (x  - 1)
2812 @end example
2813
2814 @opencatbox
2815 @category{Polynomials}
2816 @closecatbox
2817 @end deffn
2818
2819 @c THIS ITEM STILL NEEDS WORK
2820
2821 @c -----------------------------------------------------------------------------
2822 @deffn  {Function} tellrat @
2823 @fname{tellrat} (@var{p_1}, @dots{}, @var{p_n}) @
2824 @fname{tellrat} ()
2825
2826 Adds to the ring of algebraic integers known to Maxima
2827 the elements which are the solutions of the polynomials @var{p_1}, @dots{},
2828 @var{p_n}.  Each argument @var{p_i} is a polynomial with integer coefficients.
2829
2830 @code{tellrat (@var{x})} effectively means substitute 0 for @var{x} in rational
2831 functions.
2832
2833 @code{tellrat ()} returns a list of the current substitutions.
2834
2835 @code{algebraic} must be set to @code{true} in order for the simplification of
2836 algebraic integers to take effect.
2837
2838 Maxima initially knows about the imaginary unit @code{%i}
2839 and all roots of integers.
2840
2841 There is a command @code{untellrat} which takes kernels and
2842 removes @code{tellrat} properties.
2843
2844 When @code{tellrat}'ing a multivariate
2845 polynomial, e.g., @code{tellrat (x^2 - y^2)}, there would be an ambiguity as to
2846 whether to substitute @code{@var{y}^2} for @code{@var{x}^2}
2847 or vice versa.
2848 Maxima picks a particular ordering, but if the user wants to specify which, e.g.
2849 @code{tellrat (y^2 = x^2)} provides a syntax which says replace
2850 @code{@var{y}^2} by @code{@var{x}^2}.
2851
2852 @c CAN'T TELL WHAT THIS IS ABOUT -- tellrat(w^3-1)$ algebraic:true$ rat(1/(w^2-w));
2853 @c DOES NOT YIELD AN ERROR, SO WHAT IS THE POINT ABOUT ratalgdenom ??
2854 @c When you @code{tellrat} reducible polynomials, you want to be careful not to
2855 @c attempt to rationalize a denominator with a zero divisor.  E.g.
2856 @c tellrat(w^3-1)$ algebraic:true$ rat(1/(w^2-w)); will give "quotient by
2857 @c zero".  This error can be avoided by setting @code{ratalgdenom} to @code{false}.
2858
2859 Examples:
2860
2861 @c ===beg===
2862 @c 10*(%i + 1)/(%i + 3^(1/3));
2863 @c ev (ratdisrep (rat(%)), algebraic);
2864 @c tellrat (1 + a + a^2);
2865 @c 1/(a*sqrt(2) - 1) + a/(sqrt(3) + sqrt(2));
2866 @c ev (ratdisrep (rat(%)), algebraic);
2867 @c tellrat (y^2 = x^2);
2868 @c ===end===
2869 @example
2870 (%i1) 10*(%i + 1)/(%i + 3^(1/3));
2871                            10 (%i + 1)
2872 (%o1)                      -----------
2873                                   1/3
2874                             %i + 3
2875 (%i2) ev (ratdisrep (rat(%)), algebraic);
2876              2/3      1/3              2/3      1/3
2877 (%o2)    (4 3    - 2 3    - 4) %i + 2 3    + 4 3    - 2
2878 (%i3) tellrat (1 + a + a^2);
2879                             2
2880 (%o3)                     [a  + a + 1]
2881 (%i4) 1/(a*sqrt(2) - 1) + a/(sqrt(3) + sqrt(2));
2882                       1                 a
2883 (%o4)           ------------- + -----------------
2884                 sqrt(2) a - 1   sqrt(3) + sqrt(2)
2885 (%i5) ev (ratdisrep (rat(%)), algebraic);
2886          (7 sqrt(3) - 10 sqrt(2) + 2) a - 2 sqrt(2) - 1
2887 (%o5)    ----------------------------------------------
2888                                7
2889 (%i6) tellrat (y^2 = x^2);
2890                         2    2   2
2891 (%o6)                 [y  - x , a  + a + 1]
2892 @end example
2893
2894 @opencatbox
2895 @category{Polynomials}
2896 @category{Rational expressions}
2897 @closecatbox
2898 @end deffn
2899
2900 @c -----------------------------------------------------------------------------
2901 @anchor{totaldisrep}
2902 @deffn {Function} totaldisrep (@var{expr})
2903
2904 Converts every subexpression of @var{expr} from canonical rational expressions
2905 (CRE) to general form and returns the result.
2906 If @var{expr} is itself in CRE form then @code{totaldisrep} is identical to
2907 @code{ratdisrep}.
2908
2909 @code{totaldisrep} may be useful for
2910 ratdisrepping expressions such as equations, lists, matrices, etc., which
2911 have some subexpressions in CRE form.
2912
2913 @c NEED EXAMPLES HERE
2914 @opencatbox
2915 @category{Rational expressions}
2916 @closecatbox
2917 @end deffn
2918
2919 @c -----------------------------------------------------------------------------
2920 @anchor{untelltat}
2921 @deffn {Function} untellrat (@var{x_1}, @dots{}, @var{x_n})
2922
2923 Removes @code{tellrat} properties from @var{x_1}, @dots{}, @var{x_n}.
2924
2925 @c NEED EXAMPLES HERE
2926 @opencatbox
2927 @category{Polynomials}
2928 @category{Rational expressions}
2929 @closecatbox
2930 @end deffn
2931