doc/info/MathFunctions.texi.m4

   1 @c -*- mode: texinfo -*-
   2 @menu
   3 * Functions for Numbers::
   4 * Functions for Complex Numbers::
   5 * Combinatorial Functions::
   6 * Root Exponential and Logarithmic Functions::
   7 * Trigonometric Functions::
   8 * Random Numbers::
   9 @end menu
  10
  11 @c -----------------------------------------------------------------------------
  12 @node Functions for Numbers, Functions for Complex Numbers, , Elementary Functions
  13 @section Functions for Numbers
  14 @c -----------------------------------------------------------------------------
  15
  16 @c -----------------------------------------------------------------------------
  17 @anchor{abs}
  18 @deffn {Function} abs (@var{z})
  19
  20 The @code{abs} function represents the mathematical absolute value function and
  21 works for both numerical and symbolic values. If the argument, @var{z}, is a
  22 real or complex number, @code{abs} returns the absolute value of @var{z}. If
  23 possible, symbolic expressions using the absolute value function are
  24 also simplified.
  25
  26 Maxima can differentiate, integrate and calculate limits for expressions
  27 containing @code{abs}. The @code{abs_integrate} package further extends
  28 Maxima's ability to calculate integrals involving the abs function. See
  29 (%i12) in the examples below.
  30
  31 When applied to a list or matrix, @code{abs} automatically distributes over
  32 the terms. Similarly, it distributes over both sides of an
  33 equation. To alter this behaviour, see the variable @mrefdot{distribute_over}
  34
  35 See also @mrefdot{cabs}
  36
  37 Examples:
  38
  39 Calculation of @code{abs} for real and complex numbers, including numerical
  40 constants and various infinities. The first example shows how @code{abs}
  41 distributes over the elements of a list.
  42
  43 @c ===beg===
  44 @c abs([-4, 0, 1, 1+%i]);
  45 @c abs((1+%i)*(1-%i));
  46 @c abs(%e+%i);
  47 @c abs([inf, infinity, minf]);
  48 @c ===end===
  49 @example
  50 @group
  51 (%i1) abs([-4, 0, 1, 1+%i]);
  52 (%o1)                  [4, 0, 1, sqrt(2)]
  53 @end group
  54 @group
  55 (%i2) abs((1+%i)*(1-%i));
  56 (%o2)                           2
  57 @end group
  58 @group
  59 (%i3) abs(%e+%i);
  60                                  2
  61 (%o3)                     sqrt(%e  + 1)
  62 @end group
  63 @group
  64 (%i4) abs([inf, infinity, minf]);
  65 (%o4)                    [inf, inf, inf]
  66 @end group
  67 @end example
  68
  69 Simplification of expressions containing @code{abs}:
  70
  71 @c ===beg===
  72 @c abs(x^2);
  73 @c abs(x^3);
  74 @c abs(abs(x));
  75 @c abs(conjugate(x));
  76 @c ===end===
  77 @example
  78 @group
  79 (%i1) abs(x^2);
  80                                 2
  81 (%o1)                          x
  82 @end group
  83 @group
  84 (%i2) abs(x^3);
  85                              2
  86 (%o2)                       x  abs(x)
  87 @end group
  88 @group
  89 (%i3) abs(abs(x));
  90 (%o3)                        abs(x)
  91 @end group
  92 @group
  93 (%i4) abs(conjugate(x));
  94 (%o4)                        abs(x)
  95 @end group
  96 @end example
  97
  98 Integrating and differentiating with the @code{abs} function. Note that more
  99 integrals involving the @code{abs} function can be performed, if the
 100 @code{abs_integrate} package is loaded. The last example shows the Laplace
 101 transform of @code{abs}: see @mrefdot{laplace}
 102
 103 @c ===beg===
 104 @c diff(x*abs(x),x),expand;
 105 @c integrate(abs(x),x);
 106 @c integrate(x*abs(x),x);
 107 @c load("abs_integrate")$
 108 @c integrate(x*abs(x),x);
 109 @c integrate(abs(x),x,-2,%pi);
 110 @c laplace(abs(x),x,s);
 111 @c ===end===
 112 @example
 113 @group
 114 (%i1) diff(x*abs(x),x),expand;
 115 (%o1)                       2 abs(x)
 116 @end group
 117 @group
 118 (%i2) integrate(abs(x),x);
 119                             x abs(x)
 120 (%o2)                       --------
 121                                2
 122 @end group
 123 @group
 124 (%i3) integrate(x*abs(x),x);
 125                           /
 126                           |
 127 (%o3)                     | x abs(x) dx
 128                           |
 129                           /
 130 @end group
 131 (%i4) load("abs_integrate")$
 132 @group
 133 (%i5) integrate(x*abs(x),x);
 134                            3
 135                           x  signum(x)
 136 (%o5)                     ------------
 137                                3
 138 @end group
 139 @group
 140 (%i6) integrate(abs(x),x,-2,%pi);
 141                                2
 142                             %pi
 143 (%o6)                       ---- + 2
 144                              2
 145 @end group
 146 @group
 147 (%i7) laplace(abs(x),x,s);
 148                                1
 149 (%o7)                          --
 150                                 2
 151                                s
 152 @end group
 153 @end example
 154
 155 @opencatbox{Categories:}
 156 @category{Mathematical functions}
 157 @closecatbox
 158 @end deffn
 159
 160 @c -----------------------------------------------------------------------------
 161 @anchor{ceiling}
 162 @deffn {Function} ceiling (@var{x})
 163
 164 When @var{x} is a real number, return the least integer that
 165 is greater than or equal to @var{x}.
 166
 167 If @var{x} is a constant expression (@code{10 * %pi}, for example),
 168 @code{ceiling} evaluates @var{x} using big floating point numbers, and
 169 applies @code{ceiling} to the resulting big float.  Because @code{ceiling} uses
 170 floating point evaluation, it's possible, although unlikely, that @code{ceiling}
 171 could return an erroneous value for constant inputs.  To guard against errors,
 172 the floating point evaluation is done using three values for @mrefdot{fpprec}
 173
 174 For non-constant inputs, @code{ceiling} tries to return a simplified value.
 175 Here are examples of the simplifications that @code{ceiling} knows about:
 176
 177 @c ===beg===
 178 @c ceiling (ceiling (x));
 179 @c ceiling (floor (x));
 180 @c declare (n, integer)$
 181 @c [ceiling (n), ceiling (abs (n)), ceiling (max (n, 6))];
 182 @c assume (x > 0, x < 1)$
 183 @c ceiling (x);
 184 @c tex (ceiling (a));
 185 @c ===end===
 186 @example
 187 @group
 188 (%i1) ceiling (ceiling (x));
 189 (%o1)                      ceiling(x)
 190 @end group
 191 @group
 192 (%i2) ceiling (floor (x));
 193 (%o2)                       floor(x)
 194 @end group
 195 (%i3) declare (n, integer)$
 196 @group
 197 (%i4) [ceiling (n), ceiling (abs (n)), ceiling (max (n, 6))];
 198 (%o4)                [n, abs(n), max(6, n)]
 199 @end group
 200 (%i5) assume (x > 0, x < 1)$
 201 @group
 202 (%i6) ceiling (x);
 203 (%o6)                           1
 204 @end group
 205 @group
 206 (%i7) tex (ceiling (a));
 207 $$\left \lceil a \right \rceil$$
 208 (%o7)                         false
 209 @end group
 210 @end example
 211
 212 The @code{ceiling} function distributes over lists, matrices and equations.
 213 See @mrefdot{distribute_over}
 214
 215 Finally, for all inputs that are manifestly complex, @code{ceiling} returns
 216 a noun form.
 217
 218 If the range of a function is a subset of the integers, it can be declared to
 219 be @code{integervalued}.  Both the @code{ceiling} and @mref{floor} functions
 220 can use this information; for example:
 221
 222 @c ===beg===
 223 @c declare (f, integervalued)$
 224 @c floor (f(x));
 225 @c ceiling (f(x) - 1);
 226 @c ===end===
 227 @example
 228 (%i1) declare (f, integervalued)$
 229 @group
 230 (%i2) floor (f(x));
 231 (%o2)                         f(x)
 232 @end group
 233 @group
 234 (%i3) ceiling (f(x) - 1);
 235 (%o3)                       f(x) - 1
 236 @end group
 237 @end example
 238
 239 Example use:
 240
 241 @c ===beg===
 242 @c unitfrac(r) := block([uf : [], q],
 243 @c     if not(ratnump(r)) then
 244 @c        error("unitfrac: argument must be a rational number"),
 245 @c     while r # 0 do (
 246 @c         uf : cons(q : 1/ceiling(1/r), uf),
 247 @c         r : r - q),
 248 @c     reverse(uf));
 249 @c unitfrac (9/10);
 250 @c apply ("+", %);
 251 @c unitfrac (-9/10);
 252 @c apply ("+", %);
 253 @c unitfrac (36/37);
 254 @c apply ("+", %);
 255 @c ===end===
 256 @example
 257 @group
 258 (%i1) unitfrac(r) := block([uf : [], q],
 259     if not(ratnump(r)) then
 260        error("unitfrac: argument must be a rational number"),
 261     while r # 0 do (
 262         uf : cons(q : 1/ceiling(1/r), uf),
 263         r : r - q),
 264     reverse(uf));
 265 (%o1) unitfrac(r) := block([uf : [], q],
 266 if not ratnump(r) then error("unitfrac: argument must be a rational number"
 267                                      1
 268 ), while r # 0 do (uf : cons(q : ----------, uf), r : r - q),
 269                                          1
 270                                  ceiling(-)
 271                                          r
 272 reverse(uf))
 273 @end group
 274 @group
 275 (%i2) unitfrac (9/10);
 276                             1  1  1
 277 (%o2)                      [-, -, --]
 278                             2  3  15
 279 @end group
 280 @group
 281 (%i3) apply ("+", %);
 282                                9
 283 (%o3)                          --
 284                                10
 285 @end group
 286 @group
 287 (%i4) unitfrac (-9/10);
 288                                   1
 289 (%o4)                       [- 1, --]
 290                                   10
 291 @end group
 292 @group
 293 (%i5) apply ("+", %);
 294                                 9
 295 (%o5)                         - --
 296                                 10
 297 @end group
 298 @group
 299 (%i6) unitfrac (36/37);
 300                         1  1  1  1    1
 301 (%o6)                  [-, -, -, --, ----]
 302                         2  3  8  69  6808
 303 @end group
 304 @group
 305 (%i7) apply ("+", %);
 306                                36
 307 (%o7)                          --
 308                                37
 309 @end group
 310 @end example
 311
 312 @opencatbox{Categories:}
 313 @category{Mathematical functions}
 314 @closecatbox
 315 @end deffn
 316
 317 @c -----------------------------------------------------------------------------
 318 @anchor{entier}
 319 @deffn {Function} entier (@var{x})
 320
 321 Returns the largest integer less than or equal to @var{x} where @var{x} is
 322 numeric.  @mref{fix} (as in @code{fixnum}) is a synonym for this, so
 323 @code{fix(@var{x})} is precisely the same.
 324
 325 @opencatbox{Categories:}
 326 @category{Mathematical functions}
 327 @closecatbox
 328 @end deffn
 329
 330 @c -----------------------------------------------------------------------------
 331 @anchor{floor}
 332 @deffn {Function} floor (@var{x})
 333
 334 When @var{x} is a real number, return the largest integer that is less than or
 335 equal to @var{x}.
 336
 337 If @var{x} is a constant expression (@code{10 * %pi}, for example), @code{floor}
 338 evaluates @var{x} using big floating point numbers, and applies @code{floor} to
 339 the resulting big float. Because @code{floor} uses floating point evaluation,
 340 it's possible, although unlikely, that @code{floor} could return an erroneous
 341 value for constant inputs.  To guard against errors, the floating point
 342 evaluation is done using three values for @mrefdot{fpprec}
 343
 344 For non-constant inputs, @code{floor} tries to return a simplified value.  Here
 345 are examples of the simplifications that @code{floor} knows about:
 346
 347 @c ===beg===
 348 @c floor (ceiling (x));
 349 @c floor (floor (x));
 350 @c declare (n, integer)$
 351 @c [floor (n), floor (abs (n)), floor (min (n, 6))];
 352 @c assume (x > 0, x < 1)$
 353 @c floor (x);
 354 @c tex (floor (a));
 355 @c ===end===
 356 @example
 357 @group
 358 (%i1) floor (ceiling (x));
 359 (%o1)                      ceiling(x)
 360 @end group
 361 @group
 362 (%i2) floor (floor (x));
 363 (%o2)                       floor(x)
 364 @end group
 365 (%i3) declare (n, integer)$
 366 @group
 367 (%i4) [floor (n), floor (abs (n)), floor (min (n, 6))];
 368 (%o4)                [n, abs(n), min(6, n)]
 369 @end group
 370 (%i5) assume (x > 0, x < 1)$
 371 @group
 372 (%i6) floor (x);
 373 (%o6)                           0
 374 @end group
 375 @group
 376 (%i7) tex (floor (a));
 377 $$\left \lfloor a \right \rfloor$$
 378 (%o7)                         false
 379 @end group
 380 @end example
 381
 382 The @code{floor} function distributes over lists, matrices and equations.
 383 See @mrefdot{distribute_over}
 384
 385 Finally, for all inputs that are manifestly complex, @code{floor} returns
 386 a noun form.
 387
 388 If the range of a function is a subset of the integers, it can be declared to
 389 be @code{integervalued}.  Both the @mref{ceiling} and @code{floor} functions
 390 can use this information; for example:
 391
 392 @c ===beg===
 393 @c declare (f, integervalued)$
 394 @c floor (f(x));
 395 @c ceiling (f(x) - 1);
 396 @c ===end===
 397 @example
 398 (%i1) declare (f, integervalued)$
 399 @group
 400 (%i2) floor (f(x));
 401 (%o2)                         f(x)
 402 @end group
 403 @group
 404 (%i3) ceiling (f(x) - 1);
 405 (%o3)                       f(x) - 1
 406 @end group
 407 @end example
 408
 409 @opencatbox{Categories:}
 410 @category{Mathematical functions}
 411 @closecatbox
 412 @end deffn
 413
 414 @c -----------------------------------------------------------------------------
 415 @anchor{fix}
 416 @deffn {Function} fix (@var{x})
 417
 418 A synonym for @code{entier (@var{x})}.
 419
 420 @opencatbox{Categories:}
 421 @category{Mathematical functions}
 422 @closecatbox
 423 @end deffn
 424
 425 @c -----------------------------------------------------------------------------
 426 @anchor{hstep}
 427 @deffn {Function} hstep (@var{x})
 428 The Heaviside unit step function, equal to 0 if @var{x} is negative,
 429 equal to 1 if @var{x} is positive and equal to 1/2 if @var{x} is equal
 430 to zero.
 431
 432 If you want a unit step function that takes on the value of 0 at @var{x}
 433 equal to zero, use @mrefdot{unit_step}
 434
 435 @opencatbox{Categories:}
 436 @category{Laplace transform}
 437 @category{Mathematical functions}
 438 @closecatbox
 439
 440 @end deffn
 441
 442 @c -----------------------------------------------------------------------------
 443 @anchor{lmax}
 444 @deffn {Function} lmax (@var{L})
 445
 446 When @var{L} is a list or a set, return @code{apply ('max, args (@var{L}))}.
 447 When @var{L} is not a list or a set, signal an error.
 448 See also @mref{lmin} and @mrefdot{max}
 449
 450 @opencatbox{Categories:}
 451 @category{Mathematical functions}
 452 @category{Lists}
 453 @category{Sets}
 454 @closecatbox
 455 @end deffn
 456
 457 @c -----------------------------------------------------------------------------
 458 @anchor{lmin}
 459 @deffn {Function} lmin (@var{L})
 460
 461 When @var{L} is a list or a set, return @code{apply ('min, args (@var{L}))}.
 462 When @var{L} is not a list or a set, signal an error.
 463 See also @mref{lmax} and @mrefdot{min}
 464
 465 @opencatbox{Categories:}
 466 @category{Mathematical functions}
 467 @category{Lists}
 468 @category{Sets}
 469 @closecatbox
 470 @end deffn
 471
 472 @c -----------------------------------------------------------------------------
 473 @anchor{max}
 474 @deffn {Function} max (@var{x_1}, @dots{}, @var{x_n})
 475
 476 Return a simplified value for the numerical maximum of the expressions @var{x_1}
 477 through @var{x_n}. For an empty argument list, @code{max} yields @code{minf}.
 478
 479 The option variable @code{maxmin_effort} controls which simplification methods are
 480 applied. Using the default value of @emph{twelve} for @code{maxmin_effort},
 481 @code{max} uses @emph{all} available simplification methods. To to inhibit all
 482 simplifications, set @code{maxmin_effort} to zero.
 483
 484 When @code{maxmin_effort} is one or more, for an explicit list of real numbers,
 485 @code{max} returns a number.
 486
 487 Unless @code{max} needs to simplify a lengthy list of expressions, we suggest using
 488 the default value of @code{maxmin_effort}. Setting @code{maxmin_effort} to zero
 489 (no simplifications), will cause problems for some Maxima functions; accordingly,
 490 generally @code{maxmin_effort} should be nonzero.
 491
 492 See also @mref{min}, @mrefdot{lmax}, and @mrefdot{lmin}.
 493
 494 @b{Examples:}
 495
 496 In the first example, setting @code{maxmin_effort} to zero suppresses simplifications.
 497 @example
 498 (%i1) block([maxmin_effort : 0], max(1,2,x,x, max(a,b)));
 499 (%o1) max(1,2,max(a,b),x,x)
 500
 501 (%i2) block([maxmin_effort : 1], max(1,2,x,x, max(a,b)));
 502 (%o2) max(2,a,b,x)
 503 @end example
 504
 505 When @code{maxmin_effort} is two or more, @code{max} compares pairs of members:
 506 @example
 507 (%i1) block([maxmin_effort : 1], max(x,x+1,x+3));
 508 (%o1) max(x,x+1,x+3)
 509
 510 (%i2) block([maxmin_effort : 2], max(x,x+1,x+3));
 511 (%o2) x+3
 512 @end example
 513
 514 Finally, when @code{maxmin_effort} is three or more, @code{max} compares triples
 515 members and excludes those that are in between; for example
 516 @example
 517 (%i1) block([maxmin_effort : 4], max(x, 2*x, 3*x, 4*x));
 518 (%o1) max(x,4*x)
 519 @end example
 520
 521 @opencatbox{Categories:}
 522 @category{Mathematical functions}
 523 @closecatbox
 524 @end deffn
 525
 526 @anchor{min}
 527 @deffn {Function} min (@var{x_1}, @dots{}, @var{x_n})
 528
 529 Return a simplified value for the numerical minimum of the expressions @var{x_1}
 530 through @var{x_n}. For an empty argument list, @code{minf} yields @code{inf}.
 531
 532 The option variable @code{maxmin_effort} controls which simplification methods are
 533 applied. Using the default value of @emph{twelve} for @code{maxmin_effort},
 534 @code{max} uses @emph{all} available simplification methods. To to inhibit all
 535 simplifications, set @code{maxmin_effort} to zero.
 536
 537 When @code{maxmin_effort} is one or more, for an explicit list of real numbers,
 538 @code{min} returns a number.
 539
 540 Unless @code{min} needs to simplify a lengthy list of expressions, we suggest using
 541 the default value of @code{maxmin_effort}. Setting @code{maxmin_effort} to zero
 542 (no simplifications), will cause problems for some Maxima functions; accordingly,
 543 generally @code{maxmin_effort} should be nonzero.
 544
 545 See also @mref{max}, @mrefdot{lmax}, and @mrefdot{lmin}.
 546
 547 @b{Examples:}
 548
 549 In the first example, setting @code{maxmin_effort} to zero suppresses simplifications.
 550 @example
 551 (%i1) block([maxmin_effort : 0], min(1,2,x,x, min(a,b)));
 552 (%o1) min(1,2,a,b,x,x)
 553
 554 (%i2) block([maxmin_effort : 1], min(1,2,x,x, min(a,b)));
 555 (%o2) min(1,a,b,x)
 556 @end example
 557
 558 When @code{maxmin_effort} is two or more, @code{min} compares pairs of members:
 559 @example
 560 (%i1) block([maxmin_effort : 1], min(x,x+1,x+3));
 561 (%o1) min(x,x+1,x+3)
 562
 563 (%i2) block([maxmin_effort : 2], min(x,x+1,x+3));
 564 (%o2) x
 565 @end example
 566
 567 Finally, when @code{maxmin_effort} is three or more, @code{min} compares triples
 568 members and excludes those that are in between; for example
 569 @example
 570 (%i1) block([maxmin_effort : 4], min(x, 2*x, 3*x, 4*x));
 571 (%o1) max(x,4*x)
 572 @end example
 573
 574 @opencatbox{Categories:}
 575 @category{Mathematical functions}
 576 @closecatbox
 577 @end deffn
 578
 579 @c -----------------------------------------------------------------------------
 580 @anchor{round}
 581 @deffn {Function} round (@var{x})
 582
 583 When @var{x} is a real number, returns the closest integer to @var{x}.
 584 Multiples of 1/2 are rounded to the nearest even integer.  Evaluation of
 585 @var{x} is similar to @mref{floor} and @mrefdot{ceiling}
 586
 587 The @code{round} function distributes over lists, matrices and equations.
 588 See @mrefdot{distribute_over}
 589
 590 @opencatbox{Categories:}
 591 @category{Mathematical functions}
 592 @closecatbox
 593 @end deffn
 594
 595 @c -----------------------------------------------------------------------------
 596 @anchor{signum}
 597 @deffn {Function} signum (@var{x})
 598
 599 For either real or complex numbers @var{x}, the signum function returns
 600 0 if @var{x} is zero; for a nonzero numeric input @var{x}, the signum function
 601 returns @code{x/abs(x)}.
 602
 603 For non-numeric inputs, Maxima attempts to determine the sign of the input.
 604 When the sign is negative, zero, or positive, @code{signum} returns -1,0, 1,
 605 respectively.  For all other values for the sign, @code{signum} a simplified but
 606 equivalent form.  The simplifications include reflection (@code{signum(-x)}
 607 gives @code{-signum(x)}) and multiplicative identity (@code{signum(x*y)} gives
 608 @code{signum(x) * signum(y)}).
 609
 610 The @code{signum} function distributes over a list, a matrix, or an
 611 equation.  See @mref{sign} and @mrefdot{distribute_over}
 612
 613 @opencatbox{Categories:}
 614 @category{Mathematical functions}
 615 @closecatbox
 616 @end deffn
 617
 618 @c -----------------------------------------------------------------------------
 619 @anchor{truncate}
 620 @deffn {Function} truncate (@var{x})
 621
 622 When @var{x} is a real number, return the closest integer to @var{x} not
 623 greater in absolute value than @var{x}.  Evaluation of @var{x} is similar
 624 to @mref{floor} and @mrefdot{ceiling}
 625
 626 The @code{truncate} function distributes over lists, matrices and equations.
 627 See @mrefdot{distribute_over}
 628
 629 @opencatbox{Categories:}
 630 @category{Mathematical functions}
 631 @closecatbox
 632 @end deffn
 633
 634 @c -----------------------------------------------------------------------------
 635 @node Functions for Complex Numbers, Combinatorial Functions, Functions for Numbers, Elementary Functions
 636 @section Functions for Complex Numbers
 637 @c -----------------------------------------------------------------------------
 638
 639 @c -----------------------------------------------------------------------------
 640 @anchor{cabs}
 641 @deffn {Function} cabs (@var{expr})
 642
 643 Calculates the absolute value of an expression representing a complex
 644 number.  Unlike the function @mrefcomma{abs} the @code{cabs} function always
 645 decomposes its argument into a real and an imaginary part.  If @code{x} and
 646 @code{y} represent real variables or expressions, the @code{cabs} function
 647 calculates the absolute value of @code{x + %i*y} as
 648
 649 @c ===beg===
 650 @c cabs (1);
 651 @c cabs (1 + %i);
 652 @c cabs (exp (%i));
 653 @c cabs (exp (%pi * %i));
 654 @c cabs (exp (3/2 * %pi * %i));
 655 @c cabs (17 * exp (2 * %i));
 656 @c ===end===
 657 @example
 658 @group
 659 (%i1) cabs (1);
 660 (%o1)                           1
 661 @end group
 662 @group
 663 (%i2) cabs (1 + %i);
 664 (%o2)                        sqrt(2)
 665 @end group
 666 @group
 667 (%i3) cabs (exp (%i));
 668 (%o3)                           1
 669 @end group
 670 @group
 671 (%i4) cabs (exp (%pi * %i));
 672 (%o4)                           1
 673 @end group
 674 @group
 675 (%i5) cabs (exp (3/2 * %pi * %i));
 676 (%o5)                           1
 677 @end group
 678 @group
 679 (%i6) cabs (17 * exp (2 * %i));
 680 (%o6)                          17
 681 @end group
 682 @end example
 683
 684 If @code{cabs} returns a noun form this most commonly is caused by
 685 some properties of the variables involved not being known:
 686
 687 @c ===beg===
 688 @c cabs (a+%i*b);
 689 @c declare(a,real,b,real);
 690 @c cabs (a+%i*b);
 691 @c assume(a>0,b>0);
 692 @c cabs (a+%i*b);
 693 @c ===end===
 694 @example
 695 @group
 696 (%i1) cabs (a+%i*b);
 697                                 2    2
 698 (%o1)                     sqrt(b  + a )
 699 @end group
 700 @group
 701 (%i2) declare(a,real,b,real);
 702 (%o2)                         done
 703 @end group
 704 @group
 705 (%i3) cabs (a+%i*b);
 706                                 2    2
 707 (%o3)                     sqrt(b  + a )
 708 @end group
 709 @group
 710 (%i4) assume(a>0,b>0);
 711 (%o4)                    [a > 0, b > 0]
 712 @end group
 713 @group
 714 (%i5) cabs (a+%i*b);
 715                                 2    2
 716 (%o5)                     sqrt(b  + a )
 717 @end group
 718 @end example
 719
 720 The @code{cabs} function can use known properties like symmetry properties of
 721 complex functions to help it calculate the absolute value of an expression.  If
 722 such identities exist, they can be advertised to @code{cabs} using function
 723 properties.  The symmetries that @code{cabs} understands are: mirror symmetry,
 724 conjugate function and complex characteristic.
 725
 726 @code{cabs} is a verb function and is not suitable for symbolic
 727 calculations.  For such calculations (including integration,
 728 differentiation and taking limits of expressions containing absolute
 729 values), use @mrefdot{abs}
 730
 731 The result of @code{cabs} can include the absolute value function,
 732 @mrefcomma{abs} and the arc tangent, @mrefdot{atan2}
 733
 734 When applied to a list or matrix, @code{cabs} automatically distributes over
 735 the terms.  Similarly, it distributes over both sides of an equation.
 736
 737 For further ways to compute with complex numbers, see the functions
 738 @mrefcomma{rectform} @mrefcomma{realpart} @mrefcomma{imagpart}@w{}
 739 @mrefcomma{carg} @mref{conjugate} and @mrefdot{polarform}
 740
 741 Examples:
 742
 743 Examples with @mref{sqrt} and @mrefdot{sin}
 744
 745 @c ===beg===
 746 @c cabs(sqrt(1+%i*x));
 747 @c cabs(sin(x+%i*y));
 748 @c ===end===
 749 @example
 750 @group
 751 (%i1) cabs(sqrt(1+%i*x));
 752                              2     1/4
 753 (%o1)                      (x  + 1)
 754 @end group
 755 @group
 756 (%i2) cabs(sin(x+%i*y));
 757                     2        2         2        2
 758 (%o2)       sqrt(cos (x) sinh (y) + sin (x) cosh (y))
 759 @end group
 760 @end example
 761
 762 The error function, @mrefcomma{erf} has mirror symmetry, which is used here in
 763 the calculation of the absolute value with a complex argument:
 764
 765 @c ===beg===
 766 @c cabs(erf(x+%i*y));
 767 @c ===end===
 768 @example
 769 @group
 770 (%i1) cabs(erf(x+%i*y));
 771                                           2
 772            (erf(%i y + x) - erf(%i y - x))
 773 (%o1) sqrt(--------------------------------
 774                           4
 775                                                                2
 776                               (- erf(%i y + x) - erf(%i y - x))
 777                             - ----------------------------------)
 778                                               4
 779 @end group
 780 @end example
 781
 782 Maxima knows complex identities for the Bessel functions, which allow
 783 it to compute the absolute value for complex arguments.  Here is an
 784 example for @mrefdot{bessel_j}
 785
 786 @c ===beg===
 787 @c cabs(bessel_j(1,%i));
 788 @c ===end===
 789 @example
 790 @group
 791 (%i1) cabs(bessel_j(1,%i));
 792 (%o1)                    bessel_i(1, 1)
 793 @end group
 794 @end example
 795
 796 @opencatbox{Categories:}
 797 @category{Complex variables}
 798 @closecatbox
 799 @end deffn
 800
 801 @c -----------------------------------------------------------------------------
 802 @anchor{carg}
 803 @deffn {Function} carg (@var{z})
 804
 805 Returns the complex argument of @var{z}.  The complex argument is an angle
 806 @code{theta} in @code{(-%pi, %pi]} such that @code{r exp (theta %i) = @var{z}}
 807 where @code{r} is the magnitude of @var{z}.
 808
 809 @code{carg} is a computational function, not a simplifying function.
 810 @c PROBABLY NEED TO EXPLAIN IMPLICATIONS OF ABOVE STATEMENT
 811
 812 See also @mref{abs} (complex magnitude), @mrefcomma{polarform}@w{}
 813 @mrefcomma{rectform} @mrefcomma{realpart} and @mrefdot{imagpart}
 814
 815 Examples:
 816
 817 @c ===beg===
 818 @c carg (1);
 819 @c carg (1 + %i);
 820 @c carg (exp (%i));
 821 @c carg (exp (%pi * %i));
 822 @c carg (exp (3/2 * %pi * %i));
 823 @c carg (17 * exp (2 * %i));
 824 @c ===end===
 825 @example
 826 @group
 827 (%i1) carg (1);
 828 (%o1)                           0
 829 @end group
 830 @group
 831 (%i2) carg (1 + %i);
 832                                %pi
 833 (%o2)                          ---
 834                                 4
 835 @end group
 836 @group
 837 (%i3) carg (exp (%i));
 838                                sin(1)
 839 (%o3)                     atan(------)
 840                                cos(1)
 841 @end group
 842 @group
 843 (%i4) carg (exp (%pi * %i));
 844 (%o4)                          %pi
 845 @end group
 846 @group
 847 (%i5) carg (exp (3/2 * %pi * %i));
 848                                 %pi
 849 (%o5)                         - ---
 850                                  2
 851 @end group
 852 @group
 853 (%i6) carg (17 * exp (2 * %i));
 854                             sin(2)
 855 (%o6)                  atan(------) + %pi
 856                             cos(2)
 857 @end group
 858 @end example
 859
 860 If @code{carg} returns a noun form this most commonly is caused by
 861 some properties of the variables involved not being known:
 862
 863 @c ===beg===
 864 @c carg (a+%i*b);
 865 @c declare(a,real,b,real);
 866 @c carg (a+%i*b);
 867 @c assume(a>0,b>0);
 868 @c carg (a+%i*b);
 869 @c ===end===
 870 @example
 871 @group
 872 (%i1) carg (a+%i*b);
 873 (%o1)                      atan2(b, a)
 874 @end group
 875 @group
 876 (%i2) declare(a,real,b,real);
 877 (%o2)                         done
 878 @end group
 879 @group
 880 (%i3) carg (a+%i*b);
 881 (%o3)                      atan2(b, a)
 882 @end group
 883 @group
 884 (%i4) assume(a>0,b>0);
 885 (%o4)                    [a > 0, b > 0]
 886 @end group
 887 @group
 888 (%i5) carg (a+%i*b);
 889                                   b
 890 (%o5)                        atan(-)
 891                                   a
 892 @end group
 893 @end example
 894
 895 @opencatbox{Categories:}
 896 @category{Complex variables}
 897 @closecatbox
 898 @end deffn
 899
 900 @c -----------------------------------------------------------------------------
 901 @anchor{conjugate}
 902 @deffn {Function} conjugate (@var{x})
 903
 904 Returns the complex conjugate of @var{x}.
 905
 906 @c ===beg===
 907 @c declare ([aa, bb], real, cc, complex, ii, imaginary);
 908 @c conjugate (aa + bb*%i);
 909 @c conjugate (cc);
 910 @c conjugate (ii);
 911 @c conjugate (xx + yy);
 912 @c ===end===
 913 @example
 914 @group
 915 (%i1) declare ([aa, bb], real, cc, complex, ii, imaginary);
 916 (%o1)                         done
 917 @end group
 918 @group
 919 (%i2) conjugate (aa + bb*%i);
 920 (%o2)                      aa - %i bb
 921 @end group
 922 @group
 923 (%i3) conjugate (cc);
 924 (%o3)                     conjugate(cc)
 925 @end group
 926 @group
 927 (%i4) conjugate (ii);
 928 (%o4)                         - ii
 929 @end group
 930 @group
 931 (%i5) conjugate (xx + yy);
 932 (%o5)                        yy + xx
 933 @end group
 934 @end example
 935
 936 @opencatbox{Categories:}
 937 @category{Complex variables}
 938 @closecatbox
 939 @end deffn
 940
 941 @c -----------------------------------------------------------------------------
 942 @anchor{imagpart}
 943 @deffn {Function} imagpart (@var{expr})
 944
 945 Returns the imaginary part of the expression @var{expr}.
 946
 947 @code{imagpart} is a computational function, not a simplifying function.
 948 @c PROBABLY NEED TO EXPLAIN IMPLICATIONS OF ABOVE STATEMENT
 949 @c SEE ALSO SF BUG REPORT # 902290
 950
 951 See also @mrefcomma{abs} @mrefcomma{carg} @mrefcomma{polarform}@w{}
 952 @mrefcomma{rectform} and @mrefdot{realpart}
 953
 954 Example:
 955
 956 @c ===beg===
 957 @c imagpart (a+b*%i);
 958 @c imagpart (1+sqrt(2)*%i);
 959 @c imagpart (1);
 960 @c imagpart (sqrt(2)*%i);
 961 @c ===end===
 962 @example
 963 @group
 964 (%i1) imagpart (a+b*%i);
 965 (%o1)                           b
 966 @end group
 967 @group
 968 (%i2) imagpart (1+sqrt(2)*%i);
 969 (%o2)                        sqrt(2)
 970 @end group
 971 @group
 972 (%i3) imagpart (1);
 973 (%o3)                           0
 974 @end group
 975 @group
 976 (%i4) imagpart (sqrt(2)*%i);
 977 (%o4)                        sqrt(2)
 978 @end group
 979 @end example
 980
 981 @opencatbox{Categories:}
 982 @category{Complex variables}
 983 @closecatbox
 984 @end deffn
 985
 986 @c NEEDS EXAMPLES
 987
 988 @c -----------------------------------------------------------------------------
 989 @anchor{polarform}
 990 @deffn {Function} polarform (@var{expr})
 991
 992 Returns an expression @code{r %e^(%i theta)} equivalent to @var{expr},
 993 such that @code{r} and @code{theta} are purely real.
 994
 995 Example:
 996
 997 @c ===beg===
 998 @c polarform(a+b*%i);
 999 @c polarform(1+%i);
1000 @c polarform(1+2*%i);
1001 @c ===end===
1002 @example
1003 @group
1004 (%i1) polarform(a+b*%i);
1005                        2    2    %i atan2(b, a)
1006 (%o1)            sqrt(b  + a ) %e
1007 @end group
1008 @group
1009 (%i2) polarform(1+%i);
1010                                   %i %pi
1011                                   ------
1012                                     4
1013 (%o2)                   sqrt(2) %e
1014 @end group
1015 @group
1016 (%i3) polarform(1+2*%i);
1017                                 %i atan(2)
1018 (%o3)                 sqrt(5) %e
1019 @end group
1020 @end example
1021
1022 @opencatbox{Categories:}
1023 @category{Complex variables}
1024 @category{Exponential and logarithm functions}
1025 @closecatbox
1026 @end deffn
1027
1028 @c -----------------------------------------------------------------------------
1029 @anchor{realpart}
1030 @deffn {Function} realpart (@var{expr})
1031
1032 Returns the real part of @var{expr}.  @code{realpart} and @mref{imagpart} will
1033 work on expressions involving trigonometric and hyperbolic functions,
1034 as well as square root, logarithm, and exponentiation.
1035
1036 Example:
1037
1038 @c ===beg===
1039 @c realpart (a+b*%i);
1040 @c realpart (1+sqrt(2)*%i);
1041 @c realpart (sqrt(2)*%i);
1042 @c realpart (1);
1043 @c ===end===
1044 @example
1045 @group
1046 (%i1) realpart (a+b*%i);
1047 (%o1)                           a
1048 @end group
1049 @group
1050 (%i2) realpart (1+sqrt(2)*%i);
1051 (%o2)                           1
1052 @end group
1053 @group
1054 (%i3) realpart (sqrt(2)*%i);
1055 (%o3)                           0
1056 @end group
1057 @group
1058 (%i4) realpart (1);
1059 (%o4)                           1
1060 @end group
1061 @end example
1062
1063 @opencatbox{Categories:}
1064 @category{Complex variables}
1065 @closecatbox
1066 @end deffn
1067
1068 @c -----------------------------------------------------------------------------
1069 @anchor{rectform}
1070 @deffn {Function} rectform (@var{expr})
1071
1072 Returns an expression @code{a + b %i} equivalent to @var{expr},
1073 such that @var{a} and @var{b} are purely real.
1074
1075 Example:
1076
1077 @c ===beg===
1078 @c rectform(sqrt(2)*%e^(%i*%pi/4));
1079 @c rectform(sqrt(b^2+a^2)*%e^(%i*atan2(b, a)));
1080 @c rectform(sqrt(5)*%e^(%i*atan(2)));
1081 @c ===end===
1082 @example
1083 @group
1084 (%i1) rectform(sqrt(2)*%e^(%i*%pi/4));
1085 (%o1)                        %i + 1
1086 @end group
1087 @group
1088 (%i2) rectform(sqrt(b^2+a^2)*%e^(%i*atan2(b, a)));
1089 (%o2)                       %i b + a
1090 @end group
1091 @group
1092 (%i3) rectform(sqrt(5)*%e^(%i*atan(2)));
1093 (%o3)                       2 %i + 1
1094 @end group
1095 @end example
1096
1097 @opencatbox{Categories:}
1098 @category{Complex variables}
1099 @closecatbox
1100 @end deffn
1101
1102 @c -----------------------------------------------------------------------------
1103 @node Combinatorial Functions, Root Exponential and Logarithmic Functions, Functions for Complex Numbers, Elementary Functions
1104 @section Combinatorial Functions
1105 @c -----------------------------------------------------------------------------
1106
1107 @c -----------------------------------------------------------------------------
1108 @anchor{!!}
1109 @fnindex Double factorial
1110 @deffn {Operator} !!
1111
1112 The double factorial operator.
1113
1114 For an integer, float, or rational number @code{n}, @code{n!!} evaluates to the
1115 product @code{n (n-2) (n-4) (n-6) ... (n - 2 (k-1))} where @code{k} is equal to
1116 @code{entier (n/2)}, that is, the largest integer less than or equal to
1117 @code{n/2}.  Note that this definition does not coincide with other published
1118 definitions for arguments which are not integers.
1119 @c REPORTED TO BUG TRACKER AS BUG # 1093138 !!!
1120
1121 For an even (or odd) integer @code{n}, @code{n!!} evaluates to the product of
1122 all the consecutive even (or odd) integers from 2 (or 1) through @code{n}
1123 inclusive.
1124
1125 For an argument @code{n} which is not an integer, float, or rational, @code{n!!}
1126 yields a noun form @code{genfact (n, n/2, 2)}.
1127 @c n!! IS NEITHER SIMPLIFIED NOR EVALUATED IN THIS CASE
1128 @c -- MENTION THAT? OR TOO MUCH DETAIL ???
1129
1130 @opencatbox{Categories:}
1131 @category{Gamma and factorial functions}
1132 @category{Operators}
1133 @closecatbox
1134 @end deffn
1135
1136 @c -----------------------------------------------------------------------------
1137 @anchor{binomial}
1138 @deffn {Function} binomial (@var{x}, @var{y})
1139
1140 The binomial coefficient @code{@var{x}!/(@var{y}! (@var{x} - @var{y})!)}.
1141 If @var{x} and @var{y} are integers, then the numerical value of the binomial
1142 coefficient is computed.  If @var{y}, or @var{x - y}, is an integer, the
1143 binomial coefficient is expressed as a polynomial.
1144
1145 Examples:
1146
1147 @c ===beg===
1148 @c binomial (11, 7);
1149 @c 11! / 7! / (11 - 7)!;
1150 @c binomial (x, 7);
1151 @c binomial (x + 7, x);
1152 @c binomial (11, y);
1153 @c ===end===
1154 @example
1155 @group
1156 (%i1) binomial (11, 7);
1157 (%o1)                          330
1158 @end group
1159 @group
1160 (%i2) 11! / 7! / (11 - 7)!;
1161 (%o2)                          330
1162 @end group
1163 @group
1164 (%i3) binomial (x, 7);
1165         (x - 6) (x - 5) (x - 4) (x - 3) (x - 2) (x - 1) x
1166 (%o3)   -------------------------------------------------
1167                               5040
1168 @end group
1169 @group
1170 (%i4) binomial (x + 7, x);
1171       (x + 1) (x + 2) (x + 3) (x + 4) (x + 5) (x + 6) (x + 7)
1172 (%o4) -------------------------------------------------------
1173                                5040
1174 @end group
1175 @group
1176 (%i5) binomial (11, y);
1177 (%o5)                    binomial(11, y)
1178 @end group
1179 @end example
1180
1181 @opencatbox{Categories:}
1182 @category{Number theory}
1183 @closecatbox
1184 @end deffn
1185
1186 @c -----------------------------------------------------------------------------
1187 @anchor{factcomb}
1188 @deffn {Function} factcomb (@var{expr})
1189
1190 Tries to combine the coefficients of factorials in @var{expr}
1191 with the factorials themselves by converting, for example, @code{(n + 1)*n!}
1192 into @code{(n + 1)!}.
1193
1194 @mref{sumsplitfact} if set to @code{false} will cause @mref{minfactorial} to be
1195 applied after a @code{factcomb}.
1196
1197 Example:
1198
1199 @c ===beg===
1200 @c sumsplitfact;
1201 @c (n + 1)*(n + 1)*n!;
1202 @c factcomb (%);
1203 @c sumsplitfact: not sumsplitfact;
1204 @c (n + 1)*(n + 1)*n!;
1205 @c factcomb (%);
1206 @c ===end===
1207 @example
1208 @group
1209 (%i1) sumsplitfact;
1210 (%o1)                         true
1211 @end group
1212 @group
1213 (%i2) (n + 1)*(n + 1)*n!;
1214                                   2
1215 (%o2)                      (n + 1)  n!
1216 @end group
1217 @group
1218 (%i3) factcomb (%);
1219 (%o3)                  (n + 2)! - (n + 1)!
1220 @end group
1221 @group
1222 (%i4) sumsplitfact: not sumsplitfact;
1223 (%o4)                         false
1224 @end group
1225 @group
1226 (%i5) (n + 1)*(n + 1)*n!;
1227                                   2
1228 (%o5)                      (n + 1)  n!
1229 @end group
1230 @group
1231 (%i6) factcomb (%);
1232 (%o6)                 n (n + 1)! + (n + 1)!
1233 @end group
1234 @end example
1235
1236 @opencatbox{Categories:}
1237 @category{Gamma and factorial functions}
1238 @closecatbox
1239 @end deffn
1240
1241 @c -----------------------------------------------------------------------------
1242 @anchor{!}
1243 @anchor{factorial}
1244 @deffn  {Function} factorial
1245 @deffnx {Operator} !
1246
1247 Represents the factorial function.  Maxima treats @code{factorial (@var{x})}
1248 the same as @code{@var{x}!}.
1249
1250 For any complex number @code{x}, except for negative integers, @code{x!} is
1251 defined as @code{gamma(x+1)}.
1252
1253 For an integer @code{x}, @code{x!} simplifies to the product of the integers
1254 from 1 to @code{x} inclusive.  @code{0!} simplifies to 1.  For a real or complex
1255 number in float or bigfloat precision @code{x}, @code{x!} simplifies to the
1256 value of @code{gamma (x+1)}.  For @code{x} equal to @code{n/2} where @code{n} is
1257 an odd integer, @code{x!} simplifies to a rational factor times
1258 @code{sqrt (%pi)} (since @code{gamma (1/2)} is equal to @code{sqrt (%pi)}).
1259
1260 The option variables @mref{factlim} and @mref{gammalim} control the numerical
1261 evaluation of factorials for integer and rational arguments.  The functions
1262 @mref{minfactorial} and @mref{factcomb} simplifies expressions containing
1263 factorials.
1264
1265 The functions @mrefcomma{gamma} @mrefcomma{bffac} and @mref{cbffac} are
1266 varieties of the gamma function.  @code{bffac} and @code{cbffac} are called
1267 internally by @code{gamma} to evaluate the gamma function for real and complex
1268 numbers in bigfloat precision.
1269
1270 @mref{makegamma} substitutes @code{gamma} for factorials and related functions.
1271
1272 Maxima knows the derivative of the factorial function and the limits for
1273 specific values like negative integers.
1274
1275 The option variable @mref{factorial_expand} controls the simplification of
1276 expressions like @code{(n+x)!}, where @code{n} is an integer.
1277
1278 See also @mrefdot{binomial}
1279
1280 The factorial of an integer is simplified to an exact number unless the operand
1281 is greater than @code{factlim}.  The factorial for real and complex numbers is
1282 evaluated in float or bigfloat precision.
1283
1284 @c ===beg===
1285 @c factlim : 10;
1286 @c [0!, (7/2)!, 8!, 20!];
1287 @c [4,77!, (1.0+%i)!];
1288 @c [2.86b0!, (1.0b0+%i)!];
1289 @c ===end===
1290 @example
1291 @group
1292 (%i1) factlim : 10;
1293 (%o1)                          10
1294 @end group
1295 @group
1296 (%i2) [0!, (7/2)!, 8!, 20!];
1297                      105 sqrt(%pi)
1298 (%o2)            [1, -------------, 40320, 20!]
1299                           16
1300 @end group
1301 @group
1302 (%i3) [4,77!, (1.0+%i)!];
1303 (%o3) [4, 77!, 0.3430658398165453 %i + 0.6529654964201667]
1304 @end group
1305 @group
1306 (%i4) [2.86b0!, (1.0b0+%i)!];
1307 (%o4) [5.046635586910012b0, 3.430658398165454b-1 %i
1308                                           + 6.529654964201667b-1]
1309 @end group
1310 @end example
1311
1312 The factorial of a known constant, or general expression is not simplified.
1313 Even so it may be possible to simplify the factorial after evaluating the
1314 operand.
1315
1316 @c ===beg===
1317 @c [(%i + 1)!, %pi!, %e!, (cos(1) + sin(1))!];
1318 @c ev (%, numer, %enumer);
1319 @c ===end===
1320 @example
1321 @group
1322 (%i1) [(%i + 1)!, %pi!, %e!, (cos(1) + sin(1))!];
1323 (%o1)      [(%i + 1)!, %pi!, %e!, (sin(1) + cos(1))!]
1324 @end group
1325 @group
1326 (%i2) ev (%, numer, %enumer);
1327 (%o2) [0.3430658398165453 %i + 0.6529654964201667,
1328          7.188082728976031, 4.260820476357003, 1.227580202486819]
1329 @end group
1330 @end example
1331
1332 @c REMOVING THIS EXAMPLE. IT IS NOT SPECIFIC FOR THE FACTORIAL FUNCTION:
1333 @c The factorial of an unbound symbol is not simplified.
1334
1335 @c @c ===beg===
1336 @c @c kill (foo);
1337 @c @c foo!;
1338 @c @c ===end===
1339 @c @example
1340 @c (%i1) kill (foo);
1341 @c (%o1)                         done
1342 @c (%i2) foo!;
1343 @c (%o2)                         foo!
1344 @c @end example
1345
1346 Factorials are simplified, not evaluated.
1347 Thus @code{x!} may be replaced even in a quoted expression.
1348
1349 @c ===beg===
1350 @c '([0!, (7/2)!, 4.77!, 8!, 20!]);
1351 @c ===end===
1352 @example
1353 @group
1354 (%i1) '([0!, (7/2)!, 4.77!, 8!, 20!]);
1355           105 sqrt(%pi)
1356 (%o1) [1, -------------, 81.44668037931197, 40320,
1357                16
1358                                              2432902008176640000]
1359 @end group
1360 @end example
1361
1362 Maxima knows the derivative of the factorial function.
1363
1364 @c ===beg===
1365 @c diff(x!,x);
1366 @c ===end===
1367 @example
1368 @group
1369 (%i1) diff(x!,x);
1370 (%o1)                    x! psi (x + 1)
1371                                0
1372 @end group
1373 @end example
1374
1375 The option variable @code{factorial_expand} controls expansion and
1376 simplification of expressions with the factorial function.
1377
1378 @c ===beg===
1379 @c (n+1)!/n!,factorial_expand:true;
1380 @c ===end===
1381 @example
1382 @group
1383 (%i1) (n+1)!/n!,factorial_expand:true;
1384 (%o1)                         n + 1
1385 @end group
1386 @end example
1387
1388 @opencatbox{Categories:}
1389 @category{Gamma and factorial functions}
1390 @category{Operators}
1391 @closecatbox
1392 @end deffn
1393
1394 @c NEEDS EXAMPLES
1395
1396 @c -----------------------------------------------------------------------------
1397 @anchor{factlim}
1398 @defvr {Option variable} factlim
1399 Default value: 100000
1400
1401 @code{factlim} specifies the highest factorial which is
1402 automatically expanded.  If it is -1 then all integers are expanded.
1403
1404 @opencatbox{Categories:}
1405 @category{Gamma and factorial functions}
1406 @closecatbox
1407 @end defvr
1408
1409 @c -----------------------------------------------------------------------------
1410 @anchor{factorial_expand}
1411 @defvr {Option variable} factorial_expand
1412 Default value: false
1413
1414 The option variable @code{factorial_expand} controls the simplification of
1415 expressions like @code{(x+n)!}, where @code{n} is an integer.
1416 See @mref{factorial} for an example.
1417
1418 @opencatbox{Categories:}
1419 @category{Gamma and factorial functions}
1420 @closecatbox
1421 @end defvr
1422
1423 @c IS THIS DEFINITION CORRECT ??
1424
1425 @c -----------------------------------------------------------------------------
1426 @anchor{genfact}
1427 @deffn {Function} genfact (@var{x}, @var{y}, @var{z})
1428
1429 Returns the generalized factorial, defined as
1430 @code{x (x-z) (x - 2 z) ... (x - (y - 1) z)}.  Thus, when @var{x} is an integer,
1431 @code{genfact (x, x, 1) = x!} and @code{genfact (x, x/2, 2) = x!!}.
1432
1433 @opencatbox{Categories:}
1434 @category{Gamma and factorial functions}
1435 @closecatbox
1436 @end deffn
1437
1438 @c -----------------------------------------------------------------------------
1439 @anchor{minfactorial}
1440 @deffn {Function} minfactorial (@var{expr})
1441
1442 Examines @var{expr} for occurrences of two factorials
1443 which differ by an integer.
1444 @code{minfactorial} then turns one into a polynomial times the other.
1445
1446 @c I CAN'T TELL WHAT THIS IS SUPPOSED TO MEAN. !!!
1447 @c minfactorial DOESN'T SEEM TO DO ANYTHING binomial DOESN'T DO BY ITSELF !!!
1448 @c LOOKING AT THE minfactorial CODE DOESN'T HELP !!!
1449 @c If exp involves binomial coefficients then they will be
1450 @c converted into ratios of factorials.
1451
1452 @c ===beg===
1453 @c n!/(n+2)!;
1454 @c minfactorial (%);
1455 @c ===end===
1456 @example
1457 @group
1458 (%i1) n!/(n+2)!;
1459                                n!
1460 (%o1)                       --------
1461                             (n + 2)!
1462 @end group
1463 @group
1464 (%i2) minfactorial (%);
1465                                 1
1466 (%o2)                    ---------------
1467                          (n + 1) (n + 2)
1468 @end group
1469 @end example
1470
1471 @opencatbox{Categories:}
1472 @category{Number theory}
1473 @closecatbox
1474 @end deffn
1475
1476 @c -----------------------------------------------------------------------------
1477 @anchor{sumsplitfact}
1478 @defvr {Option variable} sumsplitfact
1479 Default value: @code{true}
1480
1481 When @code{sumsplitfact} is @code{false},
1482 @c "IS APPLIED" -- UNDER WHAT CIRCUMSTANCES EXACTLY ??
1483 @mref{minfactorial} is applied after a @mrefdot{factcomb}
1484
1485 @c ===beg===
1486 @c sumsplitfact;
1487 @c n!/(n+2)!;
1488 @c factcomb(%);
1489 @c sumsplitfact: not sumsplitfact ;
1490 @c n!/(n+2)!;
1491 @c factcomb(%);
1492 @c ===end===
1493 @example
1494 @group
1495 (%i1) sumsplitfact;
1496 (%o1)                         true
1497 @end group
1498 @group
1499 (%i2) n!/(n+2)!;
1500                                n!
1501 (%o2)                       --------
1502                             (n + 2)!
1503 @end group
1504 @group
1505 (%i3) factcomb(%);
1506                                n!
1507 (%o3)                       --------
1508                             (n + 2)!
1509 @end group
1510 @group
1511 (%i4) sumsplitfact: not sumsplitfact ;
1512 (%o4)                         false
1513 @end group
1514 @group
1515 (%i5) n!/(n+2)!;
1516                                n!
1517 (%o5)                       --------
1518                             (n + 2)!
1519 @end group
1520 @group
1521 (%i6) factcomb(%);
1522                                 1
1523 (%o6)                    ---------------
1524                          (n + 1) (n + 2)
1525 @end group
1526 @end example
1527
1528 @opencatbox{Categories:}
1529 @category{Gamma and factorial functions}
1530 @category{Simplification flags and variables}
1531 @closecatbox
1532 @end defvr
1533
1534 @c -----------------------------------------------------------------------------
1535 @node Root Exponential and Logarithmic Functions, Trigonometric Functions, Combinatorial Functions, Elementary Functions
1536 @section Root, Exponential and Logarithmic Functions
1537 @c -----------------------------------------------------------------------------
1538
1539 @c -----------------------------------------------------------------------------
1540 @anchor{%e_to_numlog}
1541 @defvr {Option variable} %e_to_numlog
1542 Default value: @code{false}
1543
1544 When @code{true}, @code{r} some rational number, and @code{x} some expression,
1545 @code{%e^(r*log(x))} will be simplified into @code{x^r} .  It should be noted
1546 that the @code{radcan} command also does this transformation, and more
1547 complicated transformations of this ilk as well.  The @code{logcontract}
1548 command "contracts" expressions containing @code{log}.
1549
1550 @opencatbox{Categories:}
1551 @category{Exponential and logarithm functions}
1552 @category{Simplification flags and variables}
1553 @closecatbox
1554 @end defvr
1555
1556 @c -----------------------------------------------------------------------------
1557 @anchor{%emode}
1558 @defvr {Option variable} %emode
1559 Default value: @code{true}
1560
1561 When @code{%emode} is @code{true}, @code{%e^(%pi %i x)} is simplified as
1562 follows.
1563
1564 @code{%e^(%pi %i x)} simplifies to @code{cos (%pi x) + %i sin (%pi x)} if
1565 @code{x} is a floating point number, an integer, or a multiple of 1/2, 1/3, 1/4,
1566 or 1/6, and then further simplified.
1567
1568 For other numerical @code{x}, @code{%e^(%pi %i x)} simplifies to
1569 @code{%e^(%pi %i y)} where @code{y} is @code{x - 2 k} for some integer @code{k}
1570 such that @code{abs(y) < 1}.
1571
1572 When @code{%emode} is @code{false}, no special simplification of
1573 @code{%e^(%pi %i x)} is carried out.
1574
1575 @c ===beg===
1576 @c %emode;
1577 @c %e^(%pi*%i*1);
1578 @c %e^(%pi*%i*216/144);
1579 @c %e^(%pi*%i*192/144);
1580 @c %e^(%pi*%i*180/144);
1581 @c %e^(%pi*%i*120/144);
1582 @c %e^(%pi*%i*121/144);
1583 @c ===end===
1584 @example
1585 @group
1586 (%i1) %emode;
1587 (%o1)                         true
1588 @end group
1589 @group
1590 (%i2) %e^(%pi*%i*1);
1591 (%o2)                          - 1
1592 @end group
1593 @group
1594 (%i3) %e^(%pi*%i*216/144);
1595 (%o3)                         - %i
1596 @end group
1597 @group
1598 (%i4) %e^(%pi*%i*192/144);
1599                           sqrt(3) %i   1
1600 (%o4)                   - ---------- - -
1601                               2        2
1602 @end group
1603 @group
1604 (%i5) %e^(%pi*%i*180/144);
1605                            %i         1
1606 (%o5)                  - ------- - -------
1607                          sqrt(2)   sqrt(2)
1608 @end group
1609 @group
1610 (%i6) %e^(%pi*%i*120/144);
1611                           %i   sqrt(3)
1612 (%o6)                     -- - -------
1613                           2       2
1614 @end group
1615 @group
1616 (%i7) %e^(%pi*%i*121/144);
1617                             121 %i %pi
1618                             ----------
1619                                144
1620 (%o7)                     %e
1621 @end group
1622 @end example
1623
1624 @opencatbox{Categories:}
1625 @category{Exponential and logarithm functions}
1626 @category{Simplification flags and variables}
1627 @closecatbox
1628 @end defvr
1629
1630 @c -----------------------------------------------------------------------------
1631 @anchor{%enumer}
1632 @defvr {Option variable} %enumer
1633 Default value: @code{false}
1634
1635 When @code{%enumer} is @code{true}, @code{%e} is replaced by its numeric value
1636 2.718@dots{}  whenever @code{numer} is @code{true}.
1637
1638 When @code{%enumer} is @code{false}, this substitution is carried out
1639 only if the exponent in @code{%e^x} evaluates to a number.
1640
1641 See also @mref{ev} and @mrefdot{numer}
1642
1643 @c ===beg===
1644 @c %enumer;
1645 @c numer;
1646 @c 2*%e;
1647 @c %enumer: not %enumer;
1648 @c 2*%e;
1649 @c numer: not numer;
1650 @c 2*%e;
1651 @c 2*%e^1;
1652 @c 2*%e^x;
1653 @c ===end===
1654 @example
1655 @group
1656 (%i1) %enumer;
1657 (%o1)                         false
1658 @end group
1659 @group
1660 (%i2) numer;
1661 (%o2)                         false
1662 @end group
1663 @group
1664 (%i3) 2*%e;
1665 (%o3)                         2 %e
1666 @end group
1667 @group
1668 (%i4) %enumer: not %enumer;
1669 (%o4)                         true
1670 @end group
1671 @group
1672 (%i5) 2*%e;
1673 (%o5)                         2 %e
1674 @end group
1675 @group
1676 (%i6) numer: not numer;
1677 (%o6)                         true
1678 @end group
1679 @group
1680 (%i7) 2*%e;
1681 (%o7)                   5.43656365691809
1682 @end group
1683 @group
1684 (%i8) 2*%e^1;
1685 (%o8)                   5.43656365691809
1686 @end group
1687 @group
1688 (%i9) 2*%e^x;
1689                                          x
1690 (%o9)                 2 2.718281828459045
1691 @end group
1692 @end example
1693
1694 @opencatbox{Categories:}
1695 @category{Exponential and logarithm functions}
1696 @category{Evaluation flags}
1697 @closecatbox
1698 @end defvr
1699
1700 @c PROBABLY MORE TO BE SAID HERE
1701
1702 @c -----------------------------------------------------------------------------
1703 @anchor{exp}
1704 @deffn {Function} exp (@var{x})
1705
1706 Represents the exponential function.  Instances of @code{exp (@var{x})} in input
1707 are simplified to @code{%e^@var{x}}; @code{exp} does not appear in simplified
1708 expressions.
1709
1710 @code{demoivre} if @code{true} causes @code{%e^(a + b %i)} to simplify to
1711 @code{%e^(a (cos(b) + %i sin(b)))} if @code{b} is free of @code{%i}.
1712 See @mrefdot{demoivre}
1713
1714 @code{%emode}, when @code{true}, causes @code{%e^(%pi %i x)} to be simplified.
1715 See @mrefdot{%emode}
1716
1717 @code{%enumer}, when @code{true} causes @code{%e} to be replaced by
1718 2.718@dots{} whenever @code{numer} is @code{true}.  See @mrefdot{%enumer}
1719
1720 @c ===beg===
1721 @c demoivre;
1722 @c %e^(a + b*%i);
1723 @c demoivre: not demoivre;
1724 @c %e^(a + b*%i);
1725 @c ===end===
1726 @example
1727 @group
1728 (%i1) demoivre;
1729 (%o1)                         false
1730 @end group
1731 @group
1732 (%i2) %e^(a + b*%i);
1733                              %i b + a
1734 (%o2)                      %e
1735 @end group
1736 @group
1737 (%i3) demoivre: not demoivre;
1738 (%o3)                         true
1739 @end group
1740 @group
1741 (%i4) %e^(a + b*%i);
1742                       a
1743 (%o4)               %e  (%i sin(b) + cos(b))
1744 @end group
1745 @end example
1746
1747 @opencatbox{Categories:}
1748 @category{Exponential and logarithm functions}
1749 @closecatbox
1750 @end deffn
1751
1752
1753 @c -----------------------------------------------------------------------------
1754 @anchor{li}
1755 @deffn {Function} li [@var{s}] (@var{z})
1756
1757 Represents the polylogarithm function of order @var{s} and argument @var{z},
1758 defined by the infinite series
1759
1760 m4_displaymath(
1761 <<<{\rm Li}_s \left(z\right) = \sum_{k=1}^\infty {z^k \over k^s}>>>,
1762 <<<
1763 @example
1764                                  inf
1765                                  ====   k
1766                                  \     z
1767                         Li (z) =  >    --
1768                           s      /      s
1769                                  ====  k
1770                                  k = 1
1771 @end example
1772 >>>)
1773
1774
1775 @code{li[1](z)} is
1776 m4_mathdot(-\log(1 - z),-log(1-z))
1777 @code{li[2]} and @code{li[3]} are the
1778 dilogarithm and trilogarithm functions, respectively.
1779
1780 When the order is 1, the polylogarithm simplifies to @code{- log (1 - z)}, which
1781 in turn simplifies to a numerical value if @var{z} is a real or complex floating
1782 point number or the @code{numer} evaluation flag is present.
1783
1784 When the order is 2 or 3,
1785 the polylogarithm simplifies to a numerical value
1786 if @var{z} is a real floating point number
1787 or the @code{numer} evaluation flag is present.
1788
1789 Examples:
1790
1791 @c ===beg===
1792 @c assume (x > 0);
1793 @c integrate ((log (1 - t)) / t, t, 0, x);
1794 @c li[4](1);
1795 @c li[5](1);
1796 @c li[2](1/2);
1797 @c li[2](%i);
1798 @c li[2](1+%i);
1799 @c li [2] (7);
1800 @c li [2] (7), numer;
1801 @c li [3] (7);
1802 @c li [2] (7), numer;
1803 @c L : makelist (i / 4.0, i, 0, 8);
1804 @c map (lambda ([x], li [2] (x)), L);
1805 @c map (lambda ([x], li [3] (x)), L);
1806 @c ===end===
1807 @example
1808 @group
1809 (%i1) assume (x > 0);
1810 (%o1)                        [x > 0]
1811 @end group
1812 @group
1813 (%i2) integrate ((log (1 - t)) / t, t, 0, x);
1814 (%o2)                       - li (x)
1815                                 2
1816 @end group
1817 @group
1818 (%i3) li[4](1);
1819                                  4
1820                               %pi
1821 (%o3)                         ----
1822                                90
1823 @end group
1824 @group
1825 (%i4) li[5](1);
1826 (%o4)                        zeta(5)
1827 @end group
1828 @group
1829 (%i5) li[2](1/2);
1830                             2      2
1831                          %pi    log (2)
1832 (%o5)                    ---- - -------
1833                           12       2
1834 @end group
1835 @group
1836 (%i6) li[2](%i);
1837                                         2
1838                                      %pi
1839 (%o6)                  %catalan %i - ----
1840                                       48
1841 @end group
1842 @group
1843 (%i7) li[2](1+%i);
1844                                   2
1845                %i %pi log(2)   %pi
1846 (%o7)          ------------- + ---- + %catalan %i
1847                      4          16
1848 @end group
1849 @group
1850 (%i8) li [2] (7);
1851 (%o8)                        li (7)
1852                                2
1853 @end group
1854 @group
1855 (%i9) li [2] (7), numer;
1856 (%o9)      1.2482731820994244 - 6.1132570288179915 %i
1857 @end group
1858 @group
1859 (%i10) li [3] (7);
1860 (%o10)                       li (7)
1861                                3
1862 @end group
1863 @group
1864 (%i11) li [2] (7), numer;
1865 (%o11)     1.2482731820994244 - 6.1132570288179915 %i
1866 @end group
1867 @group
1868 (%i12) L : makelist (i / 4.0, i, 0, 8);
1869 (%o12)  [0.0, 0.25, 0.5, 0.75, 1.0, 1.25, 1.5, 1.75, 2.0]
1870 @end group
1871 @group
1872 (%i13) map (lambda ([x], li [2] (x)), L);
1873 (%o13) [0.0, 0.2676526390827326, 0.5822405264650125,
1874 0.978469392930306, 1.6449340668482264,
1875 2.1901770114416452 - 0.7010261415046585 %i,
1876 2.3743952702724798 - 1.2738062049196004 %i,
1877 2.448686765338203 - 1.7580848482107874 %i,
1878 2.4674011002723395 - 2.177586090303602 %i]
1879 @end group
1880 @group
1881 (%i14) map (lambda ([x], li [3] (x)), L);
1882 (%o14) [0.0, 0.25846139579657335, 0.5372131936080402,
1883 0.8444258088622044, 1.2020569031595942,
1884 1.6428668813178295 - 0.07821473138972386 %i,
1885 2.0608775073202805 - 0.258241985293288 %i,
1886 2.433418898226189 - 0.49192601879440423 %i,
1887 2.762071906228924 - 0.7546938294602477 %i]
1888 @end group
1889 @end example
1890
1891 @opencatbox{Categories:}
1892 @category{Exponential and logarithm functions}
1893 @closecatbox
1894 @end deffn
1895
1896 @c -----------------------------------------------------------------------------
1897 @anchor{log}
1898 @deffn {Function} log (@var{x})
1899
1900 Represents the natural (base @math{e}) logarithm of @var{x}.
1901
1902 Maxima does not have a built-in function for the base 10 logarithm or other
1903 bases. @code{log10(x) := log(x) / log(10)} is a useful definition.
1904
1905 Simplification and evaluation of logarithms is governed by several global flags:
1906
1907 @table @code
1908 @item @code{logexpand}
1909 causes @code{log(a^b)} to become @code{b*log(a)}. If it is
1910 set to @code{all}, @code{log(a*b)} will also simplify to @code{log(a)+log(b)}.
1911 If it is set to @code{super}, then @code{log(a/b)} will also simplify to
1912 @code{log(a)-log(b)} for rational numbers @code{a/b}, @code{a#1}.
1913 (@code{log(1/b)}, for @code{b} integer, always simplifies.) If it is set to
1914 @code{false}, all of these simplifications will be turned off.
1915
1916 @item @code{logsimp}
1917 if @code{false} then no simplification of @code{%e} to a power containing
1918 @code{log}'s is done.
1919
1920 @item @code{lognegint}
1921 if @code{true} implements the rule @code{log(-n) -> log(n)+%i*%pi} for
1922 @code{n} a positive integer.
1923
1924 @item @code{%e_to_numlog}
1925 when @code{true}, @code{r} some rational number, and @code{x} some expression,
1926 the expression @code{%e^(r*log(x))} will be simplified into @code{x^r}.  It
1927 should be noted that the @code{radcan} command also does this transformation,
1928 and more complicated transformations of this as well. The @code{logcontract}
1929 command "contracts" expressions containing @code{log}.
1930 @end table
1931
1932 @opencatbox{Categories:}
1933 @category{Exponential and logarithm functions}
1934 @closecatbox
1935 @end deffn
1936
1937 @c -----------------------------------------------------------------------------
1938 @anchor{logabs}
1939 @defvr {Option variable} logabs
1940 Default value: @code{false}
1941
1942 When doing indefinite integration where logs are generated, e.g.
1943 @code{integrate(1/x,x)}, the answer is given in terms of @code{log(abs(...))}
1944 if @code{logabs} is @code{true}, but in terms of @code{log(...)} if
1945 @code{logabs} is @code{false}.  For definite integration, the @code{logabs:true}
1946 setting is used, because here "evaluation" of the indefinite integral at the
1947 endpoints is often needed.
1948
1949 @opencatbox{Categories:}
1950 @category{Exponential and logarithm functions}
1951 @category{Integral calculus}
1952 @category{Global flags}
1953 @closecatbox
1954 @end defvr
1955
1956 @c NEEDS EXAMPLES
1957
1958 @c -----------------------------------------------------------------------------
1959 @deffn {Function} logarc (@var{expr})
1960
1961 The function @code{logarc(@var{expr})} carries out the replacement of
1962 inverse circular and hyperbolic functions with equivalent logarithmic
1963 functions for an expression @var{expr} without setting the global
1964 variable @code{logarc}.
1965
1966 @opencatbox{Categories:}
1967 @category{Exponential and logarithm functions}
1968 @category{Simplification flags and variables}
1969 @category{Simplification functions}
1970 @closecatbox
1971 @end deffn
1972
1973 @anchor{logarc}
1974 @defvr  {Option variable} logarc
1975
1976 When the global variable @code{logarc} is @code{true},
1977 inverse circular and hyperbolic functions are replaced by
1978 equivalent logarithmic functions.
1979 The default value of @code{logarc} is @code{false}.
1980
1981 @opencatbox{Categories:}
1982 @category{Exponential and logarithm functions}
1983 @category{Simplification flags and variables}
1984 @category{Simplification functions}
1985 @closecatbox
1986 @end defvr
1987
1988 @c -----------------------------------------------------------------------------
1989 @anchor{logconcoeffp}
1990 @defvr {Option variable} logconcoeffp
1991 Default value: @code{false}
1992
1993 Controls which coefficients are
1994 contracted when using @code{logcontract}.  It may be set to the name of a
1995 predicate function of one argument.  E.g. if you like to generate
1996 SQRTs, you can do @code{logconcoeffp:'logconfun$
1997 logconfun(m):=featurep(m,integer) or ratnump(m)$} .  Then
1998 @code{logcontract(1/2*log(x));} will give @code{log(sqrt(x))}.
1999
2000 @opencatbox{Categories:}
2001 @category{Exponential and logarithm functions}
2002 @category{Simplification flags and variables}
2003 @closecatbox
2004 @end defvr
2005
2006 @c -----------------------------------------------------------------------------
2007 @anchor{logcontract}
2008 @deffn {Function} logcontract (@var{expr})
2009
2010 Recursively scans the expression @var{expr}, transforming
2011 subexpressions of the form @code{a1*log(b1) + a2*log(b2) + c} into
2012 @code{log(ratsimp(b1^a1 * b2^a2)) + c}
2013
2014 @c ===beg===
2015 @c 2*(a*log(x) + 2*a*log(y))$
2016 @c logcontract(%);
2017 @c ===end===
2018 @example
2019 (%i1) 2*(a*log(x) + 2*a*log(y))$
2020 @group
2021 (%i2) logcontract(%);
2022                                  2  4
2023 (%o2)                     a log(x  y )
2024 @end group
2025 @end example
2026
2027 The declaration @code{declare(n,integer)} causes
2028 @code{logcontract(2*a*n*log(x))} to simplify to @code{a*log(x^(2*n))}.  The
2029 coefficients that "contract" in this manner are those such as the 2 and the
2030 @code{n} here which satisfy @code{featurep(coeff,integer)}.  The user can
2031 control which coefficients are contracted by setting the option
2032 @code{logconcoeffp} to the name of a predicate function of one argument.
2033 E.g. if you like to generate SQRTs, you can do @code{logconcoeffp:'logconfun$
2034 logconfun(m):=featurep(m,integer) or ratnump(m)$} .  Then
2035 @code{logcontract(1/2*log(x));} will give @code{log(sqrt(x))}.
2036
2037 @opencatbox{Categories:}
2038 @category{Exponential and logarithm functions}
2039 @closecatbox
2040 @end deffn
2041
2042 @c -----------------------------------------------------------------------------
2043 @anchor{logexpand}
2044 @defvr {Option variable} logexpand
2045 Default value: @code{true}
2046
2047 If @code{true}, that is the default value, causes @code{log(a^b)} to become
2048 @code{b*log(a)}.  If it is set to @code{all}, @code{log(a*b)} will also simplify
2049 to @code{log(a)+log(b)}.  If it is set to @code{super}, then @code{log(a/b)}
2050 will also simplify to @code{log(a)-log(b)} for rational numbers @code{a/b},
2051 @code{a#1}.  (@code{log(1/b)}, for integer @code{b}, always simplifies.) If it
2052 is set to @code{false}, all of these simplifications will be turned off.
2053
2054 When @code{logexpand} is set to @code{all} or @code{super},
2055 the logarithm of a product expression simplifies to a summation of logarithms.
2056
2057 Examples:
2058
2059 When @code{logexpand} is @code{true},
2060 @code{log(a^b)} simplifies to @code{b*log(a)}.
2061
2062 @c ===beg===
2063 @c log(n^2), logexpand=true;
2064 @c ===end===
2065 @example
2066 @group
2067 (%i1) log(n^2), logexpand=true;
2068 (%o1)                       2 log(n)
2069 @end group
2070 @end example
2071
2072 When @code{logexpand} is @code{all},
2073 @code{log(a*b)} simplifies to @code{log(a)+log(b)}.
2074
2075 @c ===beg===
2076 @c log(10*x), logexpand=all;
2077 @c ===end===
2078 @example
2079 @group
2080 (%i1) log(10*x), logexpand=all;
2081 (%o1)                   log(x) + log(10)
2082 @end group
2083 @end example
2084
2085 When @code{logexpand} is @code{super},
2086 @code{log(a/b)} simplifies to @code{log(a)-log(b)}
2087 for rational numbers @code{a/b} with @code{a#1}.
2088
2089 @c ===beg===
2090 @c log(a/(n + 1)), logexpand=super;
2091 @c ===end===
2092 @example
2093 @group
2094 (%i1) log(a/(n + 1)), logexpand=super;
2095 (%o1)                  log(a) - log(n + 1)
2096 @end group
2097 @end example
2098
2099 When @code{logexpand} is set to @code{all} or @code{super},
2100 the logarithm of a product expression simplifies to a summation of logarithms.
2101
2102 @c ===beg===
2103 @c my_product : product (X(i), i, 1, n);
2104 @c log(my_product), logexpand=all;
2105 @c log(my_product), logexpand=super;
2106 @c ===end===
2107 @example
2108 @group
2109 (%i1) my_product : product (X(i), i, 1, n);
2110                              n
2111                            _____
2112                            |   |
2113 (%o1)                      |   | X(i)
2114                            |   |
2115                            i = 1
2116 @end group
2117 @group
2118 (%i2) log(my_product), logexpand=all;
2119                           n
2120                          ____
2121                          \
2122 (%o2)                     >    log(X(i))
2123                          /
2124                          ----
2125                          i = 1
2126 @end group
2127 @group
2128 (%i3) log(my_product), logexpand=super;
2129                           n
2130                          ____
2131                          \
2132 (%o3)                     >    log(X(i))
2133                          /
2134                          ----
2135                          i = 1
2136 @end group
2137 @end example
2138
2139 When @code{logexpand} is @code{false},
2140 these simplifications are disabled.
2141
2142 @c ===beg===
2143 @c logexpand : false $
2144 @c log(n^2);
2145 @c log(10*x);
2146 @c log(a/(n + 1));
2147 @c log ('product (X(i), i, 1, n));
2148 @c ===end===
2149 @example
2150 (%i1) logexpand : false $
2151 @group
2152 (%i2) log(n^2);
2153                                   2
2154 (%o2)                        log(n )
2155 @end group
2156 @group
2157 (%i3) log(10*x);
2158 (%o3)                       log(10 x)
2159 @end group
2160 @group
2161 (%i4) log(a/(n + 1));
2162                                  a
2163 (%o4)                      log(-----)
2164                                n + 1
2165 @end group
2166 @group
2167 (%i5) log ('product (X(i), i, 1, n));
2168                                n
2169                              _____
2170                              |   |
2171 (%o5)                    log(|   | X(i))
2172                              |   |
2173                              i = 1
2174 @end group
2175 @end example
2176
2177 @opencatbox{Categories:}
2178 @category{Exponential and logarithm functions}
2179 @category{Simplification flags and variables}
2180 @closecatbox
2181 @end defvr
2182
2183 @c -----------------------------------------------------------------------------
2184 @anchor{lognegint}
2185 @defvr {Option variable} lognegint
2186 Default value: @code{false}
2187
2188 If @code{true} implements the rule
2189 @code{log(-n) -> log(n)+%i*%pi} for @code{n} a positive integer.
2190
2191 @opencatbox{Categories:}
2192 @category{Exponential and logarithm functions}
2193 @category{Simplification flags and variables}
2194 @closecatbox
2195 @end defvr
2196
2197 @c -----------------------------------------------------------------------------
2198 @anchor{logsimp}
2199 @defvr {Option variable} logsimp
2200 Default value: @code{true}
2201
2202 If @code{false} then no simplification of @code{%e} to a
2203 power containing @code{log}'s is done.
2204
2205 @opencatbox{Categories:}
2206 @category{Exponential and logarithm functions}
2207 @category{Simplification flags and variables}
2208 @closecatbox
2209 @end defvr
2210
2211 @c -----------------------------------------------------------------------------
2212 @anchor{plog}
2213 @deffn {Function} plog (@var{x})
2214
2215 Represents the principal branch of the complex-valued natural
2216 logarithm with @code{-%pi < carg(@var{x}) <= +%pi} .
2217
2218 @opencatbox{Categories:}
2219 @category{Exponential and logarithm functions}
2220 @category{Complex variables}
2221 @closecatbox
2222 @end deffn
2223
2224 @c -----------------------------------------------------------------------------
2225 @anchor{sqrt}
2226 @deffn {Function} sqrt (@var{x})
2227
2228 The square root of @var{x}.  It is represented internally by
2229 @code{@var{x}^(1/2)}.  See also @mref{rootscontract} and @mrefdot{radexpand}
2230
2231 @opencatbox{Categories:}
2232 @category{Mathematical functions}
2233 @closecatbox
2234 @end deffn
2235
2236 @c -----------------------------------------------------------------------------
2237 @page
2238 @node Trigonometric Functions, Random Numbers, Root Exponential and Logarithmic Functions, Elementary Functions
2239 @section Trigonometric Functions
2240 @c -----------------------------------------------------------------------------
2241
2242 @menu
2243 * Introduction to Trigonometric::
2244 * Functions and Variables for Trigonometric::
2245 @end menu
2246
2247 @c -----------------------------------------------------------------------------
2248 @node Introduction to Trigonometric, Functions and Variables for Trigonometric, Trigonometric Functions, Trigonometric Functions
2249 @subsection Introduction to Trigonometric
2250 @c -----------------------------------------------------------------------------
2251
2252 Maxima has many trigonometric functions defined.  Not all trigonometric
2253 identities are programmed, but it is possible for the user to add many
2254 of them using the pattern matching capabilities of the system.  The
2255 trigonometric functions defined in Maxima are: @mref{acos},
2256 @mref{acosh}, @mref{acot}, @mref{acoth}, @mref{acsc},
2257 @mref{acsch}, @mref{asec}, @mref{asech}, @mref{asin},
2258 @mref{asinh}, @mref{atan}, @mref{atanh}, @mref{cos},
2259 @mref{cosh}, @mref{cot}, @mref{coth}, @mref{csc}, @mref{csch},
2260 @mref{sec}, @mref{sech}, @mref{sin}, @mref{sinh}, @mref{tan},
2261 and @mref{tanh}.  There are a number of commands especially for
2262 handling trigonometric functions, see @mref{trigexpand},
2263 @mref{trigreduce}, and the switch @mref{trigsign}.  Two share
2264 packages extend the simplification rules built into Maxima,
2265 @mref{ntrig} and @mref{atrig1}.  Do @code{describe(@var{command})}
2266 for details.
2267
2268 @opencatbox{Categories:}
2269 @category{Trigonometric functions}
2270 @closecatbox
2271
2272 @c -----------------------------------------------------------------------------
2273 @node Functions and Variables for Trigonometric,  , Introduction to Trigonometric, Trigonometric Functions
2274 @subsection Functions and Variables for Trigonometric
2275 @c -----------------------------------------------------------------------------
2276
2277 @menu
2278 * Trigonometric and Hyperbolic Functions::
2279 * Options Controlling Simplification::
2280 * Explicit Simplifications Using Identities::
2281 * Additional Functions::
2282 @end menu
2283
2284 @node Trigonometric and Hyperbolic Functions, Options Controlling Simplification, Functions and Variables for Trigonometric, Functions and Variables for Trigonometric
2285 @subsubsection Trigonometric and Hyperbolic Functions
2286
2287 @c -----------------------------------------------------------------------------
2288 @anchor{acos}
2289 @deffn {Function} acos (@var{x})
2290
2291 -- Arc Cosine.
2292
2293 @opencatbox{Categories:}
2294 @category{Trigonometric functions}
2295 @closecatbox
2296 @end deffn
2297
2298 @c -----------------------------------------------------------------------------
2299 @anchor{acosh}
2300 @deffn {Function} acosh (@var{x})
2301
2302 -- Hyperbolic Arc Cosine.
2303
2304 @opencatbox{Categories:}
2305 @category{Hyperbolic functions}
2306 @closecatbox
2307 @end deffn
2308
2309 @c -----------------------------------------------------------------------------
2310 @anchor{acot}
2311 @deffn {Function} acot (@var{x})
2312
2313 -- Arc Cotangent.
2314
2315 @opencatbox{Categories:}
2316 @category{Trigonometric functions}
2317 @closecatbox
2318 @end deffn
2319
2320 @c -----------------------------------------------------------------------------
2321 @anchor{acoth}
2322 @deffn {Function} acoth (@var{x})
2323
2324 -- Hyperbolic Arc Cotangent.
2325
2326 @opencatbox{Categories:}
2327 @category{Hyperbolic functions}
2328 @closecatbox
2329 @end deffn
2330
2331 @c -----------------------------------------------------------------------------
2332 @anchor{acsc}
2333 @deffn {Function} acsc (@var{x})
2334
2335 -- Arc Cosecant.
2336
2337 @opencatbox{Categories:}
2338 @category{Trigonometric functions}
2339 @closecatbox
2340 @end deffn
2341
2342 @c -----------------------------------------------------------------------------
2343 @anchor{acsch}
2344 @deffn {Function} acsch (@var{x})
2345
2346 -- Hyperbolic Arc Cosecant.
2347
2348 @opencatbox{Categories:}
2349 @category{Hyperbolic functions}
2350 @closecatbox
2351 @end deffn
2352
2353 @c -----------------------------------------------------------------------------
2354 @anchor{asec}
2355 @deffn {Function} asec (@var{x})
2356
2357 -- Arc Secant.
2358
2359 @opencatbox{Categories:}
2360 @category{Trigonometric functions}
2361 @closecatbox
2362 @end deffn
2363
2364 @c -----------------------------------------------------------------------------
2365 @anchor{asech}
2366 @deffn {Function} asech (@var{x})
2367
2368 -- Hyperbolic Arc Secant.
2369
2370 @opencatbox{Categories:}
2371 @category{Hyperbolic functions}
2372 @closecatbox
2373 @end deffn
2374
2375 @c -----------------------------------------------------------------------------
2376 @anchor{asin}
2377 @deffn {Function} asin (@var{x})
2378
2379 -- Arc Sine.
2380
2381 @opencatbox{Categories:}
2382 @category{Trigonometric functions}
2383 @closecatbox
2384 @end deffn
2385
2386 @c -----------------------------------------------------------------------------
2387 @anchor{asinh}
2388 @deffn {Function} asinh (@var{x})
2389
2390 -- Hyperbolic Arc Sine.
2391
2392 @opencatbox{Categories:}
2393 @category{Hyperbolic functions}
2394 @closecatbox
2395 @end deffn
2396
2397 @c -----------------------------------------------------------------------------
2398 @anchor{atan}
2399 @deffn {Function} atan (@var{x})
2400
2401 -- Arc Tangent.
2402
2403 See also @mref{atan2}.
2404
2405 @opencatbox{Categories:}
2406 @category{Trigonometric functions}
2407 @closecatbox
2408 @end deffn
2409
2410 @c -----------------------------------------------------------------------------
2411 @anchor{atan2}
2412 @deffn {Function} atan2 (@var{y}, @var{x})
2413
2414 -- yields the value of
2415 m4_math(<<<\tan^{-1}(y/x)>>>, atan(y/x))
2416 in the interval
2417 m4_math(-\pi, -%pi)
2418 to
2419 m4_math(\pi, %pi)
2420 taking into
2421 consideration the quadrant of the point
2422 m4_mathdot(<<<(x,y)>>>, <<<(x,y)>>>)
2423
2424 Along the branch cut with @math{y = 0} and @math{x < 0}, @code{atan2}
2425 is continuous with the second quadrant.
2426 See also @mref{atan}.
2427
2428 @opencatbox{Categories:}
2429 @category{Trigonometric functions}
2430 @closecatbox
2431 @end deffn
2432
2433 @c -----------------------------------------------------------------------------
2434 @anchor{atanh}
2435 @deffn {Function} atanh (@var{x})
2436
2437 -- Hyperbolic Arc Tangent.
2438
2439 @opencatbox{Categories:}
2440 @category{Hyperbolic functions}
2441 @closecatbox
2442 @end deffn
2443
2444 @c -----------------------------------------------------------------------------
2445 @anchor{cos}
2446 @deffn {Function} cos (@var{x})
2447
2448 -- Cosine.
2449
2450 @opencatbox{Categories:}
2451 @category{Trigonometric functions}
2452 @closecatbox
2453 @end deffn
2454
2455 @c -----------------------------------------------------------------------------
2456 @anchor{cosh}
2457 @deffn {Function} cosh (@var{x})
2458
2459 -- Hyperbolic Cosine.
2460
2461 @opencatbox{Categories:}
2462 @category{Hyperbolic functions}
2463 @closecatbox
2464 @end deffn
2465
2466 @c -----------------------------------------------------------------------------
2467 @anchor{cot}
2468 @deffn {Function} cot (@var{x})
2469
2470 -- Cotangent.
2471
2472 @opencatbox{Categories:}
2473 @category{Trigonometric functions}
2474 @closecatbox
2475 @end deffn
2476
2477 @c -----------------------------------------------------------------------------
2478 @anchor{coth}
2479 @deffn {Function} coth (@var{x})
2480
2481 -- Hyperbolic Cotangent.
2482
2483 @opencatbox{Categories:}
2484 @category{Hyperbolic functions}
2485 @closecatbox
2486 @end deffn
2487
2488 @c -----------------------------------------------------------------------------
2489 @anchor{csc}
2490 @deffn {Function} csc (@var{x})
2491
2492 -- Cosecant.
2493
2494 @opencatbox{Categories:}
2495 @category{Trigonometric functions}
2496 @closecatbox
2497 @end deffn
2498
2499 @c -----------------------------------------------------------------------------
2500 @anchor{csch}
2501 @deffn {Function} csch (@var{x})
2502
2503 -- Hyperbolic Cosecant.
2504
2505 @opencatbox{Categories:}
2506 @category{Hyperbolic functions}
2507 @closecatbox
2508 @end deffn
2509
2510 @c -----------------------------------------------------------------------------
2511 @anchor{sec}
2512 @deffn {Function} sec (@var{x})
2513
2514 -- Secant.
2515
2516 @opencatbox{Categories:}
2517 @category{Trigonometric functions}
2518 @closecatbox
2519 @end deffn
2520
2521 @c -----------------------------------------------------------------------------
2522 @anchor{sech}
2523 @deffn {Function} sech (@var{x})
2524
2525 -- Hyperbolic Secant.
2526
2527 @opencatbox{Categories:}
2528 @category{Hyperbolic functions}
2529 @closecatbox
2530 @end deffn
2531
2532 @c -----------------------------------------------------------------------------
2533 @anchor{sin}
2534 @deffn {Function} sin (@var{x})
2535
2536 -- Sine.
2537
2538 @opencatbox{Categories:}
2539 @category{Trigonometric functions}
2540 @closecatbox
2541 @end deffn
2542
2543 @c -----------------------------------------------------------------------------
2544 @anchor{sinh}
2545 @deffn {Function} sinh (@var{x})
2546
2547 -- Hyperbolic Sine.
2548
2549 @opencatbox{Categories:}
2550 @category{Hyperbolic functions}
2551 @closecatbox
2552 @end deffn
2553
2554 @c -----------------------------------------------------------------------------
2555 @anchor{tan}
2556 @deffn {Function} tan (@var{x})
2557
2558 -- Tangent.
2559
2560 @opencatbox{Categories:}
2561 @category{Trigonometric functions}
2562 @closecatbox
2563 @end deffn
2564
2565 @c -----------------------------------------------------------------------------
2566 @anchor{tanh}
2567 @deffn {Function} tanh (@var{x})
2568
2569 -- Hyperbolic Tangent.
2570
2571 @opencatbox{Categories:}
2572 @category{Hyperbolic functions}
2573 @closecatbox
2574 @end deffn
2575
2576
2577 @node Options Controlling Simplification, Explicit Simplifications Using Identities, Trigonometric and Hyperbolic Functions, Functions and Variables for Trigonometric
2578 @subsubsection Options Controlling Simplification
2579 @c -----------------------------------------------------------------------------
2580 @anchor{%piargs}
2581 @defvr {Option variable} %piargs
2582 Default value: @code{true}
2583
2584 When @code{%piargs} is @code{true},
2585 trigonometric functions are simplified to algebraic constants
2586 when the argument is an integer multiple
2587 of
2588 m4_mathcomma(\pi,%pi)
2589 m4_mathcomma(\pi/2,%pi/2)
2590 m4_mathcomma(\pi/4,%pi/4)
2591 or
2592 m4_mathdot(\pi/6,%pi/6)
2593 @c @iftex
2594 @c @math{\pi}, @math{\pi/2}, @math{\pi/3}, @math{\pi/4}, or @math{\pi/6}.
2595 @c @end iftex
2596 @c @ifnottex
2597 @c @math{%pi}, @math{%pi/2}, @math{%pi/3}, @math{%pi/4}, or @math{%pi/6}.
2598 @c @end ifnottex
2599
2600 Maxima knows some identities which can be applied when
2601 m4_mathcomma(\pi,%pi)
2602 etc.,
2603 @c @iftex
2604 @c Maxima knows some identities which can be applied when @math{\pi}, etc.,
2605 @c @end iftex
2606 @c @ifnottex
2607 @c Maxima knows some identities which can be applied when @math{%pi}, etc.,
2608 @c @end ifnottex
2609 are multiplied by an integer variable (that is, a symbol declared to be
2610 integer).
2611
2612 Examples:
2613
2614 @c ===beg===
2615 @c %piargs : false$
2616 @c [sin (%pi), sin (%pi/2), sin (%pi/3)];
2617 @c [sin (%pi/4), sin (%pi/5), sin (%pi/6)];
2618 @c %piargs : true$
2619 @c [sin (%pi), sin (%pi/2), sin (%pi/3)];
2620 @c [sin (%pi/4), sin (%pi/5), sin (%pi/6)];
2621 @c [cos (%pi/3), cos (10*%pi/3), tan (10*%pi/3),
2622 @c        cos (sqrt(2)*%pi/3)];
2623 @c ===end===
2624 @example
2625 (%i1) %piargs : false$
2626 @group
2627 (%i2) [sin (%pi), sin (%pi/2), sin (%pi/3)];
2628                                 %pi       %pi
2629 (%o2)            [sin(%pi), sin(---), sin(---)]
2630                                  2         3
2631 @end group
2632 @group
2633 (%i3) [sin (%pi/4), sin (%pi/5), sin (%pi/6)];
2634                       %pi       %pi       %pi
2635 (%o3)            [sin(---), sin(---), sin(---)]
2636                        4         5         6
2637 @end group
2638 (%i4) %piargs : true$
2639 @group
2640 (%i5) [sin (%pi), sin (%pi/2), sin (%pi/3)];
2641                                 sqrt(3)
2642 (%o5)                    [0, 1, -------]
2643                                    2
2644 @end group
2645 @group
2646 (%i6) [sin (%pi/4), sin (%pi/5), sin (%pi/6)];
2647                          1         %pi   1
2648 (%o6)                [-------, sin(---), -]
2649                       sqrt(2)       5    2
2650 @end group
2651 @group
2652 (%i7) [cos (%pi/3), cos (10*%pi/3), tan (10*%pi/3),
2653        cos (sqrt(2)*%pi/3)];
2654                 1    1               sqrt(2) %pi
2655 (%o7)          [-, - -, sqrt(3), cos(-----------)]
2656                 2    2                    3
2657 @end group
2658 @end example
2659
2660 Some identities are applied when
2661 m4_math(\pi,%pi)
2662 and
2663 m4_math(\pi/2,%pi/2)
2664 are
2665 multiplied by an integer variable.
2666 @c @iftex
2667 @c Some identities are applied when @math{\pi} and @math{\pi/2} are multiplied by
2668 @c an integer variable.
2669 @c @end iftex
2670 @c @ifnottex
2671 @c Some identities are applied when @math{%pi} and @math{%pi/2} are multiplied by
2672 @c an integer variable.
2673 @c @end ifnottex
2674
2675 @c ===beg===
2676 @c declare (n, integer, m, even)$
2677 @c [sin (%pi * n), cos (%pi * m), sin (%pi/2 * m),
2678 @c        cos (%pi/2 * m)];
2679 @c ===end===
2680 @example
2681 (%i1) declare (n, integer, m, even)$
2682 @group
2683 (%i2) [sin (%pi * n), cos (%pi * m), sin (%pi/2 * m),
2684        cos (%pi/2 * m)];
2685                                       m/2
2686 (%o2)                  [0, 1, 0, (- 1)   ]
2687 @end group
2688 @end example
2689
2690 @opencatbox{Categories:}
2691 @category{Trigonometric functions}
2692 @category{Simplification flags and variables}
2693 @closecatbox
2694 @end defvr
2695
2696 @c -----------------------------------------------------------------------------
2697 @anchor{%iargs}
2698 @defvr {Option variable} %iargs
2699 Default value: @code{true}
2700
2701 When @code{%iargs} is @code{true},
2702 trigonometric functions are simplified to hyperbolic functions
2703 when the argument is apparently a multiple of the imaginary
2704 unit
2705 m4_mathdot(i, %i)
2706 @c @iftex
2707 @c when the argument is apparently a multiple of the imaginary unit @math{i}.
2708 @c @end iftex
2709 @c @ifnottex
2710 @c when the argument is apparently a multiple of the imaginary unit @math{%i}.
2711 @c @end ifnottex
2712
2713 Even when the argument is demonstrably real, the simplification is applied;
2714 Maxima considers only whether the argument is a literal multiple
2715 of
2716 m4_mathdot(i,%i)
2717 @c @iftex
2718 @c Maxima considers only whether the argument is a literal multiple of @math{i}.
2719 @c @end iftex
2720 @c @ifnottex
2721 @c Maxima considers only whether the argument is a literal multiple of @math{%i}.
2722 @c @end ifnottex
2723
2724 Examples:
2725
2726 @c ===beg===
2727 @c %iargs : false$
2728 @c [sin (%i * x), cos (%i * x), tan (%i * x)];
2729 @c %iargs : true$
2730 @c [sin (%i * x), cos (%i * x), tan (%i * x)];
2731 @c ===end===
2732 @example
2733 (%i1) %iargs : false$
2734 @group
2735 (%i2) [sin (%i * x), cos (%i * x), tan (%i * x)];
2736 (%o2)           [sin(%i x), cos(%i x), tan(%i x)]
2737 @end group
2738 (%i3) %iargs : true$
2739 @group
2740 (%i4) [sin (%i * x), cos (%i * x), tan (%i * x)];
2741 (%o4)           [%i sinh(x), cosh(x), %i tanh(x)]
2742 @end group
2743 @end example
2744
2745 Even when the argument is demonstrably real, the simplification is applied.
2746
2747 @c ===beg===
2748 @c declare (x, imaginary)$
2749 @c [featurep (x, imaginary), featurep (x, real)];
2750 @c sin (%i * x);
2751 @c ===end===
2752 @example
2753 (%i1) declare (x, imaginary)$
2754 @group
2755 (%i2) [featurep (x, imaginary), featurep (x, real)];
2756 (%o2)                     [true, false]
2757 @end group
2758 @group
2759 (%i3) sin (%i * x);
2760 (%o3)                      %i sinh(x)
2761 @end group
2762 @end example
2763
2764 @opencatbox{Categories:}
2765 @category{Trigonometric functions}
2766 @category{Hyperbolic functions}
2767 @category{Simplification flags and variables}
2768 @closecatbox
2769 @end defvr
2770
2771 @c -----------------------------------------------------------------------------
2772 @anchor{halfangles}
2773 @defvr {Option variable} halfangles
2774 Default value: @code{false}
2775
2776 When @code{halfangles} is @code{true}, trigonometric functions of arguments
2777 @code{@var{expr}/2} are simplified to functions of @var{expr}.
2778
2779 For a real argument @math{x} in the interval
2780 m4_mathcomma(<<<0 \le x < 2\pi>>>, 0 <= x < 2*%pi)
2781 m4_math(<<<\sin{x\over 2}>>>, sin(x/2))
2782 simplifies to a simple formula:
2783 m4_displaymath(
2784 {\sqrt{1-\cos x}\over\sqrt{2}},
2785 @example
2786                          sqrt(1 - cos(x))
2787                          ----------------
2788                              sqrt(2)
2789 @end example
2790 )
2791
2792 A complicated factor is needed to make this formula correct for all complex
2793 arguments @math{z = x+iy}:
2794 m4_displaymath(
2795 (-1)^{\lfloor{x/(2\pi)}\rfloor}
2796 \left[1-\rm{unit\_step}(-y)
2797 \left(1+(-1)^{\lfloor{x/(2\pi)}\rfloor - \lceil{x/(2\pi)}\rceil}\right)\right]
2798 ,
2799 <<<@verbatim
2800               x                       x                x
2801       floor(-----)            floor(-----) - ceiling(-----)
2802             2 %pi                   2 %pi            2 %pi
2803  (- 1)             (1 - ((- 1)                              + 1)
2804                                                           unit_step(- y))
2805 @end verbatim
2806 >>>)
2807
2808 Maxima knows this factor and similar factors for the functions @code{sin},
2809 @code{cos}, @code{sinh}, and @code{cosh}.  For special values of the argument
2810 @math{z} these factors simplify accordingly.
2811
2812 Examples:
2813
2814 @c ===beg===
2815 @c halfangles : false$
2816 @c sin (x / 2);
2817 @c halfangles : true$
2818 @c sin (x / 2);
2819 @c assume(x>0, x<2*%pi)$
2820 @c sin(x / 2);
2821 @c ===end===
2822 @example
2823 (%i1) halfangles : false$
2824 @group
2825 (%i2) sin (x / 2);
2826                                  x
2827 (%o2)                        sin(-)
2828                                  2
2829 @end group
2830 (%i3) halfangles : true$
2831 @group
2832 (%i4) sin (x / 2);
2833                             x
2834                     floor(-----)
2835                           2 %pi
2836                (- 1)             sqrt(1 - cos(x))
2837 (%o4)          ----------------------------------
2838                             sqrt(2)
2839 @end group
2840 (%i5) assume(x>0, x<2*%pi)$
2841 @group
2842 (%i6) sin(x / 2);
2843                         sqrt(1 - cos(x))
2844 (%o6)                   ----------------
2845                             sqrt(2)
2846 @end group
2847 @end example
2848
2849 @opencatbox{Categories:}
2850 @category{Trigonometric functions}
2851 @category{Simplification flags and variables}
2852 @closecatbox
2853 @end defvr
2854
2855 @c -----------------------------------------------------------------------------
2856 @anchor{trigsign}
2857 @defvr {Option variable} trigsign
2858 Default value: @code{true}
2859
2860 When @code{trigsign} is @code{true}, it permits simplification of negative
2861 arguments to trigonometric functions.  E.g.,
2862 m4_math(\sin(-x),@code{sin(-x)})
2863 will
2864 become
2865 m4_math(-\sin x, @code{-sin(x)})
2866 only if @code{trigsign} is @code{true}.
2867
2868 @opencatbox{Categories:}
2869 @category{Trigonometric functions}
2870 @category{Simplification flags and variables}
2871 @closecatbox
2872 @end defvr
2873
2874
2875 @node Explicit Simplifications Using Identities, Additional Functions, Options Controlling Simplification, Functions and Variables for Trigonometric
2876 @subsubsection Explicit Simplifications Using Identities
2877 @c NEEDS CLARIFICATION AND EXAMPLES
2878
2879 @c -----------------------------------------------------------------------------
2880 @anchor{trigexpand}
2881 @deffn {Function} trigexpand (@var{expr})
2882
2883 Expands trigonometric and hyperbolic functions of
2884 sums of angles and of multiple angles occurring in @var{expr}.  For best
2885 results, @var{expr} should be expanded.  To enhance user control of
2886 simplification, this function expands only one level at a time,
2887 expanding sums of angles or multiple angles.  To obtain full expansion
2888 into sines and cosines immediately, set the switch @code{trigexpand: true}.
2889
2890 @code{trigexpand} is governed by the following global flags:
2891
2892 @table @asis
2893 @item @mref{trigexpand}
2894 If @code{true} causes expansion of all
2895 expressions containing sin's and cos's occurring subsequently.
2896 @item @mref{halfangles}
2897 If @code{true} causes half-angles to be simplified
2898 away.
2899 @item @mref{trigexpandplus}
2900 Controls the "sum" rule for @code{trigexpand},
2901 expansion of sums (e.g. @code{sin(x + y)}) will take place only if
2902 @code{trigexpandplus} is @code{true}.
2903 @item @mref{trigexpandtimes}
2904 Controls the "product" rule for @code{trigexpand},
2905 expansion of products (e.g. @code{sin(2 x)}) will take place only if
2906 @code{trigexpandtimes} is @code{true}.
2907 @end table
2908
2909 Examples:
2910
2911 @c ===beg===
2912 @c x+sin(3*x)/sin(x),trigexpand=true,expand;
2913 @c trigexpand(sin(10*x+y));
2914 @c ===end===
2915 @example
2916 @group
2917 (%i1) x+sin(3*x)/sin(x),trigexpand=true,expand;
2918                          2           2
2919 (%o1)               - sin (x) + 3 cos (x) + x
2920 @end group
2921 @group
2922 (%i2) trigexpand(sin(10*x+y));
2923 (%o2)          cos(10 x) sin(y) + sin(10 x) cos(y)
2924 @end group
2925 @end example
2926
2927 @opencatbox{Categories:}
2928 @category{Trigonometric functions}
2929 @category{Simplification functions}
2930 @closecatbox
2931 @end deffn
2932
2933 @c -----------------------------------------------------------------------------
2934 @anchor{trigexpandplus}
2935 @defvr {Option variable} trigexpandplus
2936 Default value: @code{true}
2937
2938 @code{trigexpandplus} controls the "sum" rule for
2939 @mref{trigexpand}.  Thus, when the @mref{trigexpand} command is used or the
2940 @mref{trigexpand} switch set to @code{true}, expansion of sums
2941 (e.g. @code{sin(x+y))} will take place only if @code{trigexpandplus} is
2942 @code{true}.
2943
2944 @opencatbox{Categories:}
2945 @category{Trigonometric functions}
2946 @category{Simplification flags and variables}
2947 @closecatbox
2948 @end defvr
2949
2950 @c -----------------------------------------------------------------------------
2951 @anchor{trigexpandtimes}
2952 @defvr {Option variable} trigexpandtimes
2953 Default value: @code{true}
2954
2955 @code{trigexpandtimes} controls the "product" rule for @mref{trigexpand}.
2956 Thus, when the @mref{trigexpand} command is used or the @mref{trigexpand}
2957 switch set to @code{true}, expansion of products (e.g. @code{sin(2*x)})
2958 will take place only if @code{trigexpandtimes} is @code{true}.
2959
2960 @opencatbox{Categories:}
2961 @category{Trigonometric functions}
2962 @category{Simplification flags and variables}
2963 @closecatbox
2964 @end defvr
2965
2966 @c -----------------------------------------------------------------------------
2967 @anchor{triginverses}
2968 @defvr {Option variable} triginverses
2969 Default value: @code{true}
2970
2971 @code{triginverses} controls the simplification of the
2972 composition of trigonometric and hyperbolic functions with their inverse
2973 functions.
2974
2975 If @code{all}, both e.g. @code{atan(tan(@var{x}))}
2976 and @code{tan(atan(@var{x}))} simplify to @var{x}.
2977
2978 If @code{true}, the @code{@var{arcfun}(@var{fun}(@var{x}))}
2979 simplification is turned off.
2980
2981 If @code{false}, both the
2982 @code{@var{arcfun}(@var{fun}(@var{x}))} and
2983 @code{@var{fun}(@var{arcfun}(@var{x}))}
2984 simplifications are turned off.
2985
2986 @opencatbox{Categories:}
2987 @category{Trigonometric functions}
2988 @category{Simplification flags and variables}
2989 @closecatbox
2990 @end defvr
2991
2992 @c -----------------------------------------------------------------------------
2993 @anchor{trigreduce}
2994 @deffn  {Function} trigreduce @
2995 @fname{trigreduce} (@var{expr}, @var{x}) @
2996 @fname{trigreduce} (@var{expr})
2997
2998 Combines products and powers of trigonometric
2999 and hyperbolic sin's and cos's of @var{x} into those of multiples of @var{x}.
3000 It also tries to eliminate these functions when they occur in
3001 denominators.  If @var{x} is omitted then all variables in @var{expr} are used.
3002
3003 See also @mref{poissimp}.
3004
3005 @c ===beg===
3006 @c trigreduce(-sin(x)^2+3*cos(x)^2+x);
3007 @c ===end===
3008 @example
3009 @group
3010 (%i1) trigreduce(-sin(x)^2+3*cos(x)^2+x);
3011                cos(2 x)      cos(2 x)   1        1
3012 (%o1)          -------- + 3 (-------- + -) + x - -
3013                   2             2       2        2
3014 @end group
3015 @end example
3016
3017 @c
3018 @c     OBSOLETE
3019 @c     The behavior was changed in order to avoid calling expand in the core
3020 @c     simplifier (trigi.lisp rev 1.31)
3021 @c     See http://www.math.utexas.edu/pipermail/maxima/2008/010919.html.
3022 @c
3023 @c The trigonometric simplification routines will use declared
3024 @c information in some simple cases.  Declarations about variables are
3025 @c used as follows, e.g.
3026 @c
3027 @c ---beg---
3028 @c declare(j, integer, e, even, o, odd)$
3029 @c sin(x + (e + 1/2)*%pi);
3030 @c sin(x + (o + 1/2)*%pi);
3031 @c ---end---
3032 @c @example
3033 @c (%i1) declare(j, integer, e, even, o, odd)$
3034 @c (%i2) sin(x + (e + 1/2)*%pi);
3035 @c (%o2)                        cos(x)
3036 @c (%i3) sin(x + (o + 1/2)*%pi);
3037 @c (%o3)                       - cos(x)
3038 @c @end example
3039
3040 @opencatbox{Categories:}
3041 @category{Trigonometric functions}
3042 @category{Simplification functions}
3043 @closecatbox
3044 @end deffn
3045
3046 @c -----------------------------------------------------------------------------
3047 @anchor{trigsimp}
3048 @deffn {Function} trigsimp (@var{expr})
3049
3050
3051 Employs the identities
3052 m4_math(<<<\sin\left(x\right)^2 + \cos\left(x\right)^2 = 1>>>,
3053 <<<sin(x)^2+cos(x)^2 = 1>>>)
3054 and
3055 m4_math(<<<\cosh\left(x\right)^2 - \sinh\left(x\right)^2 = 1>>>,
3056 <<<cosh(x)^2-sinh(x)^2 = 1>>>)
3057 to
3058 @c @iftex
3059 @c @tex
3060 @c $\sin\left(x\right)^2 + \cos\left(x\right)^2 = 1$
3061 @c @end tex
3062 @c and
3063 @c @tex
3064 @c $\cosh\left(x\right)^2 - \sinh\left(x\right)^2 = 1$
3065 @c @end tex
3066 simplify expressions containing @code{tan}, @code{sec},
3067 etc., to @code{sin}, @code{cos}, @code{sinh}, @code{cosh}.
3068 @c @end iftex
3069 @c @ifnottex
3070 @c Employs the identities @math{sin(x)^2 + cos(x)^2 = 1} and
3071 @c @math{cosh(x)^2 - sinh(x)^2 = 1} to simplify expressions containing @code{tan},
3072 @c @code{sec}, etc., to @code{sin}, @code{cos}, @code{sinh}, @code{cosh}.
3073 @c @end ifnottex
3074
3075 @mref{trigreduce}, @mref{ratsimp}, and @mref{radcan} may be
3076 able to further simplify the result.
3077
3078 @code{demo ("trgsmp.dem")} displays some examples of @code{trigsimp}.
3079 @c MERGE EXAMPLES INTO THIS ITEM
3080
3081 @opencatbox{Categories:}
3082 @category{Trigonometric functions}
3083 @category{Simplification functions}
3084 @closecatbox
3085 @end deffn
3086
3087 @c NEEDS CLARIFICATION
3088
3089 @c -----------------------------------------------------------------------------
3090 @anchor{trigrat}
3091 @deffn {Function} trigrat (@var{expr})
3092
3093 Gives a canonical simplified quasilinear form of a trigonometrical expression;
3094 @var{expr} is a rational fraction of several @code{sin}, @code{cos} or
3095 @code{tan}, the arguments of them are linear forms in some variables (or
3096 kernels) and @code{%pi/@var{n}} (@var{n} integer) with integer coefficients.
3097 The result is a simplified fraction with numerator and denominator linear in
3098 @code{sin} and @code{cos}.  Thus @code{trigrat} linearize always when it is
3099 possible.
3100
3101 @c ===beg===
3102 @c trigrat(sin(3*a)/sin(a+%pi/3));
3103 @c ===end===
3104 @example
3105 @group
3106 (%i1) trigrat(sin(3*a)/sin(a+%pi/3));
3107 (%o1)            sqrt(3) sin(2 a) + cos(2 a) - 1
3108 @end group
3109 @end example
3110
3111 The following example is taken from
3112 Davenport, Siret, and Tournier, @i{Calcul Formel}, Masson (or in English,
3113 Addison-Wesley), section 1.5.5, Morley theorem.
3114
3115 @c ===beg===
3116 @c c : %pi/3 - a - b$
3117 @c bc : sin(a)*sin(3*c)/sin(a+b);
3118 @c ba : bc, c=a, a=c;
3119 @c ac2 : ba^2 + bc^2 - 2*bc*ba*cos(b);
3120 @c trigrat (ac2);
3121 @c ===end===
3122 @example
3123 (%i1) c : %pi/3 - a - b$
3124 @group
3125 (%i2) bc : sin(a)*sin(3*c)/sin(a+b);
3126                                           %pi
3127                   sin(a) sin(3 (- b - a + ---))
3128                                            3
3129 (%o2)             -----------------------------
3130                            sin(b + a)
3131 @end group
3132 @group
3133 (%i3) ba : bc, c=a, a=c;
3134                                          %pi
3135                     sin(3 a) sin(b + a - ---)
3136                                           3
3137 (%o3)               -------------------------
3138                                   %pi
3139                           sin(a - ---)
3140                                    3
3141 @end group
3142 @group
3143 (%i4) ac2 : ba^2 + bc^2 - 2*bc*ba*cos(b);
3144          2         2         %pi
3145       sin (3 a) sin (b + a - ---)
3146                               3
3147 (%o4) ---------------------------
3148                 2     %pi
3149              sin (a - ---)
3150                        3
3151                                        %pi
3152  - (2 sin(a) sin(3 a) sin(3 (- b - a + ---)) cos(b)
3153                                         3
3154              %pi            %pi
3155  sin(b + a - ---))/(sin(a - ---) sin(b + a))
3156               3              3
3157       2       2              %pi
3158    sin (a) sin (3 (- b - a + ---))
3159                               3
3160  + -------------------------------
3161                 2
3162              sin (b + a)
3163 @end group
3164 @group
3165 (%i5) trigrat (ac2);
3166 (%o5) - (sqrt(3) sin(4 b + 4 a) - cos(4 b + 4 a)
3167  - 2 sqrt(3) sin(4 b + 2 a) + 2 cos(4 b + 2 a)
3168  - 2 sqrt(3) sin(2 b + 4 a) + 2 cos(2 b + 4 a)
3169  + 4 sqrt(3) sin(2 b + 2 a) - 8 cos(2 b + 2 a) - 4 cos(2 b - 2 a)
3170  + sqrt(3) sin(4 b) - cos(4 b) - 2 sqrt(3) sin(2 b) + 10 cos(2 b)
3171  + sqrt(3) sin(4 a) - cos(4 a) - 2 sqrt(3) sin(2 a) + 10 cos(2 a)
3172  - 9)/4
3173 @end group
3174 @end example
3175
3176 @opencatbox{Categories:}
3177 @category{Trigonometric functions}
3178 @category{Simplification functions}
3179 @closecatbox
3180 @end deffn
3181
3182
3183 @node Additional Functions,  , Explicit Simplifications Using Identities, Functions and Variables for Trigonometric
3184 @subsubsection Additional Functions
3185 @c IS THIS DESCRIPTION ACCURATE ??
3186 @c LET'S BE EXPLICIT ABOUT EXACTLY WHAT ARE THE RULES IMPLEMENTED BY THIS PACKAGE
3187
3188 @c -----------------------------------------------------------------------------
3189 @anchor{atrig1}
3190 @defvr {Package} atrig1
3191
3192 The @code{atrig1} package contains several additional simplification rules
3193 for inverse trigonometric functions.  Together with rules
3194 already known to Maxima, the following angles are fully implemented:
3195 @math{0},
3196 m4_mathcomma(\pi/6,%pi/6)
3197 m4_mathcomma(\pi/4,%pi/4)
3198 m4_mathcomma(\pi/3,%pi/3)
3199 and
3200 m4_mathdot(\pi/2,%pi/2)
3201 Corresponding angles in the other three quadrants are also available.
3202 Do @code{load("atrig1");} to use them.
3203
3204 @opencatbox{Categories:}
3205 @category{Trigonometric functions}
3206 @category{Package atrig1}
3207 @closecatbox
3208 @end defvr
3209
3210 @c IS THIS DESCRIPTION ACCURATE ??
3211 @c LET'S BE EXPLICIT ABOUT EXACTLY WHAT ARE THE RULES IMPLEMENTED BY THIS PACKAGE
3212
3213 @c -----------------------------------------------------------------------------
3214 @anchor{ntrig}
3215 @defvr {Package} ntrig
3216
3217 The @code{ntrig} package contains a set of simplification rules that are
3218 used to simplify trigonometric function whose arguments are of the form
3219 @code{@var{f}(@var{n} %pi/10)} where @var{f} is any of the functions
3220 @code{sin}, @code{cos}, @code{tan}, @code{csc}, @code{sec} and @code{cot}.
3221 @c NEED TO LOAD THIS PACKAGE ??
3222
3223 @opencatbox{Categories:}
3224 @category{Trigonometric functions}
3225 @category{Package ntrig}
3226 @closecatbox
3227 @end defvr
3228
3229 @c -----------------------------------------------------------------------------
3230 @page
3231 @node Random Numbers,  , Trigonometric Functions, Elementary Functions
3232 @section Random Numbers
3233 @c -----------------------------------------------------------------------------
3234
3235 @c -----------------------------------------------------------------------------
3236 @anchor{make_random_state}
3237 @deffn  {Function} make_random_state @
3238 @fname{make_random_state} (@var{n}) @
3239 @fname{make_random_state} (@var{s}) @
3240 @fname{make_random_state} (true) @
3241 @fname{make_random_state} (false)
3242
3243 @c OMIT THIS FOR NOW. SEE COMMENT BELOW.
3244 @c @defunx make_random_state (@var{a})
3245
3246 A random state object represents the state of the random number generator.
3247 The state comprises 627 32-bit words.
3248
3249 @code{make_random_state (@var{n})} returns a new random state object
3250 created from an integer seed value equal to @var{n} modulo 2^32.
3251 @var{n} may be negative.
3252
3253 @c OMIT THIS FOR NOW. NOT SURE HOW THIS IS SUPPOSED TO WORK.
3254 @c @code{make_random_state (@var{a})} returns a new random state object
3255 @c created from an array @var{a}, which must be a Lisp array of 32 unsigned bytes.
3256
3257 @code{make_random_state (@var{s})} returns a copy of the random state @var{s}.
3258
3259 @code{make_random_state (true)} returns a new random state object,
3260 using the current computer clock time as the seed.
3261
3262 @code{make_random_state (false)} returns a copy of the current state
3263 of the random number generator.
3264
3265 @opencatbox{Categories:}
3266 @category{Random numbers}
3267 @closecatbox
3268 @end deffn
3269
3270 @c -----------------------------------------------------------------------------
3271 @anchor{set_random_state}
3272 @deffn {Function} set_random_state (@var{s})
3273
3274 Copies @var{s} to the random number generator state.
3275
3276 @code{set_random_state} always returns @code{done}.
3277
3278 @opencatbox{Categories:}
3279 @category{Random numbers}
3280 @closecatbox
3281 @end deffn
3282
3283 @c -----------------------------------------------------------------------------
3284 @anchor{random}
3285 @deffn {Function} random (@var{x})
3286
3287 Returns a pseudorandom number.  If @var{x} is an integer,
3288 @code{random (@var{x})} returns an integer from 0 through @code{@var{x} - 1}
3289 inclusive.  If @var{x} is a floating point number, @code{random (@var{x})}
3290 returns a nonnegative floating point number less than @var{x}.  @code{random}
3291 complains with an error if @var{x} is neither an integer nor a float, or if
3292 @var{x} is not positive.
3293
3294 The functions @code{make_random_state} and @code{set_random_state}
3295 maintain the state of the random number generator.
3296
3297 The Maxima random number generator is an implementation of the Mersenne twister
3298 MT 19937.
3299
3300 Examples:
3301
3302 @c ===beg===
3303 @c s1: make_random_state (654321)$
3304 @c set_random_state (s1);
3305 @c random (1000);
3306 @c random (9573684);
3307 @c random (2^75);
3308 @c s2: make_random_state (false)$
3309 @c random (1.0);
3310 @c random (10.0);
3311 @c random (100.0);
3312 @c set_random_state (s2);
3313 @c random (1.0);
3314 @c random (10.0);
3315 @c random (100.0);
3316 @c ===end===
3317 @example
3318 (%i1) s1: make_random_state (654321)$
3319 @group
3320 (%i2) set_random_state (s1);
3321 (%o2)                         done
3322 @end group
3323 @group
3324 (%i3) random (1000);
3325 (%o3)                          768
3326 @end group
3327 @group
3328 (%i4) random (9573684);
3329 (%o4)                        7657880
3330 @end group
3331 @group
3332 (%i5) random (2^75);
3333 (%o5)                11804491615036831636390
3334 @end group
3335 (%i6) s2: make_random_state (false)$
3336 @group
3337 (%i7) random (1.0);
3338 (%o7)                  0.2310127244107132
3339 @end group
3340 @group
3341 (%i8) random (10.0);
3342 (%o8)                  4.3945536458708245
3343 @end group
3344 @group
3345 (%i9) random (100.0);
3346 (%o9)                   32.28666704056853
3347 @end group
3348 @group
3349 (%i10) set_random_state (s2);
3350 (%o10)                        done
3351 @end group
3352 @group
3353 (%i11) random (1.0);
3354 (%o11)                 0.2310127244107132
3355 @end group
3356 @group
3357 (%i12) random (10.0);
3358 (%o12)                 4.3945536458708245
3359 @end group
3360 @group
3361 (%i13) random (100.0);
3362 (%o13)                  32.28666704056853
3363 @end group
3364 @end example
3365
3366 @opencatbox{Categories:}
3367 @category{Random numbers}
3368 @category{Numerical methods}
3369 @closecatbox
3370 @end deffn
3371