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