Arithmetic
**********

Unless otherwise noted, all of the functions described in this chapter will work for real and complex scalar or matrix arguments.

Utility Functions
=================

The following functions are available for working with complex numbers. Each expects a single argument.  They are called mapping functions because when given a matrix argument, they apply the given function to each element of the matrix.

 -- Mapping Function: ceil (X)
     Return the smallest integer not less than X.  If X is complex, return ceil (real (X)) + ceil (imag (X)) * I.

 -- Mapping Function: exp (X)
     Compute the exponential of X.  To compute the matrix exponential, see Linear Algebra.

 -- Mapping Function: fix (X)
     Truncate X toward zero.  If X is complex, return fix (real (X)) + fix (imag (X)) * I.

 -- Mapping Function: floor (X)
     Return the largest integer not greater than X.  If X is complex, return floor (real (X)) + floor (imag (X)) * I.

 -- Mapping Function: gcd (X, ...)
     Compute the greatest common divisor of the elements of X, or the list of all the arguments.  For example,

          gcd (a1, ..., ak)

     is the same as

          gcd ([a1, ..., ak])

     An optional second return value, V contains an integer vector such that

          g = v(1) * a(k) + ... + v(k) * a(k)

 -- Mapping Function: lcm (X, ...)
     Compute the least common multiple of the elements elements of X, or the list of all the arguments.  For example,

          lcm (a1, ..., ak)

     is the same as

          lcm ([a1, ..., ak]).

 -- Mapping Function: log (X)
     Compute the natural logarithm of X.  To compute the matrix logarithm, see Linear Algebra.

 -- Mapping Function: log10 (X)
     Compute the base-10 logarithm of X.

 -- Mapping Function: Y = log2 (X)
 -- Mapping Function: [F, E] log2 (X)
     Compute the base-2 logarithm of X.  With two outputs, returns F and E such that 1/2 <= abs(f) < 1 and x = f * 2^e.

 -- Loadable Function: max (X)
     For a vector argument, return the maximum value.  For a matrix argument, return the maximum value from each column, as a row vector.  Thus,

          max (max (X))

     returns the largest element of X.

     For complex arguments, the magnitude of the elements are used for comparison.

 -- Loadable Function: min (X)
     Like max, but return the minimum value.

 -- Function File: nextpow2 (X)
     If X is a scalar, returns the first integer N such that 2^n >= abs (x).

     If X is a vector, return nextpow2 (length (X)).

 -- Mapping Function: pow2 (X)
 -- Mapping Function: pow2 (F, E)
     With one argument, computes 2 .^ x for each element of X.  With two arguments, returns f .* (2 .^ e).

 -- Mapping Function: rem (X, Y)
     Return the remainder of X / Y, computed using the expression

          x - y .* fix (x ./ y)

     An error message is printed if the dimensions of the arguments do not agree, or if either of the arguments is complex.

 -- Mapping Function: round (X)
     Return the integer nearest to X.  If X is complex, return round (real (X)) + round (imag (X)) * I.

 -- Mapping Function: sign (X)
     Compute the signum function, which is defined as

                     -1, x < 0;
          sign (x) =  0, x = 0;
                      1, x > 0.

     For complex arguments, sign returns x ./ abs (X).

 -- Mapping Function: sqrt (X)
     Compute the square root of X.  If X is negative, a complex result is returned.  To compute the matrix square root, see Linear Algebra.

 -- Mapping Function: xor (X, Y)
     Return the `exclusive or' of the entries of X and Y. For boolean expressions X and Y, xor (X, Y) is true if and only if X or Y is true, but not if both X and Y are true.

Complex Arithmetic
==================

The following functions are available for working with complex numbers.  Each expects a single argument.  Given a matrix they work on an element by element basis.  In the descriptions of the following functions, Z is the complex number X + IY, where I is defined as sqrt (-1).

 -- Mapping Function: abs (Z)
     Compute the magnitude of Z, defined as |Z| = sqrt (x^2 + y^2).

     For example,

          abs (3 + 4i)
               => 5

 -- Mapping Function: arg (Z)
 -- Mapping Function: angle (Z)
     Compute the argument of Z, defined as THETA = atan (Y/X).

     in radians.

     For example,

          arg (3 + 4i)
               => 0.92730

 -- Mapping Function: conj (Z)
     Return the complex conjugate of Z, defined as conj (Z) = X - IY.

 -- Mapping Function: imag (Z)
     Return the imaginary part of Z as a real number.

 -- Mapping Function: real (Z)
     Return the real part of Z.

Trigonometry
============

Octave provides the following trigonometric functions:

 -- Mapping Function: sin (Z)
 -- Mapping Function: cos (Z)
 -- Mapping Function: tan (Z)
 -- Mapping Function: sec (Z)
 -- Mapping Function: csc (Z)
 -- Mapping Function: cot (Z)
     The ordinary trigonometric functions.

 -- Mapping Function: asin (Z)
 -- Mapping Function: acos (Z)
 -- Mapping Function: atan (Z)
 -- Mapping Function: asec (Z)
 -- Mapping Function: acsc (Z)
 -- Mapping Function: acot (Z)
     The ordinary inverse trigonometric functions.

 -- Mapping Function: sinh (Z)
 -- Mapping Function: cosh (Z)
 -- Mapping Function: tanh (Z)
 -- Mapping Function: sech (Z)
 -- Mapping Function: csch (Z)
 -- Mapping Function: coth (Z)
     Hyperbolic trigonometric functions.

 -- Mapping Function: asinh (Z)
 -- Mapping Function: acosh (Z)
 -- Mapping Function: atanh (Z)
 -- Mapping Function: asech (Z)
 -- Mapping Function: acsch (Z)
 -- Mapping Function: acoth (Z)
     Inverse hyperbolic trigonometric functions.

Each of these functions expect a single argument.  For matrix arguments, they work on an element by element basis.  For example,

     sin ([1, 2; 3, 4])
          =>  0.84147   0.90930
              0.14112  -0.75680

 -- Mapping Function: atan2 (Y, X)
     Return the arctangent of Y/X.  The signs of the arguments are used to determine the quadrant of the result, which is in the range pi to -pi.

Sums and Products
=================

 -- Built-in Function: sum (X)
     For a vector argument, return the sum of all the elements.  For a matrix argument, return the sum of the elements in each column, as a row vector.  The sum of an empty matrix is 0 if it has no columns, or a vector of zeros if it has no rows (see Empty Matrices).

 -- Built-in Function: prod (X)
     For a vector argument, return the product of all the elements.  For a matrix argument, return the product of the elements in each column, as a row vector.  The product of an empty matrix is 1 if it has no columns, or a vector of ones if it has no rows (see Empty Matrices).

 -- Built-in Function: cumsum (X)
     Return the cumulative sum of each column of X.  For example,

          cumsum ([1, 2; 3, 4])
               =>  1  2
                   4  6

 -- Built-in Function: cumprod (X)
     Return the cumulative product of each column of X.  For example,

          cumprod ([1, 2; 3, 4])
               =>  1  2
                   3  8

 -- Built-in Function: sumsq (X)
     For a vector argument, return the sum of the squares of all the elements.  For a matrix argument, return the sum of the squares of the elements in each column, as a row vector.

Special Functions
=================

 -- Mapping Function: besseli (ALPHA, X)
 -- Mapping Function: besselj (ALPHA, X)
 -- Mapping Function: besselk (ALPHA, X)
 -- Mapping Function: bessely (ALPHA, X)
     Compute Bessel functions of the following types:

     besselj
          Bessel functions of the first kind.

     bessely
          Bessel functions of the second kind.

     besseli
          Modified Bessel functions of the first kind.

     besselk
          Modified Bessel functions of the second kind.

     The second argument, X, must be a real matrix, vector, or scalar.

     The first argument, ALPHA, must be greater than or equal to zero. If ALPHA is a range, it must have an increment equal to one.

     If ALPHA is a scalar, the result is the same size as X.

     If ALPHA is a range, X must be a vector or scalar, and the result is a matrix with length(X) rows and length(ALPHA) columns.

 -- Mapping Function: beta (A, B)
     Return the Beta function,

          beta (a, b) = gamma (a) * gamma (b) / gamma (a + b).

 -- Mapping Function: betai (A, B, X)
     Return the incomplete Beta function,

                                              x
                                             /
          betai (a, b, x) = beta (a, b)^(-1) | t^(a-1) (1-t)^(b-1) dt.
                                             /
                                          t=0

     If x has more than one component, both A and B must be scalars.  If X is a scalar, A and B must be of compatible dimensions.

 -- Mapping Function: bincoeff (N, K)
     Return the binomial coefficient of N and K, defined as

           /   \
           | n |    n (n-1) (n-2) ... (n-k+1)
           |   |  = -------------------------
           | k |               k!
           \   /

     For example,

          bincoeff (5, 2)
               => 10

 -- Mapping Function: erf (Z)
     Computes the error function,

                                   z
                                  /
          erf (z) = (2/sqrt (pi)) | e^(-t^2) dt
                                  /
                               t=0

 -- Mapping Function: erfc (Z)
     Computes the complementary error function, 1 - erf (Z).

 -- Mapping Function: erfinv (Z)
     Computes the inverse of the error function,

 -- Mapping Function: gamma (Z)
     Computes the Gamma function,

                      infinity
                      /
          gamma (z) = | t^(z-1) exp (-t) dt.
                      /
                   t=0

 -- Mapping Function: gammai (A, X)
     Computes the incomplete gamma function,

                                        x
                              1        /
          gammai (a, x) = ---------    | exp (-t) t^(a-1) dt
                          gamma (a)    /
                                    t=0

     If A is scalar, then gammai (A, X) is returned for each element of X and vice versa.

     If neither A nor X is scalar, the sizes of A and X must agree, and GAMMAI is applied element-by-element.

 -- Mapping Function: lgamma (A, X)
 -- Mapping Function: gammaln (A, X)
     Return the natural logarithm of the gamma function.

 -- Function File: cross (X, Y)
     Computes the vector cross product of the two 3-dimensional vectors X and Y.  For example,

          cross ([1,1,0], [0,1,1])
               => [ 1; -1; 1 ]

 -- Function File: commutation_matrix (M, N)
     Return the commutation matrix K(m,n) which is the unique M*N by M*N matrix such that K(M,N) * vec (A) = vec (A') for all M by N matrices A.

     If only one argument M is given, K(m,m) is returned.

     See Magnus and Neudecker (1988), Matrix differential calculus with applications in statistics and econometrics.

 -- Function File: duplication_matrix (N)
     Return the duplication matrix D_N which is the unique N^2 by N*(N+1)/2 matrix such that D_N \cdot vech (A) = vec (A) for all symmetric N by N matrices A.

     See Magnus and Neudecker (1988), Matrix differential calculus with applications in statistics and econometrics.

Mathematical Constants
======================

 -- Built-in Variable: I
 -- Built-in Variable: J
 -- Built-in Variable: i
 -- Built-in Variable: j
     A pure imaginary number, defined as sqrt (-1). The I and J forms are true constants, and cannot be modified.  The i and j forms are like ordinary variables, and may be used for other purposes.  However, unlike other variables, they once again assume their special predefined values if they are cleared see Status of Variables.

 -- Built-in Variable: Inf
 -- Built-in Variable: inf
     Infinity.  This is the result of an operation like 1/0, or an operation that results in a floating point overflow.

 -- Built-in Variable: NaN
 -- Built-in Variable: nan
     Not a number.  This is the result of an operation like 0/0, or Inf - Inf, or any operation with a NaN.

     Note that NaN always compares not equal to NaN.  This behavior is specified by the IEEE standard for floating point arithmetic.  To find NaN values, you must use the isnan function.

 -- Built-in Variable: pi
     The ratio of the circumference of a circle to its diameter. Internally, pi is computed as 4.0 * atan (1.0).

 -- Built-in Variable: e
     The base of natural logarithms.  The constant E satisfies the equation log (E) = 1.

 -- Built-in Variable: eps
     The machine precision.  More precisely, eps is the largest relative spacing between any two adjacent numbers in the machine's floating point system.  This number is obviously system-dependent.  On machines that support 64 bit IEEE floating point arithmetic, eps is approximately 2.2204e-16.

 -- Built-in Variable: realmax
     The largest floating point number that is representable.  The actual value is system-dependent.  On machines that support 64 bit IEEE floating point arithmetic, realmax is approximately 1.7977e+308

 -- Built-in Variable: realmin
     The smallest floating point number that is representable.  The actual value is system-dependent.  On machines that support 64 bit IEEE floating point arithmetic, realmin is approximately 2.2251e-308