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 Use this to make the same cross-references to variables that
2288 @c control simplification of trig (and hyperbolic) functions.
2289 @macro xreftrigvars{}
2290 For variables that control simplification @pxref{%piargs},
2291 @ref{%iargs}, @ref{halfangles}, @ref{triginverses}, and
2292 @ref{trigsign}.
2293
2294 @end macro
2295 @c -----------------------------------------------------------------------------
2296 @anchor{acos}
2297 @deffn {Function} acos (@var{x})
2298
2299 -- Arc Cosine.
2300
2301 @xreftrigvars{}
2302
2303 @opencatbox{Categories:}
2304 @category{Trigonometric functions}
2305 @closecatbox
2306 @end deffn
2307
2308 @c -----------------------------------------------------------------------------
2309 @anchor{acosh}
2310 @deffn {Function} acosh (@var{x})
2311
2312 -- Hyperbolic Arc Cosine.
2313
2314 @xreftrigvars{}
2315
2316 @opencatbox{Categories:}
2317 @category{Hyperbolic functions}
2318 @closecatbox
2319 @end deffn
2320
2321 @c -----------------------------------------------------------------------------
2322 @anchor{acot}
2323 @deffn {Function} acot (@var{x})
2324
2325 -- Arc Cotangent.
2326
2327 @xreftrigvars{}
2328
2329 @opencatbox{Categories:}
2330 @category{Trigonometric functions}
2331 @closecatbox
2332 @end deffn
2333
2334 @c -----------------------------------------------------------------------------
2335 @anchor{acoth}
2336 @deffn {Function} acoth (@var{x})
2337
2338 -- Hyperbolic Arc Cotangent.
2339
2340 @xreftrigvars{}
2341
2342 @opencatbox{Categories:}
2343 @category{Hyperbolic functions}
2344 @closecatbox
2345 @end deffn
2346
2347 @c -----------------------------------------------------------------------------
2348 @anchor{acsc}
2349 @deffn {Function} acsc (@var{x})
2350
2351 -- Arc Cosecant.
2352
2353 @xreftrigvars{}
2354
2355 @opencatbox{Categories:}
2356 @category{Trigonometric functions}
2357 @closecatbox
2358 @end deffn
2359
2360 @c -----------------------------------------------------------------------------
2361 @anchor{acsch}
2362 @deffn {Function} acsch (@var{x})
2363
2364 -- Hyperbolic Arc Cosecant.
2365
2366 @xreftrigvars{}
2367
2368 @opencatbox{Categories:}
2369 @category{Hyperbolic functions}
2370 @closecatbox
2371 @end deffn
2372
2373 @c -----------------------------------------------------------------------------
2374 @anchor{asec}
2375 @deffn {Function} asec (@var{x})
2376
2377 -- Arc Secant.
2378
2379 @xreftrigvars{}
2380
2381 @opencatbox{Categories:}
2382 @category{Trigonometric functions}
2383 @closecatbox
2384 @end deffn
2385
2386 @c -----------------------------------------------------------------------------
2387 @anchor{asech}
2388 @deffn {Function} asech (@var{x})
2389
2390 -- Hyperbolic Arc Secant.
2391
2392 @xreftrigvars{}
2393
2394 @opencatbox{Categories:}
2395 @category{Hyperbolic functions}
2396 @closecatbox
2397 @end deffn
2398
2399 @c -----------------------------------------------------------------------------
2400 @anchor{asin}
2401 @deffn {Function} asin (@var{x})
2402
2403 -- Arc Sine.
2404
2405 @xreftrigvars{}
2406
2407 @opencatbox{Categories:}
2408 @category{Trigonometric functions}
2409 @closecatbox
2410 @end deffn
2411
2412 @c -----------------------------------------------------------------------------
2413 @anchor{asinh}
2414 @deffn {Function} asinh (@var{x})
2415
2416 -- Hyperbolic Arc Sine.
2417
2418 @xreftrigvars{}
2419
2420 @opencatbox{Categories:}
2421 @category{Hyperbolic functions}
2422 @closecatbox
2423 @end deffn
2424
2425 @c -----------------------------------------------------------------------------
2426 @anchor{atan}
2427 @deffn {Function} atan (@var{x})
2428
2429 -- Arc Tangent.
2430
2431 See also @mref{atan2}.
2432
2433 @xreftrigvars{}
2434
2435 @opencatbox{Categories:}
2436 @category{Trigonometric functions}
2437 @closecatbox
2438 @end deffn
2439
2440 @c -----------------------------------------------------------------------------
2441 @anchor{atan2}
2442 @deffn {Function} atan2 (@var{y}, @var{x})
2443
2444 -- yields the value of
2445 m4_math(<<<\tan^{-1}(y/x)>>>, atan(y/x))
2446 in the interval
2447 m4_math(-\pi, -%pi)
2448 to
2449 m4_math(\pi, %pi)
2450 taking into
2451 consideration the quadrant of the point
2452 m4_mathdot(<<<(x,y)>>>, <<<(x,y)>>>)
2453
2454 Along the branch cut with @math{y = 0} and @math{x < 0}, @code{atan2}
2455 is continuous with the second quadrant.
2456 See also @mref{atan}.
2457
2458 @xreftrigvars{}
2459
2460 @opencatbox{Categories:}
2461 @category{Trigonometric functions}
2462 @closecatbox
2463 @end deffn
2464
2465 @c -----------------------------------------------------------------------------
2466 @anchor{atanh}
2467 @deffn {Function} atanh (@var{x})
2468
2469 -- Hyperbolic Arc Tangent.
2470
2471 @xreftrigvars{}
2472
2473 @opencatbox{Categories:}
2474 @category{Hyperbolic functions}
2475 @closecatbox
2476 @end deffn
2477
2478 @c -----------------------------------------------------------------------------
2479 @anchor{cos}
2480 @deffn {Function} cos (@var{x})
2481
2482 -- Cosine.
2483
2484 @xreftrigvars{}
2485
2486 @opencatbox{Categories:}
2487 @category{Trigonometric functions}
2488 @closecatbox
2489 @end deffn
2490
2491 @c -----------------------------------------------------------------------------
2492 @anchor{cosh}
2493 @deffn {Function} cosh (@var{x})
2494
2495 -- Hyperbolic Cosine.
2496
2497 @xreftrigvars{}
2498
2499 @opencatbox{Categories:}
2500 @category{Hyperbolic functions}
2501 @closecatbox
2502 @end deffn
2503
2504 @c -----------------------------------------------------------------------------
2505 @anchor{cot}
2506 @deffn {Function} cot (@var{x})
2507
2508 -- Cotangent.
2509
2510 @xreftrigvars{}
2511
2512 @opencatbox{Categories:}
2513 @category{Trigonometric functions}
2514 @closecatbox
2515 @end deffn
2516
2517 @c -----------------------------------------------------------------------------
2518 @anchor{coth}
2519 @deffn {Function} coth (@var{x})
2520
2521 -- Hyperbolic Cotangent.
2522
2523 @xreftrigvars{}
2524
2525 @opencatbox{Categories:}
2526 @category{Hyperbolic functions}
2527 @closecatbox
2528 @end deffn
2529
2530 @c -----------------------------------------------------------------------------
2531 @anchor{csc}
2532 @deffn {Function} csc (@var{x})
2533
2534 -- Cosecant.
2535
2536 @xreftrigvars{}
2537
2538 @opencatbox{Categories:}
2539 @category{Trigonometric functions}
2540 @closecatbox
2541 @end deffn
2542
2543 @c -----------------------------------------------------------------------------
2544 @anchor{csch}
2545 @deffn {Function} csch (@var{x})
2546
2547 -- Hyperbolic Cosecant.
2548
2549 @xreftrigvars{}
2550
2551 @opencatbox{Categories:}
2552 @category{Hyperbolic functions}
2553 @closecatbox
2554 @end deffn
2555
2556 @c -----------------------------------------------------------------------------
2557 @anchor{sec}
2558 @deffn {Function} sec (@var{x})
2559
2560 -- Secant.
2561
2562 @xreftrigvars{}
2563
2564 @opencatbox{Categories:}
2565 @category{Trigonometric functions}
2566 @closecatbox
2567 @end deffn
2568
2569 @c -----------------------------------------------------------------------------
2570 @anchor{sech}
2571 @deffn {Function} sech (@var{x})
2572
2573 -- Hyperbolic Secant.
2574
2575 @xreftrigvars{}
2576
2577 @opencatbox{Categories:}
2578 @category{Hyperbolic functions}
2579 @closecatbox
2580 @end deffn
2581
2582 @c -----------------------------------------------------------------------------
2583 @anchor{sin}
2584 @deffn {Function} sin (@var{x})
2585
2586 -- Sine.
2587
2588 @xreftrigvars{}
2589
2590 @opencatbox{Categories:}
2591 @category{Trigonometric functions}
2592 @closecatbox
2593 @end deffn
2594
2595 @c -----------------------------------------------------------------------------
2596 @anchor{sinh}
2597 @deffn {Function} sinh (@var{x})
2598
2599 -- Hyperbolic Sine.
2600
2601 @xreftrigvars{}
2602
2603 @opencatbox{Categories:}
2604 @category{Hyperbolic functions}
2605 @closecatbox
2606 @end deffn
2607
2608 @c -----------------------------------------------------------------------------
2609 @anchor{tan}
2610 @deffn {Function} tan (@var{x})
2611
2612 -- Tangent.
2613
2614 @xreftrigvars{}
2615
2616 @opencatbox{Categories:}
2617 @category{Trigonometric functions}
2618 @closecatbox
2619 @end deffn
2620
2621 @c -----------------------------------------------------------------------------
2622 @anchor{tanh}
2623 @deffn {Function} tanh (@var{x})
2624
2625 -- Hyperbolic Tangent.
2626
2627 @xreftrigvars{}
2628
2629 @opencatbox{Categories:}
2630 @category{Hyperbolic functions}
2631 @closecatbox
2632 @end deffn
2633
2634 @unmacro xreftrigvars
2635
2636 @node Options Controlling Simplification, Explicit Simplifications Using Identities, Trigonometric and Hyperbolic Functions, Functions and Variables for Trigonometric
2637 @subsubsection Options Controlling Simplification
2638 @c -----------------------------------------------------------------------------
2639 @anchor{%piargs}
2640 @defvr {Option variable} %piargs
2641 Default value: @code{true}
2642
2643 When @code{%piargs} is @code{true},
2644 trigonometric functions are simplified to algebraic constants
2645 when the argument is an integer multiple
2646 of
2647 m4_mathcomma(\pi,%pi)
2648 m4_mathcomma(\pi/2,%pi/2)
2649 m4_mathcomma(\pi/4,%pi/4)
2650 or
2651 m4_mathdot(\pi/6,%pi/6)
2652 @c @iftex
2653 @c @math{\pi}, @math{\pi/2}, @math{\pi/3}, @math{\pi/4}, or @math{\pi/6}.
2654 @c @end iftex
2655 @c @ifnottex
2656 @c @math{%pi}, @math{%pi/2}, @math{%pi/3}, @math{%pi/4}, or @math{%pi/6}.
2657 @c @end ifnottex
2658
2659 Maxima knows some identities which can be applied when
2660 m4_mathcomma(\pi,%pi)
2661 etc.,
2662 @c @iftex
2663 @c Maxima knows some identities which can be applied when @math{\pi}, etc.,
2664 @c @end iftex
2665 @c @ifnottex
2666 @c Maxima knows some identities which can be applied when @math{%pi}, etc.,
2667 @c @end ifnottex
2668 are multiplied by an integer variable (that is, a symbol declared to be
2669 integer).
2670
2671 Examples:
2672
2673 @c ===beg===
2674 @c %piargs : false$
2675 @c [sin (%pi), sin (%pi/2), sin (%pi/3)];
2676 @c [sin (%pi/4), sin (%pi/5), sin (%pi/6)];
2677 @c %piargs : true$
2678 @c [sin (%pi), sin (%pi/2), sin (%pi/3)];
2679 @c [sin (%pi/4), sin (%pi/5), sin (%pi/6)];
2680 @c [cos (%pi/3), cos (10*%pi/3), tan (10*%pi/3),
2681 @c        cos (sqrt(2)*%pi/3)];
2682 @c ===end===
2683 @example
2684 (%i1) %piargs : false$
2685 @group
2686 (%i2) [sin (%pi), sin (%pi/2), sin (%pi/3)];
2687                                 %pi       %pi
2688 (%o2)            [sin(%pi), sin(---), sin(---)]
2689                                  2         3
2690 @end group
2691 @group
2692 (%i3) [sin (%pi/4), sin (%pi/5), sin (%pi/6)];
2693                       %pi       %pi       %pi
2694 (%o3)            [sin(---), sin(---), sin(---)]
2695                        4         5         6
2696 @end group
2697 (%i4) %piargs : true$
2698 @group
2699 (%i5) [sin (%pi), sin (%pi/2), sin (%pi/3)];
2700                                 sqrt(3)
2701 (%o5)                    [0, 1, -------]
2702                                    2
2703 @end group
2704 @group
2705 (%i6) [sin (%pi/4), sin (%pi/5), sin (%pi/6)];
2706                          1         %pi   1
2707 (%o6)                [-------, sin(---), -]
2708                       sqrt(2)       5    2
2709 @end group
2710 @group
2711 (%i7) [cos (%pi/3), cos (10*%pi/3), tan (10*%pi/3),
2712        cos (sqrt(2)*%pi/3)];
2713                 1    1               sqrt(2) %pi
2714 (%o7)          [-, - -, sqrt(3), cos(-----------)]
2715                 2    2                    3
2716 @end group
2717 @end example
2718
2719 Some identities are applied when
2720 m4_math(\pi,%pi)
2721 and
2722 m4_math(\pi/2,%pi/2)
2723 are
2724 multiplied by an integer variable.
2725 @c @iftex
2726 @c Some identities are applied when @math{\pi} and @math{\pi/2} are multiplied by
2727 @c an integer variable.
2728 @c @end iftex
2729 @c @ifnottex
2730 @c Some identities are applied when @math{%pi} and @math{%pi/2} are multiplied by
2731 @c an integer variable.
2732 @c @end ifnottex
2733
2734 @c ===beg===
2735 @c declare (n, integer, m, even)$
2736 @c [sin (%pi * n), cos (%pi * m), sin (%pi/2 * m),
2737 @c        cos (%pi/2 * m)];
2738 @c ===end===
2739 @example
2740 (%i1) declare (n, integer, m, even)$
2741 @group
2742 (%i2) [sin (%pi * n), cos (%pi * m), sin (%pi/2 * m),
2743        cos (%pi/2 * m)];
2744                                       m/2
2745 (%o2)                  [0, 1, 0, (- 1)   ]
2746 @end group
2747 @end example
2748
2749 @opencatbox{Categories:}
2750 @category{Trigonometric functions}
2751 @category{Simplification flags and variables}
2752 @closecatbox
2753 @end defvr
2754
2755 @c -----------------------------------------------------------------------------
2756 @anchor{%iargs}
2757 @defvr {Option variable} %iargs
2758 Default value: @code{true}
2759
2760 When @code{%iargs} is @code{true},
2761 trigonometric functions are simplified to hyperbolic functions
2762 when the argument is apparently a multiple of the imaginary
2763 unit
2764 m4_mathdot(i, %i)
2765 @c @iftex
2766 @c when the argument is apparently a multiple of the imaginary unit @math{i}.
2767 @c @end iftex
2768 @c @ifnottex
2769 @c when the argument is apparently a multiple of the imaginary unit @math{%i}.
2770 @c @end ifnottex
2771
2772 Even when the argument is demonstrably real, the simplification is applied;
2773 Maxima considers only whether the argument is a literal multiple
2774 of
2775 m4_mathdot(i,%i)
2776 @c @iftex
2777 @c Maxima considers only whether the argument is a literal multiple of @math{i}.
2778 @c @end iftex
2779 @c @ifnottex
2780 @c Maxima considers only whether the argument is a literal multiple of @math{%i}.
2781 @c @end ifnottex
2782
2783 Examples:
2784
2785 @c ===beg===
2786 @c %iargs : false$
2787 @c [sin (%i * x), cos (%i * x), tan (%i * x)];
2788 @c %iargs : true$
2789 @c [sin (%i * x), cos (%i * x), tan (%i * x)];
2790 @c ===end===
2791 @example
2792 (%i1) %iargs : false$
2793 @group
2794 (%i2) [sin (%i * x), cos (%i * x), tan (%i * x)];
2795 (%o2)           [sin(%i x), cos(%i x), tan(%i x)]
2796 @end group
2797 (%i3) %iargs : true$
2798 @group
2799 (%i4) [sin (%i * x), cos (%i * x), tan (%i * x)];
2800 (%o4)           [%i sinh(x), cosh(x), %i tanh(x)]
2801 @end group
2802 @end example
2803
2804 Even when the argument is demonstrably real, the simplification is applied.
2805
2806 @c ===beg===
2807 @c declare (x, imaginary)$
2808 @c [featurep (x, imaginary), featurep (x, real)];
2809 @c sin (%i * x);
2810 @c ===end===
2811 @example
2812 (%i1) declare (x, imaginary)$
2813 @group
2814 (%i2) [featurep (x, imaginary), featurep (x, real)];
2815 (%o2)                     [true, false]
2816 @end group
2817 @group
2818 (%i3) sin (%i * x);
2819 (%o3)                      %i sinh(x)
2820 @end group
2821 @end example
2822
2823 @opencatbox{Categories:}
2824 @category{Trigonometric functions}
2825 @category{Hyperbolic functions}
2826 @category{Simplification flags and variables}
2827 @closecatbox
2828 @end defvr
2829
2830 @c -----------------------------------------------------------------------------
2831 @anchor{halfangles}
2832 @defvr {Option variable} halfangles
2833 Default value: @code{false}
2834
2835 When @code{halfangles} is @code{true}, trigonometric functions of arguments
2836 @code{@var{expr}/2} are simplified to functions of @var{expr}.
2837
2838 For a real argument @math{x} in the interval
2839 m4_mathcomma(<<<0 \le x < 2\pi>>>, 0 <= x < 2*%pi)
2840 m4_math(<<<\sin{x\over 2}>>>, sin(x/2))
2841 simplifies to a simple formula:
2842 m4_displaymath(
2843 {\sqrt{1-\cos x}\over\sqrt{2}},
2844 @example
2845                          sqrt(1 - cos(x))
2846                          ----------------
2847                              sqrt(2)
2848 @end example
2849 )
2850
2851 A complicated factor is needed to make this formula correct for all complex
2852 arguments @math{z = x+iy}:
2853 m4_displaymath(
2854 (-1)^{\lfloor{x/(2\pi)}\rfloor}
2855 \left[1-\rm{unit\_step}(-y)
2856 \left(1+(-1)^{\lfloor{x/(2\pi)}\rfloor - \lceil{x/(2\pi)}\rceil}\right)\right]
2857 ,
2858 <<<@verbatim
2859               x                       x                x
2860       floor(-----)            floor(-----) - ceiling(-----)
2861             2 %pi                   2 %pi            2 %pi
2862  (- 1)             (1 - ((- 1)                              + 1)
2863                                                           unit_step(- y))
2864 @end verbatim
2865 >>>)
2866
2867 Maxima knows this factor and similar factors for the functions @code{sin},
2868 @code{cos}, @code{sinh}, and @code{cosh}.  For special values of the argument
2869 @math{z} these factors simplify accordingly.
2870
2871 Examples:
2872
2873 @c ===beg===
2874 @c halfangles : false$
2875 @c sin (x / 2);
2876 @c halfangles : true$
2877 @c sin (x / 2);
2878 @c assume(x>0, x<2*%pi)$
2879 @c sin(x / 2);
2880 @c ===end===
2881 @example
2882 (%i1) halfangles : false$
2883 @group
2884 (%i2) sin (x / 2);
2885                                  x
2886 (%o2)                        sin(-)
2887                                  2
2888 @end group
2889 (%i3) halfangles : true$
2890 @group
2891 (%i4) sin (x / 2);
2892                             x
2893                     floor(-----)
2894                           2 %pi
2895                (- 1)             sqrt(1 - cos(x))
2896 (%o4)          ----------------------------------
2897                             sqrt(2)
2898 @end group
2899 (%i5) assume(x>0, x<2*%pi)$
2900 @group
2901 (%i6) sin(x / 2);
2902                         sqrt(1 - cos(x))
2903 (%o6)                   ----------------
2904                             sqrt(2)
2905 @end group
2906 @end example
2907
2908 @opencatbox{Categories:}
2909 @category{Trigonometric functions}
2910 @category{Simplification flags and variables}
2911 @closecatbox
2912 @end defvr
2913
2914 @c -----------------------------------------------------------------------------
2915 @anchor{trigsign}
2916 @defvr {Option variable} trigsign
2917 Default value: @code{true}
2918
2919 When @code{trigsign} is @code{true}, it permits simplification of negative
2920 arguments to trigonometric functions.  E.g.,
2921 m4_math(\sin(-x),@code{sin(-x)})
2922 will
2923 become
2924 m4_math(-\sin x, @code{-sin(x)})
2925 only if @code{trigsign} is @code{true}.
2926
2927 @opencatbox{Categories:}
2928 @category{Trigonometric functions}
2929 @category{Simplification flags and variables}
2930 @closecatbox
2931 @end defvr
2932
2933
2934 @node Explicit Simplifications Using Identities, Additional Functions, Options Controlling Simplification, Functions and Variables for Trigonometric
2935 @subsubsection Explicit Simplifications Using Identities
2936 @c NEEDS CLARIFICATION AND EXAMPLES
2937
2938 @c -----------------------------------------------------------------------------
2939 @anchor{trigexpand}
2940 @deffn {Function} trigexpand (@var{expr})
2941
2942 Expands trigonometric and hyperbolic functions of
2943 sums of angles and of multiple angles occurring in @var{expr}.  For best
2944 results, @var{expr} should be expanded.  To enhance user control of
2945 simplification, this function expands only one level at a time,
2946 expanding sums of angles or multiple angles.  To obtain full expansion
2947 into sines and cosines immediately, set the switch @code{trigexpand: true}.
2948
2949 @code{trigexpand} is governed by the following global flags:
2950
2951 @table @asis
2952 @item @mref{trigexpand}
2953 If @code{true} causes expansion of all
2954 expressions containing sin's and cos's occurring subsequently.
2955 @item @mref{halfangles}
2956 If @code{true} causes half-angles to be simplified
2957 away.
2958 @item @mref{trigexpandplus}
2959 Controls the "sum" rule for @code{trigexpand},
2960 expansion of sums (e.g. @code{sin(x + y)}) will take place only if
2961 @code{trigexpandplus} is @code{true}.
2962 @item @mref{trigexpandtimes}
2963 Controls the "product" rule for @code{trigexpand},
2964 expansion of products (e.g. @code{sin(2 x)}) will take place only if
2965 @code{trigexpandtimes} is @code{true}.
2966 @end table
2967
2968 Examples:
2969
2970 @c ===beg===
2971 @c x+sin(3*x)/sin(x),trigexpand=true,expand;
2972 @c trigexpand(sin(10*x+y));
2973 @c ===end===
2974 @example
2975 @group
2976 (%i1) x+sin(3*x)/sin(x),trigexpand=true,expand;
2977                          2           2
2978 (%o1)               - sin (x) + 3 cos (x) + x
2979 @end group
2980 @group
2981 (%i2) trigexpand(sin(10*x+y));
2982 (%o2)          cos(10 x) sin(y) + sin(10 x) cos(y)
2983 @end group
2984 @end example
2985
2986 @opencatbox{Categories:}
2987 @category{Trigonometric functions}
2988 @category{Simplification functions}
2989 @closecatbox
2990 @end deffn
2991
2992 @c -----------------------------------------------------------------------------
2993 @anchor{trigexpandplus}
2994 @defvr {Option variable} trigexpandplus
2995 Default value: @code{true}
2996
2997 @code{trigexpandplus} controls the "sum" rule for
2998 @mref{trigexpand}.  Thus, when the @mref{trigexpand} command is used or the
2999 @mref{trigexpand} switch set to @code{true}, expansion of sums
3000 (e.g. @code{sin(x+y))} will take place only if @code{trigexpandplus} is
3001 @code{true}.
3002
3003 @opencatbox{Categories:}
3004 @category{Trigonometric functions}
3005 @category{Simplification flags and variables}
3006 @closecatbox
3007 @end defvr
3008
3009 @c -----------------------------------------------------------------------------
3010 @anchor{trigexpandtimes}
3011 @defvr {Option variable} trigexpandtimes
3012 Default value: @code{true}
3013
3014 @code{trigexpandtimes} controls the "product" rule for @mref{trigexpand}.
3015 Thus, when the @mref{trigexpand} command is used or the @mref{trigexpand}
3016 switch set to @code{true}, expansion of products (e.g. @code{sin(2*x)})
3017 will take place only if @code{trigexpandtimes} is @code{true}.
3018
3019 @opencatbox{Categories:}
3020 @category{Trigonometric functions}
3021 @category{Simplification flags and variables}
3022 @closecatbox
3023 @end defvr
3024
3025 @c -----------------------------------------------------------------------------
3026 @anchor{triginverses}
3027 @defvr {Option variable} triginverses
3028 Default value: @code{true}
3029
3030 @code{triginverses} controls the simplification of the
3031 composition of trigonometric and hyperbolic functions with their inverse
3032 functions.
3033
3034 If @code{all}, both e.g. @code{atan(tan(@var{x}))}
3035 and @code{tan(atan(@var{x}))} simplify to @var{x}.
3036
3037 If @code{true}, the @code{@var{arcfun}(@var{fun}(@var{x}))}
3038 simplification is turned off.
3039
3040 If @code{false}, both the
3041 @code{@var{arcfun}(@var{fun}(@var{x}))} and
3042 @code{@var{fun}(@var{arcfun}(@var{x}))}
3043 simplifications are turned off.
3044
3045 @opencatbox{Categories:}
3046 @category{Trigonometric functions}
3047 @category{Simplification flags and variables}
3048 @closecatbox
3049 @end defvr
3050
3051 @c -----------------------------------------------------------------------------
3052 @anchor{trigreduce}
3053 @deffn  {Function} trigreduce @
3054 @fname{trigreduce} (@var{expr}, @var{x}) @
3055 @fname{trigreduce} (@var{expr})
3056
3057 Combines products and powers of trigonometric
3058 and hyperbolic sin's and cos's of @var{x} into those of multiples of @var{x}.
3059 It also tries to eliminate these functions when they occur in
3060 denominators.  If @var{x} is omitted then all variables in @var{expr} are used.
3061
3062 See also @mref{poissimp}.
3063
3064 @c ===beg===
3065 @c trigreduce(-sin(x)^2+3*cos(x)^2+x);
3066 @c ===end===
3067 @example
3068 @group
3069 (%i1) trigreduce(-sin(x)^2+3*cos(x)^2+x);
3070                cos(2 x)      cos(2 x)   1        1
3071 (%o1)          -------- + 3 (-------- + -) + x - -
3072                   2             2       2        2
3073 @end group
3074 @end example
3075
3076 @c
3077 @c     OBSOLETE
3078 @c     The behavior was changed in order to avoid calling expand in the core
3079 @c     simplifier (trigi.lisp rev 1.31)
3080 @c     See http://www.math.utexas.edu/pipermail/maxima/2008/010919.html.
3081 @c
3082 @c The trigonometric simplification routines will use declared
3083 @c information in some simple cases.  Declarations about variables are
3084 @c used as follows, e.g.
3085 @c
3086 @c ---beg---
3087 @c declare(j, integer, e, even, o, odd)$
3088 @c sin(x + (e + 1/2)*%pi);
3089 @c sin(x + (o + 1/2)*%pi);
3090 @c ---end---
3091 @c @example
3092 @c (%i1) declare(j, integer, e, even, o, odd)$
3093 @c (%i2) sin(x + (e + 1/2)*%pi);
3094 @c (%o2)                        cos(x)
3095 @c (%i3) sin(x + (o + 1/2)*%pi);
3096 @c (%o3)                       - cos(x)
3097 @c @end example
3098
3099 @opencatbox{Categories:}
3100 @category{Trigonometric functions}
3101 @category{Simplification functions}
3102 @closecatbox
3103 @end deffn
3104
3105 @c -----------------------------------------------------------------------------
3106 @anchor{trigsimp}
3107 @deffn {Function} trigsimp (@var{expr})
3108
3109
3110 Employs the identities
3111 m4_math(<<<\sin\left(x\right)^2 + \cos\left(x\right)^2 = 1>>>,
3112 <<<sin(x)^2+cos(x)^2 = 1>>>)
3113 and
3114 m4_math(<<<\cosh\left(x\right)^2 - \sinh\left(x\right)^2 = 1>>>,
3115 <<<cosh(x)^2-sinh(x)^2 = 1>>>)
3116 to
3117 @c @iftex
3118 @c @tex
3119 @c $\sin\left(x\right)^2 + \cos\left(x\right)^2 = 1$
3120 @c @end tex
3121 @c and
3122 @c @tex
3123 @c $\cosh\left(x\right)^2 - \sinh\left(x\right)^2 = 1$
3124 @c @end tex
3125 simplify expressions containing @code{tan}, @code{sec},
3126 etc., to @code{sin}, @code{cos}, @code{sinh}, @code{cosh}.
3127 @c @end iftex
3128 @c @ifnottex
3129 @c Employs the identities @math{sin(x)^2 + cos(x)^2 = 1} and
3130 @c @math{cosh(x)^2 - sinh(x)^2 = 1} to simplify expressions containing @code{tan},
3131 @c @code{sec}, etc., to @code{sin}, @code{cos}, @code{sinh}, @code{cosh}.
3132 @c @end ifnottex
3133
3134 @mref{trigreduce}, @mref{ratsimp}, and @mref{radcan} may be
3135 able to further simplify the result.
3136
3137 @code{demo ("trgsmp.dem")} displays some examples of @code{trigsimp}.
3138 @c MERGE EXAMPLES INTO THIS ITEM
3139
3140 @opencatbox{Categories:}
3141 @category{Trigonometric functions}
3142 @category{Simplification functions}
3143 @closecatbox
3144 @end deffn
3145
3146 @c NEEDS CLARIFICATION
3147
3148 @c -----------------------------------------------------------------------------
3149 @anchor{trigrat}
3150 @deffn {Function} trigrat (@var{expr})
3151
3152 Gives a canonical simplified quasilinear form of a trigonometrical expression;
3153 @var{expr} is a rational fraction of several @code{sin}, @code{cos} or
3154 @code{tan}, the arguments of them are linear forms in some variables (or
3155 kernels) and @code{%pi/@var{n}} (@var{n} integer) with integer coefficients.
3156 The result is a simplified fraction with numerator and denominator linear in
3157 @code{sin} and @code{cos}.  Thus @code{trigrat} linearize always when it is
3158 possible.
3159
3160 @c ===beg===
3161 @c trigrat(sin(3*a)/sin(a+%pi/3));
3162 @c ===end===
3163 @example
3164 @group
3165 (%i1) trigrat(sin(3*a)/sin(a+%pi/3));
3166 (%o1)            sqrt(3) sin(2 a) + cos(2 a) - 1
3167 @end group
3168 @end example
3169
3170 The following example is taken from
3171 Davenport, Siret, and Tournier, @i{Calcul Formel}, Masson (or in English,
3172 Addison-Wesley), section 1.5.5, Morley theorem.
3173
3174 @c ===beg===
3175 @c c : %pi/3 - a - b$
3176 @c bc : sin(a)*sin(3*c)/sin(a+b);
3177 @c ba : bc, c=a, a=c;
3178 @c ac2 : ba^2 + bc^2 - 2*bc*ba*cos(b);
3179 @c trigrat (ac2);
3180 @c ===end===
3181 @example
3182 (%i1) c : %pi/3 - a - b$
3183 @group
3184 (%i2) bc : sin(a)*sin(3*c)/sin(a+b);
3185                                           %pi
3186                   sin(a) sin(3 (- b - a + ---))
3187                                            3
3188 (%o2)             -----------------------------
3189                            sin(b + a)
3190 @end group
3191 @group
3192 (%i3) ba : bc, c=a, a=c;
3193                                          %pi
3194                     sin(3 a) sin(b + a - ---)
3195                                           3
3196 (%o3)               -------------------------
3197                                   %pi
3198                           sin(a - ---)
3199                                    3
3200 @end group
3201 @group
3202 (%i4) ac2 : ba^2 + bc^2 - 2*bc*ba*cos(b);
3203          2         2         %pi
3204       sin (3 a) sin (b + a - ---)
3205                               3
3206 (%o4) ---------------------------
3207                 2     %pi
3208              sin (a - ---)
3209                        3
3210                                        %pi
3211  - (2 sin(a) sin(3 a) sin(3 (- b - a + ---)) cos(b)
3212                                         3
3213              %pi            %pi
3214  sin(b + a - ---))/(sin(a - ---) sin(b + a))
3215               3              3
3216       2       2              %pi
3217    sin (a) sin (3 (- b - a + ---))
3218                               3
3219  + -------------------------------
3220                 2
3221              sin (b + a)
3222 @end group
3223 @group
3224 (%i5) trigrat (ac2);
3225 (%o5) - (sqrt(3) sin(4 b + 4 a) - cos(4 b + 4 a)
3226  - 2 sqrt(3) sin(4 b + 2 a) + 2 cos(4 b + 2 a)
3227  - 2 sqrt(3) sin(2 b + 4 a) + 2 cos(2 b + 4 a)
3228  + 4 sqrt(3) sin(2 b + 2 a) - 8 cos(2 b + 2 a) - 4 cos(2 b - 2 a)
3229  + sqrt(3) sin(4 b) - cos(4 b) - 2 sqrt(3) sin(2 b) + 10 cos(2 b)
3230  + sqrt(3) sin(4 a) - cos(4 a) - 2 sqrt(3) sin(2 a) + 10 cos(2 a)
3231  - 9)/4
3232 @end group
3233 @end example
3234
3235 @opencatbox{Categories:}
3236 @category{Trigonometric functions}
3237 @category{Simplification functions}
3238 @closecatbox
3239 @end deffn
3240
3241
3242 @node Additional Functions,  , Explicit Simplifications Using Identities, Functions and Variables for Trigonometric
3243 @subsubsection Additional Functions
3244 @c IS THIS DESCRIPTION ACCURATE ??
3245 @c LET'S BE EXPLICIT ABOUT EXACTLY WHAT ARE THE RULES IMPLEMENTED BY THIS PACKAGE
3246
3247 @c -----------------------------------------------------------------------------
3248 @anchor{atrig1}
3249 @defvr {Package} atrig1
3250
3251 The @code{atrig1} package contains several additional simplification rules
3252 for inverse trigonometric functions.  Together with rules
3253 already known to Maxima, the following angles are fully implemented:
3254 @math{0},
3255 m4_mathcomma(\pi/6,%pi/6)
3256 m4_mathcomma(\pi/4,%pi/4)
3257 m4_mathcomma(\pi/3,%pi/3)
3258 and
3259 m4_mathdot(\pi/2,%pi/2)
3260 Corresponding angles in the other three quadrants are also available.
3261 Do @code{load("atrig1");} to use them.
3262
3263 @opencatbox{Categories:}
3264 @category{Trigonometric functions}
3265 @category{Package atrig1}
3266 @closecatbox
3267 @end defvr
3268
3269 @c IS THIS DESCRIPTION ACCURATE ??
3270 @c LET'S BE EXPLICIT ABOUT EXACTLY WHAT ARE THE RULES IMPLEMENTED BY THIS PACKAGE
3271
3272 @c -----------------------------------------------------------------------------
3273 @anchor{ntrig}
3274 @defvr {Package} ntrig
3275
3276 The @code{ntrig} package contains a set of simplification rules that are
3277 used to simplify trigonometric function whose arguments are of the form
3278 @code{@var{f}(@var{n} %pi/10)} where @var{f} is any of the functions
3279 @code{sin}, @code{cos}, @code{tan}, @code{csc}, @code{sec} and @code{cot}.
3280 @c NEED TO LOAD THIS PACKAGE ??
3281
3282 @opencatbox{Categories:}
3283 @category{Trigonometric functions}
3284 @category{Package ntrig}
3285 @closecatbox
3286 @end defvr
3287
3288 @c -----------------------------------------------------------------------------
3289 @page
3290 @node Random Numbers,  , Trigonometric Functions, Elementary Functions
3291 @section Random Numbers
3292 @c -----------------------------------------------------------------------------
3293
3294 @c -----------------------------------------------------------------------------
3295 @anchor{make_random_state}
3296 @deffn  {Function} make_random_state @
3297 @fname{make_random_state} (@var{n}) @
3298 @fname{make_random_state} (@var{s}) @
3299 @fname{make_random_state} (true) @
3300 @fname{make_random_state} (false)
3301
3302 @c OMIT THIS FOR NOW. SEE COMMENT BELOW.
3303 @c @defunx make_random_state (@var{a})
3304
3305 A random state object represents the state of the random number generator.
3306 The state comprises 627 32-bit words.
3307
3308 @code{make_random_state (@var{n})} returns a new random state object
3309 created from an integer seed value equal to @var{n} modulo 2^32.
3310 @var{n} may be negative.
3311
3312 @c OMIT THIS FOR NOW. NOT SURE HOW THIS IS SUPPOSED TO WORK.
3313 @c @code{make_random_state (@var{a})} returns a new random state object
3314 @c created from an array @var{a}, which must be a Lisp array of 32 unsigned bytes.
3315
3316 @code{make_random_state (@var{s})} returns a copy of the random state @var{s}.
3317
3318 @code{make_random_state (true)} returns a new random state object,
3319 using the current computer clock time as the seed.
3320
3321 @code{make_random_state (false)} returns a copy of the current state
3322 of the random number generator.
3323
3324 @opencatbox{Categories:}
3325 @category{Random numbers}
3326 @closecatbox
3327 @end deffn
3328
3329 @c -----------------------------------------------------------------------------
3330 @anchor{set_random_state}
3331 @deffn {Function} set_random_state (@var{s})
3332
3333 Copies @var{s} to the random number generator state.
3334
3335 @code{set_random_state} always returns @code{done}.
3336
3337 @opencatbox{Categories:}
3338 @category{Random numbers}
3339 @closecatbox
3340 @end deffn
3341
3342 @c -----------------------------------------------------------------------------
3343 @anchor{random}
3344 @deffn {Function} random (@var{x})
3345
3346 Returns a pseudorandom number.  If @var{x} is an integer,
3347 @code{random (@var{x})} returns an integer from 0 through @code{@var{x} - 1}
3348 inclusive.  If @var{x} is a floating point number, @code{random (@var{x})}
3349 returns a nonnegative floating point number less than @var{x}.  @code{random}
3350 complains with an error if @var{x} is neither an integer nor a float, or if
3351 @var{x} is not positive.
3352
3353 The functions @code{make_random_state} and @code{set_random_state}
3354 maintain the state of the random number generator.
3355
3356 The Maxima random number generator is an implementation of the Mersenne twister
3357 MT 19937.
3358
3359 Examples:
3360
3361 @c ===beg===
3362 @c s1: make_random_state (654321)$
3363 @c set_random_state (s1);
3364 @c random (1000);
3365 @c random (9573684);
3366 @c random (2^75);
3367 @c s2: make_random_state (false)$
3368 @c random (1.0);
3369 @c random (10.0);
3370 @c random (100.0);
3371 @c set_random_state (s2);
3372 @c random (1.0);
3373 @c random (10.0);
3374 @c random (100.0);
3375 @c ===end===
3376 @example
3377 (%i1) s1: make_random_state (654321)$
3378 @group
3379 (%i2) set_random_state (s1);
3380 (%o2)                         done
3381 @end group
3382 @group
3383 (%i3) random (1000);
3384 (%o3)                          768
3385 @end group
3386 @group
3387 (%i4) random (9573684);
3388 (%o4)                        7657880
3389 @end group
3390 @group
3391 (%i5) random (2^75);
3392 (%o5)                11804491615036831636390
3393 @end group
3394 (%i6) s2: make_random_state (false)$
3395 @group
3396 (%i7) random (1.0);
3397 (%o7)                  0.2310127244107132
3398 @end group
3399 @group
3400 (%i8) random (10.0);
3401 (%o8)                  4.3945536458708245
3402 @end group
3403 @group
3404 (%i9) random (100.0);
3405 (%o9)                   32.28666704056853
3406 @end group
3407 @group
3408 (%i10) set_random_state (s2);
3409 (%o10)                        done
3410 @end group
3411 @group
3412 (%i11) random (1.0);
3413 (%o11)                 0.2310127244107132
3414 @end group
3415 @group
3416 (%i12) random (10.0);
3417 (%o12)                 4.3945536458708245
3418 @end group
3419 @group
3420 (%i13) random (100.0);
3421 (%o13)                  32.28666704056853
3422 @end group
3423 @end example
3424
3425 @opencatbox{Categories:}
3426 @category{Random numbers}
3427 @category{Numerical methods}
3428 @closecatbox
3429 @end deffn
3430