@c DO NOT EDIT!  Generated automatically by munge-texi.pl.

@c Copyright (C) 1996-2013 John W. Eaton
@c
@c This file is part of Octave.
@c
@c Octave is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details.
@c 
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@node Arithmetic
@chapter Arithmetic

Unless otherwise noted, all of the functions described in this chapter
will work for real and complex scalar, vector, or matrix arguments.  Functions
described as @dfn{mapping functions} apply the given operation individually to 
each element when given a matrix argument.  For example:

@example
@group
sin ([1, 2; 3, 4])
     @result{}  0.84147   0.90930
         0.14112  -0.75680
@end group
@end example

@menu
* Exponents and Logarithms::
* Complex Arithmetic::
* Trigonometry::
* Sums and Products::
* Utility Functions::
* Special Functions::
* Rational Approximations::
* Coordinate Transformations::
* Mathematical Constants::
@end menu

@node Exponents and Logarithms
@section Exponents and Logarithms

@c exp libinterp/corefcn/mappers.cc
@anchor{XREFexp}
@deftypefn {Mapping Function} {} exp (@var{x})
Compute
@tex
$e^{x}$
@end tex
@ifnottex
@code{e^x}
@end ifnottex
for each element of @var{x}.  To compute the matrix
exponential, see @ref{Linear Algebra}.
@seealso{@ref{XREFlog,,log}}
@end deftypefn


@c expm1 libinterp/corefcn/mappers.cc
@anchor{XREFexpm1}
@deftypefn {Mapping Function} {} expm1 (@var{x})
Compute
@tex
$ e^{x} - 1 $
@end tex
@ifnottex
@code{exp (@var{x}) - 1}
@end ifnottex
accurately in the neighborhood of zero.
@seealso{@ref{XREFexp,,exp}}
@end deftypefn


@c log libinterp/corefcn/mappers.cc
@anchor{XREFlog}
@deftypefn {Mapping Function} {} log (@var{x})
Compute the natural logarithm,
@tex
$\ln{(x)},$
@end tex
@ifnottex
@code{ln (@var{x})},
@end ifnottex
for each element of @var{x}.  To compute the
matrix logarithm, see @ref{Linear Algebra}.
@seealso{@ref{XREFexp,,exp}, @ref{XREFlog1p,,log1p}, @ref{XREFlog2,,log2}, @ref{XREFlog10,,log10}, @ref{XREFlogspace,,logspace}}
@end deftypefn


@c reallog scripts/specfun/reallog.m
@anchor{XREFreallog}
@deftypefn {Function File} {} reallog (@var{x})
Return the real-valued natural logarithm of each element of @var{x}.  Report
an error if any element results in a complex return value.
@seealso{@ref{XREFlog,,log}, @ref{XREFrealpow,,realpow}, @ref{XREFrealsqrt,,realsqrt}}
@end deftypefn


@c log1p libinterp/corefcn/mappers.cc
@anchor{XREFlog1p}
@deftypefn {Mapping Function} {} log1p (@var{x})
Compute
@tex
$\ln{(1 + x)}$
@end tex
@ifnottex
@code{log (1 + @var{x})}
@end ifnottex
accurately in the neighborhood of zero.
@seealso{@ref{XREFlog,,log}, @ref{XREFexp,,exp}, @ref{XREFexpm1,,expm1}}
@end deftypefn


@c log10 libinterp/corefcn/mappers.cc
@anchor{XREFlog10}
@deftypefn {Mapping Function} {} log10 (@var{x})
Compute the base-10 logarithm of each element of @var{x}.
@seealso{@ref{XREFlog,,log}, @ref{XREFlog2,,log2}, @ref{XREFlogspace,,logspace}, @ref{XREFexp,,exp}}
@end deftypefn


@c log2 libinterp/corefcn/data.cc
@anchor{XREFlog2}
@deftypefn  {Mapping Function} {} log2 (@var{x})
@deftypefnx {Mapping Function} {[@var{f}, @var{e}] =} log2 (@var{x})
Compute the base-2 logarithm of each element of @var{x}.

If called with two output arguments, split @var{x} into
binary mantissa and exponent so that
@tex
${1 \over 2} \le \left| f \right| < 1$
@end tex
@ifnottex
@code{1/2 <= abs(f) < 1}
@end ifnottex
and @var{e} is an integer.  If
@tex
$x = 0$, $f = e = 0$.
@end tex
@ifnottex
@code{x = 0}, @code{f = e = 0}.
@end ifnottex
@seealso{@ref{XREFpow2,,pow2}, @ref{XREFlog,,log}, @ref{XREFlog10,,log10}, @ref{XREFexp,,exp}}
@end deftypefn


@c pow2 scripts/specfun/pow2.m
@anchor{XREFpow2}
@deftypefn  {Mapping Function} {} pow2 (@var{x})
@deftypefnx {Mapping Function} {} pow2 (@var{f}, @var{e})
With one argument, computes
@tex
$2^x$
@end tex
@ifnottex
2 .^ x
@end ifnottex
for each element of @var{x}.

With two arguments, returns
@tex
$f \cdot 2^e$.
@end tex
@ifnottex
f .* (2 .^ e).
@end ifnottex
@seealso{@ref{XREFlog2,,log2}, @ref{XREFnextpow2,,nextpow2}}
@end deftypefn


@c nextpow2 scripts/general/nextpow2.m
@anchor{XREFnextpow2}
@deftypefn {Function File} {} nextpow2 (@var{x})
If @var{x} is a scalar, return the first integer @var{n} such that
@tex
$2^n \ge |x|$.
@end tex
@ifnottex
2^n @geq{} abs (x).
@end ifnottex

If @var{x} is a vector, return @code{nextpow2 (length (@var{x}))}.
@seealso{@ref{XREFpow2,,pow2}, @ref{XREFlog2,,log2}}
@end deftypefn


@c realpow scripts/specfun/realpow.m
@anchor{XREFrealpow}
@deftypefn {Function File} {} realpow (@var{x}, @var{y})
Compute the real-valued, element-by-element power operator.  This is
equivalent to @w{@code{@var{x} .^ @var{y}}}, except that @code{realpow}
reports an error if any return value is complex.
@seealso{@ref{XREFreallog,,reallog}, @ref{XREFrealsqrt,,realsqrt}}
@end deftypefn


@c sqrt libinterp/corefcn/mappers.cc
@anchor{XREFsqrt}
@deftypefn {Mapping Function} {} sqrt (@var{x})
Compute the square root of each element of @var{x}.  If @var{x} is negative,
a complex result is returned.  To compute the matrix square root, see
@ref{Linear Algebra}.
@seealso{@ref{XREFrealsqrt,,realsqrt}, @ref{XREFnthroot,,nthroot}}
@end deftypefn


@c realsqrt scripts/specfun/realsqrt.m
@anchor{XREFrealsqrt}
@deftypefn {Function File} {} realsqrt (@var{x})
Return the real-valued square root of each element of @var{x}.  Report an
error if any element results in a complex return value.
@seealso{@ref{XREFsqrt,,sqrt}, @ref{XREFrealpow,,realpow}, @ref{XREFreallog,,reallog}}
@end deftypefn


@c cbrt libinterp/corefcn/mappers.cc
@anchor{XREFcbrt}
@deftypefn {Mapping Function} {} cbrt (@var{x})
Compute the real cube root of each element of @var{x}.
Unlike @code{@var{x}^(1/3)}, the result will be negative if @var{x} is
negative.
@seealso{@ref{XREFnthroot,,nthroot}}
@end deftypefn


@c nthroot scripts/specfun/nthroot.m
@anchor{XREFnthroot}
@deftypefn {Function File} {} nthroot (@var{x}, @var{n})

Compute the n-th root of @var{x}, returning real results for real
components of @var{x}.  For example:

@example
@group
nthroot (-1, 3)
@result{} -1
(-1) ^ (1 / 3)
@result{} 0.50000 - 0.86603i
@end group
@end example

@var{x} must have all real entries.  @var{n} must be a scalar.
If @var{n} is an even integer and @var{X} has negative entries, an
error is produced.
@seealso{@ref{XREFrealsqrt,,realsqrt}, @ref{XREFsqrt,,sqrt}, @ref{XREFcbrt,,cbrt}}
@end deftypefn


@node Complex Arithmetic
@section Complex Arithmetic

In the descriptions of the following functions,
@tex
$z$ is the complex number $x + iy$, where $i$ is defined as
$\sqrt{-1}$.
@end tex
@ifnottex
@var{z} is the complex number @var{x} + @var{i}@var{y}, where @var{i} is
defined as @code{sqrt (-1)}.
@end ifnottex

@c abs libinterp/corefcn/mappers.cc
@anchor{XREFabs}
@deftypefn {Mapping Function} {} abs (@var{z})
Compute the magnitude of @var{z}, defined as
@tex
$|z| = \sqrt{x^2 + y^2}$.
@end tex
@ifnottex
|@var{z}| = @code{sqrt (x^2 + y^2)}.
@end ifnottex

For example:

@example
@group
abs (3 + 4i)
     @result{} 5
@end group
@end example
@end deftypefn


@c arg libinterp/corefcn/mappers.cc
@anchor{XREFarg}
@deftypefn  {Mapping Function} {} arg (@var{z})
@deftypefnx {Mapping Function} {} angle (@var{z})
Compute the argument of @var{z}, defined as,
@tex
$\theta = atan2 (y, x),$
@end tex
@ifnottex
@var{theta} = @code{atan2 (@var{y}, @var{x})},
@end ifnottex
in radians.

For example:

@example
@group
arg (3 + 4i)
     @result{} 0.92730
@end group
@end example
@end deftypefn


@c conj libinterp/corefcn/mappers.cc
@anchor{XREFconj}
@deftypefn {Mapping Function} {} conj (@var{z})
Return the complex conjugate of @var{z}, defined as
@tex
$\bar{z} = x - iy$.
@end tex
@ifnottex
@code{conj (@var{z})} = @var{x} - @var{i}@var{y}.
@end ifnottex
@seealso{@ref{XREFreal,,real}, @ref{XREFimag,,imag}}
@end deftypefn


@c cplxpair scripts/general/cplxpair.m
@anchor{XREFcplxpair}
@deftypefn  {Function File} {} cplxpair (@var{z})
@deftypefnx {Function File} {} cplxpair (@var{z}, @var{tol})
@deftypefnx {Function File} {} cplxpair (@var{z}, @var{tol}, @var{dim})
Sort the numbers @var{z} into complex conjugate pairs ordered by
increasing real part.  Place the negative imaginary complex number
first within each pair.  Place all the real numbers (those with
@code{abs (imag (@var{z}) / @var{z}) < @var{tol})}) after the
complex pairs.

If @var{tol} is unspecified the default value is 100*@code{eps}.

By default the complex pairs are sorted along the first non-singleton
dimension of @var{z}.  If @var{dim} is specified, then the complex
pairs are sorted along this dimension.

Signal an error if some complex numbers could not be paired.  Signal an
error if all complex numbers are not exact conjugates (to within
@var{tol}).  Note that there is no defined order for pairs with identical
real parts but differing imaginary parts.
@c Set example in small font to prevent overfull line

@smallexample
cplxpair (exp(2i*pi*[0:4]'/5)) == exp(2i*pi*[3; 2; 4; 1; 0]/5)
@end smallexample
@end deftypefn


@c imag libinterp/corefcn/mappers.cc
@anchor{XREFimag}
@deftypefn {Mapping Function} {} imag (@var{z})
Return the imaginary part of @var{z} as a real number.
@seealso{@ref{XREFreal,,real}, @ref{XREFconj,,conj}}
@end deftypefn


@c real libinterp/corefcn/mappers.cc
@anchor{XREFreal}
@deftypefn {Mapping Function} {} real (@var{z})
Return the real part of @var{z}.
@seealso{@ref{XREFimag,,imag}, @ref{XREFconj,,conj}}
@end deftypefn


@node Trigonometry
@section Trigonometry

Octave provides the following trigonometric functions where angles are
specified in radians.  To convert from degrees to radians multiply by
@tex
$\pi/180$
@end tex
@ifnottex
@code{pi/180}
@end ifnottex
(e.g., @code{sin (30 * pi/180)} returns the sine of 30 degrees).  As
an alternative, Octave provides a number of trigonometric functions
which work directly on an argument specified in degrees.  These functions
are named after the base trigonometric function with a @samp{d} suffix.  For
example, @code{sin} expects an angle in radians while @code{sind} expects an
angle in degrees.

Octave uses the C library trigonometric functions.  It is expected that these
functions are defined by the ISO/IEC 9899 Standard.  This Standard is available
at: @url{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf}.
Section F.9.1 deals with the trigonometric functions.  The behavior of most of
the functions is relatively straightforward.  However, there are some
exceptions to the standard behavior.  Many of the exceptions involve the
behavior for -0.  The most complex case is atan2.  Octave exactly implements
the behavior given in the Standard.  Including
@tex
$atan2(\pm0, -0)$ returns $\pm \pi$.
@end tex
@ifnottex
@code{atan2(+- 0, 0)} returns @code{+- pi}.
@end ifnottex

It should be noted that @sc{matlab} uses different definitions which apparently
do not distinguish -0.

@c sin libinterp/corefcn/mappers.cc
@anchor{XREFsin}
@deftypefn {Mapping Function} {} sin (@var{x})
Compute the sine for each element of @var{x} in radians.
@seealso{@ref{XREFasin,,asin}, @ref{XREFsind,,sind}, @ref{XREFsinh,,sinh}}
@end deftypefn

@c cos libinterp/corefcn/mappers.cc
@anchor{XREFcos}
@deftypefn {Mapping Function} {} cos (@var{x})
Compute the cosine for each element of @var{x} in radians.
@seealso{@ref{XREFacos,,acos}, @ref{XREFcosd,,cosd}, @ref{XREFcosh,,cosh}}
@end deftypefn

@c tan libinterp/corefcn/mappers.cc
@anchor{XREFtan}
@deftypefn {Mapping Function} {} tan (@var{z})
Compute the tangent for each element of @var{x} in radians.
@seealso{@ref{XREFatan,,atan}, @ref{XREFtand,,tand}, @ref{XREFtanh,,tanh}}
@end deftypefn

@c sec scripts/elfun/sec.m
@anchor{XREFsec}
@deftypefn {Mapping Function} {} sec (@var{x})
Compute the secant for each element of @var{x} in radians.
@seealso{@ref{XREFasec,,asec}, @ref{XREFsecd,,secd}, @ref{XREFsech,,sech}}
@end deftypefn

@c csc scripts/elfun/csc.m
@anchor{XREFcsc}
@deftypefn {Mapping Function} {} csc (@var{x})
Compute the cosecant for each element of @var{x} in radians.
@seealso{@ref{XREFacsc,,acsc}, @ref{XREFcscd,,cscd}, @ref{XREFcsch,,csch}}
@end deftypefn

@c cot scripts/elfun/cot.m
@anchor{XREFcot}
@deftypefn {Mapping Function} {} cot (@var{x})
Compute the cotangent for each element of @var{x} in radians.
@seealso{@ref{XREFacot,,acot}, @ref{XREFcotd,,cotd}, @ref{XREFcoth,,coth}}
@end deftypefn


@c asin libinterp/corefcn/mappers.cc
@anchor{XREFasin}
@deftypefn {Mapping Function} {} asin (@var{x})
Compute the inverse sine in radians for each element of @var{x}.
@seealso{@ref{XREFsin,,sin}, @ref{XREFasind,,asind}}
@end deftypefn

@c acos libinterp/corefcn/mappers.cc
@anchor{XREFacos}
@deftypefn {Mapping Function} {} acos (@var{x})
Compute the inverse cosine in radians for each element of @var{x}.
@seealso{@ref{XREFcos,,cos}, @ref{XREFacosd,,acosd}}
@end deftypefn

@c atan libinterp/corefcn/mappers.cc
@anchor{XREFatan}
@deftypefn {Mapping Function} {} atan (@var{x})
Compute the inverse tangent in radians for each element of @var{x}.
@seealso{@ref{XREFtan,,tan}, @ref{XREFatand,,atand}}
@end deftypefn

@c asec scripts/elfun/asec.m
@anchor{XREFasec}
@deftypefn {Mapping Function} {} asec (@var{x})
Compute the inverse secant in radians for each element of @var{x}.
@seealso{@ref{XREFsec,,sec}, @ref{XREFasecd,,asecd}}
@end deftypefn

@c acsc scripts/elfun/acsc.m
@anchor{XREFacsc}
@deftypefn {Mapping Function} {} acsc (@var{x})
Compute the inverse cosecant in radians for each element of @var{x}.
@seealso{@ref{XREFcsc,,csc}, @ref{XREFacscd,,acscd}}
@end deftypefn

@c acot scripts/elfun/acot.m
@anchor{XREFacot}
@deftypefn {Mapping Function} {} acot (@var{x})
Compute the inverse cotangent in radians for each element of @var{x}.
@seealso{@ref{XREFcot,,cot}, @ref{XREFacotd,,acotd}}
@end deftypefn


@c sinh libinterp/corefcn/mappers.cc
@anchor{XREFsinh}
@deftypefn {Mapping Function} {} sinh (@var{x})
Compute the hyperbolic sine for each element of @var{x}.
@seealso{@ref{XREFasinh,,asinh}, @ref{XREFcosh,,cosh}, @ref{XREFtanh,,tanh}}
@end deftypefn

@c cosh libinterp/corefcn/mappers.cc
@anchor{XREFcosh}
@deftypefn {Mapping Function} {} cosh (@var{x})
Compute the hyperbolic cosine for each element of @var{x}.
@seealso{@ref{XREFacosh,,acosh}, @ref{XREFsinh,,sinh}, @ref{XREFtanh,,tanh}}
@end deftypefn

@c tanh libinterp/corefcn/mappers.cc
@anchor{XREFtanh}
@deftypefn {Mapping Function} {} tanh (@var{x})
Compute hyperbolic tangent for each element of @var{x}.
@seealso{@ref{XREFatanh,,atanh}, @ref{XREFsinh,,sinh}, @ref{XREFcosh,,cosh}}
@end deftypefn

@c sech scripts/elfun/sech.m
@anchor{XREFsech}
@deftypefn {Mapping Function} {} sech (@var{x})
Compute the hyperbolic secant of each element of @var{x}.
@seealso{@ref{XREFasech,,asech}}
@end deftypefn

@c csch scripts/elfun/csch.m
@anchor{XREFcsch}
@deftypefn {Mapping Function} {} csch (@var{x})
Compute the hyperbolic cosecant of each element of @var{x}.
@seealso{@ref{XREFacsch,,acsch}}
@end deftypefn

@c coth scripts/elfun/coth.m
@anchor{XREFcoth}
@deftypefn {Mapping Function} {} coth (@var{x})
Compute the hyperbolic cotangent of each element of @var{x}.
@seealso{@ref{XREFacoth,,acoth}}
@end deftypefn


@c asinh libinterp/corefcn/mappers.cc
@anchor{XREFasinh}
@deftypefn {Mapping Function} {} asinh (@var{x})
Compute the inverse hyperbolic sine for each element of @var{x}.
@seealso{@ref{XREFsinh,,sinh}}
@end deftypefn

@c acosh libinterp/corefcn/mappers.cc
@anchor{XREFacosh}
@deftypefn {Mapping Function} {} acosh (@var{x})
Compute the inverse hyperbolic cosine for each element of @var{x}.
@seealso{@ref{XREFcosh,,cosh}}
@end deftypefn

@c atanh libinterp/corefcn/mappers.cc
@anchor{XREFatanh}
@deftypefn {Mapping Function} {} atanh (@var{x})
Compute the inverse hyperbolic tangent for each element of @var{x}.
@seealso{@ref{XREFtanh,,tanh}}
@end deftypefn

@c asech scripts/elfun/asech.m
@anchor{XREFasech}
@deftypefn {Mapping Function} {} asech (@var{x})
Compute the inverse hyperbolic secant of each element of @var{x}.
@seealso{@ref{XREFsech,,sech}}
@end deftypefn

@c acsch scripts/elfun/acsch.m
@anchor{XREFacsch}
@deftypefn {Mapping Function} {} acsch (@var{x})
Compute the inverse hyperbolic cosecant of each element of @var{x}.
@seealso{@ref{XREFcsch,,csch}}
@end deftypefn

@c acoth scripts/elfun/acoth.m
@anchor{XREFacoth}
@deftypefn {Mapping Function} {} acoth (@var{x})
Compute the inverse hyperbolic cotangent of each element of @var{x}.
@seealso{@ref{XREFcoth,,coth}}
@end deftypefn


@c atan2 libinterp/corefcn/data.cc
@anchor{XREFatan2}
@deftypefn {Mapping Function} {} atan2 (@var{y}, @var{x})
Compute atan (@var{y} / @var{x}) for corresponding elements of @var{y}
and @var{x}.  Signal an error if @var{y} and @var{x} do not match in size
and orientation.
@seealso{@ref{XREFtan,,tan}, @ref{XREFtand,,tand}, @ref{XREFtanh,,tanh}, @ref{XREFatanh,,atanh}}
@end deftypefn


Octave provides the following trigonometric functions where angles are
specified in degrees.  These functions produce true zeros at the appropriate
intervals rather than the small round-off error that occurs when using
radians.  For example:

@example
@group
cosd (90)
     @result{} 0
cos (pi/2)
     @result{} 6.1230e-17
@end group
@end example

@c sind scripts/elfun/sind.m
@anchor{XREFsind}
@deftypefn {Function File} {} sind (@var{x})
Compute the sine for each element of @var{x} in degrees.  Returns zero
for elements where @code{@var{x}/180} is an integer.
@seealso{@ref{XREFasind,,asind}, @ref{XREFsin,,sin}}
@end deftypefn

@c cosd scripts/elfun/cosd.m
@anchor{XREFcosd}
@deftypefn {Function File} {} cosd (@var{x})
Compute the cosine for each element of @var{x} in degrees.  Returns zero
for elements where @code{(@var{x}-90)/180} is an integer.
@seealso{@ref{XREFacosd,,acosd}, @ref{XREFcos,,cos}}
@end deftypefn

@c tand scripts/elfun/tand.m
@anchor{XREFtand}
@deftypefn {Function File} {} tand (@var{x})
Compute the tangent for each element of @var{x} in degrees.  Returns zero
for elements where @code{@var{x}/180} is an integer and @code{Inf} for
elements where @code{(@var{x}-90)/180} is an integer.
@seealso{@ref{XREFatand,,atand}, @ref{XREFtan,,tan}}
@end deftypefn

@c secd scripts/elfun/secd.m
@anchor{XREFsecd}
@deftypefn {Function File} {} secd (@var{x})
Compute the secant for each element of @var{x} in degrees.
@seealso{@ref{XREFasecd,,asecd}, @ref{XREFsec,,sec}}
@end deftypefn

@c cscd scripts/elfun/cscd.m
@anchor{XREFcscd}
@deftypefn {Function File} {} cscd (@var{x})
Compute the cosecant for each element of @var{x} in degrees.
@seealso{@ref{XREFacscd,,acscd}, @ref{XREFcsc,,csc}}
@end deftypefn

@c cotd scripts/elfun/cotd.m
@anchor{XREFcotd}
@deftypefn {Function File} {} cotd (@var{x})
Compute the cotangent for each element of @var{x} in degrees.
@seealso{@ref{XREFacotd,,acotd}, @ref{XREFcot,,cot}}
@end deftypefn


@c asind scripts/elfun/asind.m
@anchor{XREFasind}
@deftypefn {Function File} {} asind (@var{x})
Compute the inverse sine in degrees for each element of @var{x}.
@seealso{@ref{XREFsind,,sind}, @ref{XREFasin,,asin}}
@end deftypefn

@c acosd scripts/elfun/acosd.m
@anchor{XREFacosd}
@deftypefn {Function File} {} acosd (@var{x})
Compute the inverse cosine in degrees for each element of @var{x}.
@seealso{@ref{XREFcosd,,cosd}, @ref{XREFacos,,acos}}
@end deftypefn

@c atand scripts/elfun/atand.m
@anchor{XREFatand}
@deftypefn {Function File} {} atand (@var{x})
Compute the inverse tangent in degrees for each element of @var{x}.
@seealso{@ref{XREFtand,,tand}, @ref{XREFatan,,atan}}
@end deftypefn

@c atan2d scripts/elfun/atan2d.m
@anchor{XREFatan2d}
@deftypefn {Function File} {} atan2d (@var{y}, @var{x})
Compute atan2 (@var{y} / @var{x}) in degrees for corresponding elements
from @var{y} and @var{x}.
@seealso{@ref{XREFtand,,tand}, @ref{XREFatan2,,atan2}}
@end deftypefn

@c asecd scripts/elfun/asecd.m
@anchor{XREFasecd}
@deftypefn {Function File} {} asecd (@var{x})
Compute the inverse secant in degrees for each element of @var{x}.
@seealso{@ref{XREFsecd,,secd}, @ref{XREFasec,,asec}}
@end deftypefn

@c acscd scripts/elfun/acscd.m
@anchor{XREFacscd}
@deftypefn {Function File} {} acscd (@var{x})
Compute the inverse cosecant in degrees for each element of @var{x}.
@seealso{@ref{XREFcscd,,cscd}, @ref{XREFacsc,,acsc}}
@end deftypefn

@c acotd scripts/elfun/acotd.m
@anchor{XREFacotd}
@deftypefn {Function File} {} acotd (@var{x})
Compute the inverse cotangent in degrees for each element of @var{x}.
@seealso{@ref{XREFcotd,,cotd}, @ref{XREFacot,,acot}}
@end deftypefn


@node Sums and Products
@section Sums and Products

@c sum libinterp/corefcn/data.cc
@anchor{XREFsum}
@deftypefn  {Built-in Function} {} sum (@var{x})
@deftypefnx {Built-in Function} {} sum (@var{x}, @var{dim})
@deftypefnx {Built-in Function} {} sum (@dots{}, "native")
@deftypefnx {Built-in Function} {} sum (@dots{}, "double")
@deftypefnx {Built-in Function} {} sum (@dots{}, "extra")
Sum of elements along dimension @var{dim}.  If @var{dim} is
omitted, it defaults to the first non-singleton dimension.

If the optional argument @qcode{"native"} is given, then the sum is
performed in the same type as the original argument, rather than in the
default double type.  For example:

@example
@group
sum ([true, true])
   @result{} 2
sum ([true, true], "native")
   @result{} true
@end group
@end example

On the contrary, if @qcode{"double"} is given, the sum is performed in
double precision even for single precision inputs.

For double precision inputs, @qcode{"extra"} indicates that a more accurate
algorithm than straightforward summation is to be used.  For single precision
inputs, @qcode{"extra"} is the same as @qcode{"double"}.  Otherwise,
@qcode{"extra"} has no effect.
@seealso{@ref{XREFcumsum,,cumsum}, @ref{XREFsumsq,,sumsq}, @ref{XREFprod,,prod}}
@end deftypefn


@c prod libinterp/corefcn/data.cc
@anchor{XREFprod}
@deftypefn  {Built-in Function} {} prod (@var{x})
@deftypefnx {Built-in Function} {} prod (@var{x}, @var{dim})
Product of elements along dimension @var{dim}.  If @var{dim} is
omitted, it defaults to the first non-singleton dimension.
@seealso{@ref{XREFcumprod,,cumprod}, @ref{XREFsum,,sum}}
@end deftypefn


@c cumsum libinterp/corefcn/data.cc
@anchor{XREFcumsum}
@deftypefn  {Built-in Function} {} cumsum (@var{x})
@deftypefnx {Built-in Function} {} cumsum (@var{x}, @var{dim})
@deftypefnx {Built-in Function} {} cumsum (@dots{}, "native")
@deftypefnx {Built-in Function} {} cumsum (@dots{}, "double")
@deftypefnx {Built-in Function} {} cumsum (@dots{}, "extra")
Cumulative sum of elements along dimension @var{dim}.  If @var{dim}
is omitted, it defaults to the first non-singleton dimension.

See @code{sum} for an explanation of the optional parameters
@qcode{"native"}, @qcode{"double"}, and @qcode{"extra"}.
@seealso{@ref{XREFsum,,sum}, @ref{XREFcumprod,,cumprod}}
@end deftypefn


@c cumprod libinterp/corefcn/data.cc
@anchor{XREFcumprod}
@deftypefn  {Built-in Function} {} cumprod (@var{x})
@deftypefnx {Built-in Function} {} cumprod (@var{x}, @var{dim})
Cumulative product of elements along dimension @var{dim}.  If
@var{dim} is omitted, it defaults to the first non-singleton dimension.

@seealso{@ref{XREFprod,,prod}, @ref{XREFcumsum,,cumsum}}
@end deftypefn


@c sumsq libinterp/corefcn/data.cc
@anchor{XREFsumsq}
@deftypefn  {Built-in Function} {} sumsq (@var{x})
@deftypefnx {Built-in Function} {} sumsq (@var{x}, @var{dim})
Sum of squares of elements along dimension @var{dim}.  If @var{dim}
is omitted, it defaults to the first non-singleton dimension.

This function is conceptually equivalent to computing

@example
sum (x .* conj (x), dim)
@end example

@noindent
but it uses less memory and avoids calling @code{conj} if @var{x} is real.
@seealso{@ref{XREFsum,,sum}, @ref{XREFprod,,prod}}
@end deftypefn


@node Utility Functions
@section Utility Functions

@c ceil libinterp/corefcn/mappers.cc
@anchor{XREFceil}
@deftypefn {Mapping Function} {} ceil (@var{x})
Return the smallest integer not less than @var{x}.  This is equivalent to
rounding towards positive infinity.  If @var{x} is
complex, return @code{ceil (real (@var{x})) + ceil (imag (@var{x})) * I}.

@example
@group
ceil ([-2.7, 2.7])
    @result{} -2    3
@end group
@end example
@seealso{@ref{XREFfloor,,floor}, @ref{XREFround,,round}, @ref{XREFfix,,fix}}
@end deftypefn


@c fix libinterp/corefcn/mappers.cc
@anchor{XREFfix}
@deftypefn {Mapping Function} {} fix (@var{x})
Truncate fractional portion of @var{x} and return the integer portion.  This
is equivalent to rounding towards zero.  If @var{x} is complex, return
@code{fix (real (@var{x})) + fix (imag (@var{x})) * I}.

@example
@group
fix ([-2.7, 2.7])
   @result{} -2    2
@end group
@end example
@seealso{@ref{XREFceil,,ceil}, @ref{XREFfloor,,floor}, @ref{XREFround,,round}}
@end deftypefn


@c floor libinterp/corefcn/mappers.cc
@anchor{XREFfloor}
@deftypefn {Mapping Function} {} floor (@var{x})
Return the largest integer not greater than @var{x}.  This is equivalent to
rounding towards negative infinity.  If @var{x} is
complex, return @code{floor (real (@var{x})) + floor (imag (@var{x})) * I}.

@example
@group
floor ([-2.7, 2.7])
     @result{} -3    2
@end group
@end example
@seealso{@ref{XREFceil,,ceil}, @ref{XREFround,,round}, @ref{XREFfix,,fix}}
@end deftypefn


@c round libinterp/corefcn/mappers.cc
@anchor{XREFround}
@deftypefn {Mapping Function} {} round (@var{x})
Return the integer nearest to @var{x}.  If @var{x} is complex, return
@code{round (real (@var{x})) + round (imag (@var{x})) * I}.  If there
are two nearest integers, return the one further away from zero.

@example
@group
round ([-2.7, 2.7])
     @result{} -3    3
@end group
@end example
@seealso{@ref{XREFceil,,ceil}, @ref{XREFfloor,,floor}, @ref{XREFfix,,fix}, @ref{XREFroundb,,roundb}}
@end deftypefn


@c roundb libinterp/corefcn/mappers.cc
@anchor{XREFroundb}
@deftypefn {Mapping Function} {} roundb (@var{x})
Return the integer nearest to @var{x}.  If there are two nearest
integers, return the even one (banker's rounding).  If @var{x} is complex,
return @code{roundb (real (@var{x})) + roundb (imag (@var{x})) * I}.
@seealso{@ref{XREFround,,round}}
@end deftypefn


@c max libinterp/corefcn/max.cc
@anchor{XREFmax}
@deftypefn  {Built-in Function} {} max (@var{x})
@deftypefnx {Built-in Function} {} max (@var{x}, @var{y})
@deftypefnx {Built-in Function} {} max (@var{x}, [], @var{dim})
@deftypefnx {Built-in Function} {} max (@var{x}, @var{y}, @var{dim})
@deftypefnx {Built-in Function} {[@var{w}, @var{iw}] =} max (@var{x})
For a vector argument, return the maximum value.  For a matrix
argument, return the maximum value from each column, as a row
vector, or over the dimension @var{dim} if defined, in which case @var{y} 
should be set to the empty matrix (it's ignored otherwise).  For two matrices
(or a matrix and scalar), return the pair-wise maximum.
Thus,

@example
max (max (@var{x}))
@end example

@noindent
returns the largest element of the matrix @var{x}, and

@example
@group
max (2:5, pi)
    @result{}  3.1416  3.1416  4.0000  5.0000
@end group
@end example

@noindent
compares each element of the range @code{2:5} with @code{pi}, and
returns a row vector of the maximum values.

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

If called with one input and two output arguments,
@code{max} also returns the first index of the
maximum value(s).  Thus,

@example
@group
[x, ix] = max ([1, 3, 5, 2, 5])
    @result{}  x = 5
        ix = 3
@end group
@end example
@seealso{@ref{XREFmin,,min}, @ref{XREFcummax,,cummax}, @ref{XREFcummin,,cummin}}
@end deftypefn


@c min libinterp/corefcn/max.cc
@anchor{XREFmin}
@deftypefn  {Built-in Function} {} min (@var{x})
@deftypefnx {Built-in Function} {} min (@var{x}, @var{y})
@deftypefnx {Built-in Function} {} min (@var{x}, [], @var{dim})
@deftypefnx {Built-in Function} {} min (@var{x}, @var{y}, @var{dim})
@deftypefnx {Built-in Function} {[@var{w}, @var{iw}] =} min (@var{x})
For a vector argument, return the minimum value.  For a matrix
argument, return the minimum value from each column, as a row
vector, or over the dimension @var{dim} if defined, in which case @var{y} 
should be set to the empty matrix (it's ignored otherwise).  For two matrices
(or a matrix and scalar), return the pair-wise minimum.
Thus,

@example
min (min (@var{x}))
@end example

@noindent
returns the smallest element of @var{x}, and

@example
@group
min (2:5, pi)
    @result{}  2.0000  3.0000  3.1416  3.1416
@end group
@end example

@noindent
compares each element of the range @code{2:5} with @code{pi}, and
returns a row vector of the minimum values.

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

If called with one input and two output arguments,
@code{min} also returns the first index of the
minimum value(s).  Thus,

@example
@group
[x, ix] = min ([1, 3, 0, 2, 0])
    @result{}  x = 0
        ix = 3
@end group
@end example
@seealso{@ref{XREFmax,,max}, @ref{XREFcummin,,cummin}, @ref{XREFcummax,,cummax}}
@end deftypefn


@c cummax libinterp/corefcn/max.cc
@anchor{XREFcummax}
@deftypefn  {Built-in Function} {} cummax (@var{x})
@deftypefnx {Built-in Function} {} cummax (@var{x}, @var{dim})
@deftypefnx {Built-in Function} {[@var{w}, @var{iw}] =} cummax (@dots{})
Return the cumulative maximum values along dimension @var{dim}.

If @var{dim} is unspecified it defaults to column-wise operation.  For
example:

@example
@group
cummax ([1 3 2 6 4 5])
   @result{}  1  3  3  6  6  6
@end group
@end example

If called with two output arguments the index of the maximum value is also
returned.

@example
@group
[w, iw] = cummax ([1 3 2 6 4 5])
@result{}
w =  1  3  3  6  6  6
iw = 1  2  2  4  4  4
@end group
@end example

@seealso{@ref{XREFcummin,,cummin}, @ref{XREFmax,,max}, @ref{XREFmin,,min}}
@end deftypefn


@c cummin libinterp/corefcn/max.cc
@anchor{XREFcummin}
@deftypefn  {Built-in Function} {} cummin (@var{x})
@deftypefnx {Built-in Function} {} cummin (@var{x}, @var{dim})
@deftypefnx {Built-in Function} {[@var{w}, @var{iw}] =} cummin (@var{x})
Return the cumulative minimum values along dimension @var{dim}.

If @var{dim} is unspecified it defaults to column-wise operation.  For
example:

@example
@group
cummin ([5 4 6 2 3 1])
   @result{}  5  4  4  2  2  1
@end group
@end example

If called with two output arguments the index of the minimum value is also
returned.

@example
@group
[w, iw] = cummin ([5 4 6 2 3 1])
@result{}
w =  5  4  4  2  2  1
iw = 1  2  2  4  4  6
@end group
@end example

@seealso{@ref{XREFcummax,,cummax}, @ref{XREFmin,,min}, @ref{XREFmax,,max}}
@end deftypefn


@c hypot libinterp/corefcn/data.cc
@anchor{XREFhypot}
@deftypefn  {Built-in Function} {} hypot (@var{x}, @var{y})
@deftypefnx {Built-in Function} {} hypot (@var{x}, @var{y}, @var{z}, @dots{})
Compute the element-by-element square root of the sum of the squares of
@var{x} and @var{y}.  This is equivalent to
@code{sqrt (@var{x}.^2 + @var{y}.^2)}, but calculated in a manner that
avoids overflows for large values of @var{x} or @var{y}.
@code{hypot} can also be called with more than 2 arguments; in this case,
the arguments are accumulated from left to right:

@example
@group
hypot (hypot (@var{x}, @var{y}), @var{z})
hypot (hypot (hypot (@var{x}, @var{y}), @var{z}), @var{w}), etc.
@end group
@end example
@end deftypefn


@c gradient scripts/general/gradient.m
@anchor{XREFgradient}
@deftypefn  {Function File} {@var{dx} =} gradient (@var{m})
@deftypefnx {Function File} {[@var{dx}, @var{dy}, @var{dz}, @dots{}] =} gradient (@var{m})
@deftypefnx {Function File} {[@dots{}] =} gradient (@var{m}, @var{s})
@deftypefnx {Function File} {[@dots{}] =} gradient (@var{m}, @var{x}, @var{y}, @var{z}, @dots{})
@deftypefnx {Function File} {[@dots{}] =} gradient (@var{f}, @var{x0})
@deftypefnx {Function File} {[@dots{}] =} gradient (@var{f}, @var{x0}, @var{s})
@deftypefnx {Function File} {[@dots{}] =} gradient (@var{f}, @var{x0}, @var{x}, @var{y}, @dots{})

Calculate the gradient of sampled data or a function.  If @var{m}
is a vector, calculate the one-dimensional gradient of @var{m}.  If
@var{m} is a matrix the gradient is calculated for each dimension.

@code{[@var{dx}, @var{dy}] = gradient (@var{m})} calculates the one
dimensional gradient for @var{x} and @var{y} direction if @var{m} is a
matrix.  Additional return arguments can be use for multi-dimensional
matrices.

A constant spacing between two points can be provided by the
@var{s} parameter.  If @var{s} is a scalar, it is assumed to be the spacing
for all dimensions.
Otherwise, separate values of the spacing can be supplied by
the @var{x}, @dots{} arguments.  Scalar values specify an equidistant
spacing.
Vector values for the @var{x}, @dots{} arguments specify the coordinate for
that
dimension.  The length must match their respective dimension of @var{m}.

At boundary points a linear extrapolation is applied.  Interior points
are calculated with the first approximation of the numerical gradient

@example
y'(i) = 1/(x(i+1)-x(i-1)) * (y(i-1)-y(i+1)).
@end example

If the first argument @var{f} is a function handle, the gradient of the
function at the points in @var{x0} is approximated using central
difference.  For example, @code{gradient (@@cos, 0)} approximates the
gradient of the cosine function in the point @math{x0 = 0}.  As with
sampled data, the spacing values between the points from which the
gradient is estimated can be set via the @var{s} or @var{dx},
@var{dy}, @dots{} arguments.  By default a spacing of 1 is used.
@seealso{@ref{XREFdiff,,diff}, @ref{XREFdel2,,del2}}
@end deftypefn


@c dot libinterp/corefcn/dot.cc
@anchor{XREFdot}
@deftypefn {Built-in Function} {} dot (@var{x}, @var{y}, @var{dim})
Compute the dot product of two vectors.  If @var{x} and @var{y}
are matrices, calculate the dot products along the first
non-singleton dimension.  If the optional argument @var{dim} is
given, calculate the dot products along this dimension.

This is equivalent to
@code{sum (conj (@var{X}) .* @var{Y}, @var{dim})},
but avoids forming a temporary array and is faster.  When @var{X} and
@var{Y} are column vectors, the result is equivalent to
@code{@var{X}' * @var{Y}}.
@seealso{@ref{XREFcross,,cross}, @ref{XREFdivergence,,divergence}}
@end deftypefn


@c cross scripts/linear-algebra/cross.m
@anchor{XREFcross}
@deftypefn  {Function File} {} cross (@var{x}, @var{y})
@deftypefnx {Function File} {} cross (@var{x}, @var{y}, @var{dim})
Compute the vector cross product of two 3-dimensional vectors
@var{x} and @var{y}.

@example
@group
cross ([1,1,0], [0,1,1])
     @result{} [ 1; -1; 1 ]
@end group
@end example

If @var{x} and @var{y} are matrices, the cross product is applied
along the first dimension with 3 elements.  The optional argument
@var{dim} forces the cross product to be calculated along
the specified dimension.
@seealso{@ref{XREFdot,,dot}, @ref{XREFcurl,,curl}, @ref{XREFdivergence,,divergence}}
@end deftypefn


@c divergence scripts/general/divergence.m
@anchor{XREFdivergence}
@deftypefn  {Function File} {@var{div} =} divergence (@var{x}, @var{y}, @var{z}, @var{fx}, @var{fy}, @var{fz})
@deftypefnx {Function File} {@var{div} =} divergence (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {Function File} {@var{div} =} divergence (@var{x}, @var{y}, @var{fx}, @var{fy})
@deftypefnx {Function File} {@var{div} =} divergence (@var{fx}, @var{fy})
Calculate divergence of a vector field given by the arrays @var{fx},
@var{fy}, and @var{fz} or @var{fx}, @var{fy} respectively.
@tex
$$
div F(x,y,z) = \partial_x{F} + \partial_y{F} + \partial_z{F}
$$
@end tex
@ifnottex

@example
@group
                  d               d               d
div F(x,y,z)  =   -- F(x,y,z)  +  -- F(x,y,z)  +  -- F(x,y,z)
                  dx              dy              dz
@end group
@end example

@end ifnottex
The coordinates of the vector field can be given by the arguments @var{x},
@var{y}, @var{z} or @var{x}, @var{y} respectively.

@seealso{@ref{XREFcurl,,curl}, @ref{XREFgradient,,gradient}, @ref{XREFdel2,,del2}, @ref{XREFdot,,dot}}
@end deftypefn


@c curl scripts/general/curl.m
@anchor{XREFcurl}
@deftypefn  {Function File} {[@var{cx}, @var{cy}, @var{cz}, @var{v}] =} curl (@var{x}, @var{y}, @var{z}, @var{fx}, @var{fy}, @var{fz})
@deftypefnx {Function File} {[@var{cz}, @var{v}] =} curl (@var{x}, @var{y}, @var{fx}, @var{fy})
@deftypefnx {Function File} {[@dots{}] =} curl (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {Function File} {[@dots{}] =} curl (@var{fx}, @var{fy})
@deftypefnx {Function File} {@var{v} =} curl (@dots{})
Calculate curl of vector field given by the arrays @var{fx}, @var{fy}, and
@var{fz} or @var{fx}, @var{fy} respectively.
@tex
$$ curl F(x,y,z) = \left( {\partial{d} \over \partial{y}} F_z - {\partial{d} \over \partial{z}} F_y, {\partial{d} \over \partial{z}} F_x - {\partial{d} \over \partial{x}} F_z, {\partial{d} \over \partial{x}} F_y - {\partial{d} \over \partial{y}} F_x \right)$$
@end tex
@ifnottex

@example
@group
                  / d         d       d         d       d         d     \
curl F(x,y,z)  =  | -- Fz  -  -- Fy,  -- Fx  -  -- Fz,  -- Fy  -  -- Fx |
                  \ dy        dz      dz        dx      dx        dy    /
@end group
@end example

@end ifnottex
The coordinates of the vector field can be given by the arguments @var{x},
@var{y}, @var{z} or @var{x}, @var{y} respectively.  @var{v} calculates the
scalar component of the angular velocity vector in direction of the z-axis
for two-dimensional input.  For three-dimensional input the scalar
rotation is calculated at each grid point in direction of the vector field
at that point.
@seealso{@ref{XREFdivergence,,divergence}, @ref{XREFgradient,,gradient}, @ref{XREFdel2,,del2}, @ref{XREFcross,,cross}}
@end deftypefn


@c del2 scripts/general/del2.m
@anchor{XREFdel2}
@deftypefn  {Function File} {@var{d} =} del2 (@var{M})
@deftypefnx {Function File} {@var{d} =} del2 (@var{M}, @var{h})
@deftypefnx {Function File} {@var{d} =} del2 (@var{M}, @var{dx}, @var{dy}, @dots{})

Calculate the discrete Laplace
@tex
operator $( \nabla^2 )$.
@end tex
@ifnottex
operator.
@end ifnottex
For a 2-dimensional matrix @var{M} this is defined as
@tex
$$d = {1 \over 4} \left( {d^2 \over dx^2} M(x,y) + {d^2 \over dy^2} M(x,y) \right)$$
@end tex
@ifnottex

@example
@group
      1    / d^2            d^2         \
D  = --- * | ---  M(x,y) +  ---  M(x,y) |
      4    \ dx^2           dy^2        /
@end group
@end example

@end ifnottex
For N-dimensional arrays the sum in parentheses is expanded to include second
derivatives over the additional higher dimensions.

The spacing between evaluation points may be defined by @var{h}, which is a
scalar defining the equidistant spacing in all dimensions.  Alternatively,
the spacing in each dimension may be defined separately by @var{dx},
@var{dy}, etc.  A scalar spacing argument defines equidistant spacing,
whereas a vector argument can be used to specify variable spacing.  The
length of the spacing vectors must match the respective dimension of
@var{M}.  The default spacing value is 1.

At least 3 data points are needed for each dimension.  Boundary points are
calculated from the linear extrapolation of interior points.

@seealso{@ref{XREFgradient,,gradient}, @ref{XREFdiff,,diff}}
@end deftypefn


@c factorial scripts/specfun/factorial.m
@anchor{XREFfactorial}
@deftypefn {Function File} {} factorial (@var{n})
Return the factorial of @var{n} where @var{n} is a positive integer.  If
@var{n} is a scalar, this is equivalent to @code{prod (1:@var{n})}.  For
vector or matrix arguments, return the factorial of each element in the
array.  For non-integers see the generalized factorial function
@code{gamma}.
@seealso{@ref{XREFprod,,prod}, @ref{XREFgamma,,gamma}}
@end deftypefn


@c factor scripts/specfun/factor.m
@anchor{XREFfactor}
@deftypefn  {Function File} {@var{p} =} factor (@var{q})
@deftypefnx {Function File} {[@var{p}, @var{n}] =} factor (@var{q})

Return the prime factorization of @var{q}.  That is,
@code{prod (@var{p}) == @var{q}} and every element of @var{p} is a prime
number.  If @code{@var{q} == 1}, return 1.

With two output arguments, return the unique primes @var{p} and
their multiplicities.  That is, @code{prod (@var{p} .^ @var{n}) ==
@var{q}}.

Implementation Note: The input @var{q} must not be greater than
@code{bitmax} (9.0072e+15) in order to factor correctly.
@seealso{@ref{XREFgcd,,gcd}, @ref{XREFlcm,,lcm}, @ref{XREFisprime,,isprime}}
@end deftypefn


@c gcd libinterp/corefcn/gcd.cc
@anchor{XREFgcd}
@deftypefn  {Built-in Function} {@var{g} =} gcd (@var{a1}, @var{a2}, @dots{})
@deftypefnx {Built-in Function} {[@var{g}, @var{v1}, @dots{}] =} gcd (@var{a1}, @var{a2}, @dots{})

Compute the greatest common divisor of @var{a1}, @var{a2}, @dots{}.  If more
than one argument is given all arguments must be the same size or scalar.
In this case the greatest common divisor is calculated for each element
individually.  All elements must be ordinary or Gaussian (complex)
integers.  Note that for Gaussian integers, the gcd is not unique up to
units (multiplication by 1, -1, @var{i} or -@var{i}), so an arbitrary
greatest common divisor amongst four possible is returned.

Example code:

@example
@group
gcd ([15, 9], [20, 18])
   @result{}  5  9
@end group
@end example

Optional return arguments @var{v1}, etc., contain integer vectors such
that,

@tex
$g = v_1 a_1 + v_2 a_2 + \cdots$
@end tex
@ifnottex

@example
@var{g} = @var{v1} .* @var{a1} + @var{v2} .* @var{a2} + @dots{}
@end example

@end ifnottex

@seealso{@ref{XREFlcm,,lcm}, @ref{XREFfactor,,factor}}
@end deftypefn


@c lcm scripts/specfun/lcm.m
@anchor{XREFlcm}
@deftypefn  {Mapping Function} {} lcm (@var{x}, @var{y})
@deftypefnx {Mapping Function} {} lcm (@var{x}, @var{y}, @dots{})
Compute the least common multiple of @var{x} and @var{y},
or of the list of all arguments.  All elements must be the same size or
scalar.
@seealso{@ref{XREFfactor,,factor}, @ref{XREFgcd,,gcd}}
@end deftypefn


@c chop scripts/general/chop.m
@anchor{XREFchop}
@deftypefn {Function File} {} chop (@var{x}, @var{ndigits}, @var{base})
Truncate elements of @var{x} to a length of @var{ndigits} such that the
resulting numbers are exactly divisible by @var{base}.  If @var{base} is not
specified it defaults to 10.

@example
@group
chop (-pi, 5, 10)
   @result{} -3.14200000000000
chop (-pi, 5, 5)
   @result{} -3.14150000000000
@end group
@end example
@end deftypefn


@c rem libinterp/corefcn/data.cc
@anchor{XREFrem}
@deftypefn  {Mapping Function} {} rem (@var{x}, @var{y})
@deftypefnx {Mapping Function} {} fmod (@var{x}, @var{y})
Return the remainder of the division @code{@var{x} / @var{y}}, computed
using the expression

@example
x - y .* fix (x ./ y)
@end example

An error message is printed if the dimensions of the arguments do not
agree, or if either of the arguments is complex.
@seealso{@ref{XREFmod,,mod}}
@end deftypefn


@c mod libinterp/corefcn/data.cc
@anchor{XREFmod}
@deftypefn {Mapping Function} {} mod (@var{x}, @var{y})
Compute the modulo of @var{x} and @var{y}.  Conceptually this is given by

@example
x - y .* floor (x ./ y)
@end example

@noindent
and is written such that the correct modulus is returned for
integer types.  This function handles negative values correctly.  That
is, @code{mod (-1, 3)} is 2, not -1, as @code{rem (-1, 3)} returns.
@code{mod (@var{x}, 0)} returns @var{x}.

An error results if the dimensions of the arguments do not agree, or if
either of the arguments is complex.
@seealso{@ref{XREFrem,,rem}}
@end deftypefn


@c primes scripts/specfun/primes.m
@anchor{XREFprimes}
@deftypefn {Function File} {} primes (@var{n})

Return all primes up to @var{n}.

The algorithm used is the Sieve of Eratosthenes.

Note that if you need a specific number of primes you can use the
fact that the distance from one prime to the next is, on average,
proportional to the logarithm of the prime.  Integrating, one finds
that there are about @math{k} primes less than
@tex
$k \log (5 k)$.
@end tex
@ifnottex
k*log (5*k).
@end ifnottex
@seealso{@ref{XREFlist_primes,,list_primes}, @ref{XREFisprime,,isprime}}
@end deftypefn


@c list_primes scripts/miscellaneous/list_primes.m
@anchor{XREFlist_primes}
@deftypefn  {Function File} {} list_primes ()
@deftypefnx {Function File} {} list_primes (@var{n})
List the first @var{n} primes.  If @var{n} is unspecified, the first
25 primes are listed.

The algorithm used is from page 218 of the @TeX{}book.
@seealso{@ref{XREFprimes,,primes}, @ref{XREFisprime,,isprime}}
@end deftypefn


@c sign libinterp/corefcn/mappers.cc
@anchor{XREFsign}
@deftypefn {Mapping Function} {} sign (@var{x})
Compute the @dfn{signum} function, which is defined as
@tex
$$
{\rm sign} (@var{x}) = \cases{1,&$x>0$;\cr 0,&$x=0$;\cr -1,&$x<0$.\cr}
$$
@end tex
@ifnottex

@example
@group
           -1, x < 0;
sign (x) =  0, x = 0;
            1, x > 0.
@end group
@end example

@end ifnottex

For complex arguments, @code{sign} returns @code{x ./ abs (@var{x})}.

Note that @code{sign (-0.0)} is 0.
Although IEEE 754 floating point
allows zero to be signed, 0.0 and -0.0 compare equal.  If you must test
whether zero is signed, use the @code{signbit} function.
@seealso{@ref{XREFsignbit,,signbit}}
@end deftypefn


@c signbit libinterp/corefcn/mappers.cc
@anchor{XREFsignbit}
@deftypefn {Mapping Function} {} signbit (@var{x})
Return logical true if the value of @var{x} has its sign bit set.
Otherwise return logical false.  This behavior is consistent with the other
logical functions.  See@ref{Logical Values}.  The behavior differs from the
C language function which returns non-zero if the sign bit is set.

This is not the same as @code{x < 0.0}, because IEEE 754 floating point
allows zero to be signed.  The comparison @code{-0.0 < 0.0} is false,
but @code{signbit (-0.0)} will return a nonzero value.
@seealso{@ref{XREFsign,,sign}}
@end deftypefn


@node Special Functions
@section Special Functions

@c airy libinterp/corefcn/besselj.cc
@anchor{XREFairy}
@deftypefn {Built-in Function} {[@var{a}, @var{ierr}] =} airy (@var{k}, @var{z}, @var{opt})
Compute Airy functions of the first and second kind, and their
derivatives.

@example
@group
 K   Function   Scale factor (if "opt" is supplied)
---  --------   ---------------------------------------
 0   Ai (Z)     exp ((2/3) * Z * sqrt (Z))
 1   dAi(Z)/dZ  exp ((2/3) * Z * sqrt (Z))
 2   Bi (Z)     exp (-abs (real ((2/3) * Z * sqrt (Z))))
 3   dBi(Z)/dZ  exp (-abs (real ((2/3) * Z * sqrt (Z))))
@end group
@end example

The function call @code{airy (@var{z})} is equivalent to
@code{airy (0, @var{z})}.

The result is the same size as @var{z}.

If requested, @var{ierr} contains the following status information and
is the same size as the result.

@enumerate 0
@item
Normal return.

@item
Input error, return @code{NaN}.

@item
Overflow, return @code{Inf}.

@item
Loss of significance by argument reduction results in less than half
 of machine accuracy.

@item
Complete loss of significance by argument reduction, return @code{NaN}.

@item
Error---no computation, algorithm termination condition not met,
return @code{NaN}.
@end enumerate
@end deftypefn


@c besselj libinterp/corefcn/besselj.cc
@anchor{XREFbesselj}
@deftypefn  {Built-in Function} {[@var{j}, @var{ierr}] =} besselj (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {Built-in Function} {[@var{y}, @var{ierr}] =} bessely (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {Built-in Function} {[@var{i}, @var{ierr}] =} besseli (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {Built-in Function} {[@var{k}, @var{ierr}] =} besselk (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {Built-in Function} {[@var{h}, @var{ierr}] =} besselh (@var{alpha}, @var{k}, @var{x}, @var{opt})
Compute Bessel or Hankel functions of various kinds:

@table @code
@item besselj
Bessel functions of the first kind.  If the argument @var{opt} is supplied,
the result is multiplied by @code{exp (-abs (imag (@var{x})))}.

@item bessely
Bessel functions of the second kind.  If the argument @var{opt} is supplied,
the result is multiplied by @code{exp (-abs (imag (@var{x})))}.

@item besseli

Modified Bessel functions of the first kind.  If the argument @var{opt} is
supplied, the result is multiplied by @code{exp (-abs (real (@var{x})))}.

@item besselk

Modified Bessel functions of the second kind.  If the argument @var{opt} is
supplied, the result is multiplied by @code{exp (@var{x})}.

@item besselh
Compute Hankel functions of the first (@var{k} = 1) or second (@var{k}
= 2) kind.  If the argument @var{opt} is supplied, the result is multiplied
by @code{exp (-I*@var{x})} for @var{k} = 1 or @code{exp (I*@var{x})} for
@var{k} = 2.
@end table

If @var{alpha} is a scalar, the result is the same size as @var{x}.
If @var{x} is a scalar, the result is the same size as @var{alpha}.
If @var{alpha} is a row vector and @var{x} is a column vector, the
result is a matrix with @code{length (@var{x})} rows and
@code{length (@var{alpha})} columns.  Otherwise, @var{alpha} and
@var{x} must conform and the result will be the same size.

The value of @var{alpha} must be real.  The value of @var{x} may be
complex.

If requested, @var{ierr} contains the following status information
and is the same size as the result.

@enumerate 0
@item
Normal return.

@item
Input error, return @code{NaN}.

@item
Overflow, return @code{Inf}.

@item
Loss of significance by argument reduction results in less than
half of machine accuracy.

@item
Complete loss of significance by argument reduction, return @code{NaN}.

@item
Error---no computation, algorithm termination condition not met,
return @code{NaN}.
@end enumerate
@end deftypefn


@c beta scripts/specfun/beta.m
@anchor{XREFbeta}
@deftypefn {Mapping Function} {} beta (@var{a}, @var{b})
For real inputs, return the Beta function,
@tex
$$
 B (a, b) = {\Gamma (a) \Gamma (b) \over \Gamma (a + b)}.
$$
@end tex
@ifnottex

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

@end ifnottex
@seealso{@ref{XREFbetaln,,betaln}, @ref{XREFbetainc,,betainc}}
@end deftypefn


@c betainc libinterp/corefcn/betainc.cc
@anchor{XREFbetainc}
@deftypefn {Mapping Function} {} betainc (@var{x}, @var{a}, @var{b})
Return the regularized incomplete Beta function,
@tex
$$
 I (x, a, b) = {1 \over {B (a, b)}} \int_0^x t^{(a-z)} (1-t)^{(b-1)} dt.
$$
@end tex
@ifnottex
@c Set example in small font to prevent overfull line

@smallexample
@group
                                   x
                          1       /
betainc (x, a, b) = -----------   | t^(a-1) (1-t)^(b-1) dt.
                    beta (a, b)   /
                               t=0
@end group
@end smallexample

@end ifnottex

If @var{x} has more than one component, both @var{a} and @var{b} must be
scalars.  If @var{x} is a scalar, @var{a} and @var{b} must be of
compatible dimensions.
@seealso{@ref{XREFbetaincinv,,betaincinv}, @ref{XREFbeta,,beta}, @ref{XREFbetaln,,betaln}}
@end deftypefn


@c betaincinv libinterp/corefcn/betainc.cc
@anchor{XREFbetaincinv}
@deftypefn {Mapping Function} {} betaincinv (@var{y}, @var{a}, @var{b})
Compute the inverse of the incomplete Beta function, i.e., @var{x} such that

@example
@var{y} == betainc (@var{x}, @var{a}, @var{b}) 
@end example
@seealso{@ref{XREFbetainc,,betainc}, @ref{XREFbeta,,beta}, @ref{XREFbetaln,,betaln}}
@end deftypefn


@c betaln scripts/specfun/betaln.m
@anchor{XREFbetaln}
@deftypefn {Mapping Function} {} betaln (@var{a}, @var{b})
Return the natural logarithm of the Beta function,
@tex
$$
 {\rm betaln} (a, b) = \ln (B (a,b)) \equiv \ln ({\Gamma (a) \Gamma (b) \over \Gamma (a + b)}).
$$
@end tex
@ifnottex

@example
betaln (a, b) = log (beta (a, b))
@end example

@end ifnottex
calculated in a way to reduce the occurrence of underflow.
@seealso{@ref{XREFbeta,,beta}, @ref{XREFbetainc,,betainc}, @ref{XREFgammaln,,gammaln}}
@end deftypefn


@c bincoeff scripts/general/bincoeff.m
@anchor{XREFbincoeff}
@deftypefn {Mapping Function} {} bincoeff (@var{n}, @var{k})
Return the binomial coefficient of @var{n} and @var{k}, defined as
@tex
$$
 {n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!}
$$
@end tex
@ifnottex

@example
@group
 /   \
 | n |    n (n-1) (n-2) @dots{} (n-k+1)
 |   |  = -------------------------
 | k |               k!
 \   /
@end group
@end example

@end ifnottex
For example:

@example
@group
bincoeff (5, 2)
   @result{} 10
@end group
@end example

In most cases, the @code{nchoosek} function is faster for small
scalar integer arguments.  It also warns about loss of precision for
big arguments.

@seealso{@ref{XREFnchoosek,,nchoosek}}
@end deftypefn


@c commutation_matrix scripts/linear-algebra/commutation_matrix.m
@anchor{XREFcommutation_matrix}
@deftypefn {Function File} {} commutation_matrix (@var{m}, @var{n})
Return the commutation matrix
@tex
 $K_{m,n}$
@end tex
@ifnottex
 K(m,n)
@end ifnottex
 which is the unique
@tex
 $m n \times m n$
@end tex
@ifnottex
@var{m}*@var{n} by @var{m}*@var{n}
@end ifnottex
 matrix such that
@tex
 $K_{m,n} \cdot {\rm vec} (A) = {\rm vec} (A^T)$
@end tex
@ifnottex
@math{K(m,n) * vec(A) = vec(A')}
@end ifnottex
 for all
@tex
 $m\times n$
@end tex
@ifnottex
@math{m} by @math{n}
@end ifnottex
 matrices
@tex
 $A$.
@end tex
@ifnottex
@math{A}.
@end ifnottex

If only one argument @var{m} is given,
@tex
 $K_{m,m}$
@end tex
@ifnottex
@math{K(m,m)}
@end ifnottex
 is returned.

See Magnus and Neudecker (1988), @cite{Matrix Differential Calculus with
Applications in Statistics and Econometrics.}
@end deftypefn


@c duplication_matrix scripts/linear-algebra/duplication_matrix.m
@anchor{XREFduplication_matrix}
@deftypefn {Function File} {} duplication_matrix (@var{n})
Return the duplication matrix
@tex
 $D_n$
@end tex
@ifnottex
@nospell{@math{Dn}}
@end ifnottex
 which is the unique
@tex
 $n^2 \times n(n+1)/2$
@end tex
@ifnottex
@math{n^2} by @math{n*(n+1)/2}
@end ifnottex
 matrix such that
@tex
 $D_n * {\rm vech} (A) = {\rm vec} (A)$
@end tex
@ifnottex
@nospell{@math{Dn vech (A) = vec (A)}}
@end ifnottex
 for all symmetric
@tex
 $n \times n$
@end tex
@ifnottex
@math{n} by @math{n}
@end ifnottex
 matrices
@tex
 $A$.
@end tex
@ifnottex
@math{A}.
@end ifnottex

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


@c dawson libinterp/corefcn/mappers.cc
@anchor{XREFdawson}
@deftypefn {Mapping Function} {} dawson (@var{z})
Compute the Dawson (scaled imaginary error) function,
@tex
$$
 {\sqrt{\pi} \over 2} e^{-z^2} {\rm erfi} (z) \equiv -i {\sqrt{\pi} \over 2} e^{-z^2} {\rm erf} (iz)
$$
@end tex
@ifnottex

@example
(sqrt (pi) / 2) * exp (-z^2) * erfi (z)
@end example

@end ifnottex
@seealso{@ref{XREFerfc,,erfc}, @ref{XREFerf,,erf}, @ref{XREFerfcx,,erfcx}, @ref{XREFerfi,,erfi}, @ref{XREFerfinv,,erfinv}, @ref{XREFerfcinv,,erfcinv}}
@end deftypefn


@c ellipj libinterp/corefcn/ellipj.cc
@anchor{XREFellipj}
@deftypefn  {Built-in Function} {[@var{sn}, @var{cn}, @var{dn}, @var{err}] =} ellipj (@var{u}, @var{m})
@deftypefnx {Built-in Function} {[@var{sn}, @var{cn}, @var{dn}, @var{err}] =} ellipj (@var{u}, @var{m}, @var{tol})
Compute the Jacobi elliptic functions @var{sn}, @var{cn}, and @var{dn}
of complex argument @var{u} and real parameter @var{m}.

If @var{m} is a scalar, the results are the same size as @var{u}.
If @var{u} is a scalar, the results are the same size as @var{m}.
If @var{u} is a column vector and @var{m} is a row vector, the
results are matrices with @code{length (@var{u})} rows and
@code{length (@var{m})} columns.  Otherwise, @var{u} and
@var{m} must conform in size and the results will be the same size as the
inputs.

The value of @var{u} may be complex.
The value of @var{m} must be 0 @leq{} @var{m} @leq{} 1.

The optional input @var{tol} is currently ignored (@sc{matlab} uses this to
allow faster, less accurate approximation).

If requested, @var{err} contains the following status information
and is the same size as the result.

@enumerate 0
@item
Normal return.

@item
Error---no computation, algorithm termination condition not met,
return @code{NaN}.
@end enumerate

Reference: Milton Abramowitz and Irene A Stegun,
@cite{Handbook of Mathematical Functions}, Chapter 16 (Sections 16.4, 16.13,
and 16.15), Dover, 1965.

@seealso{@ref{XREFellipke,,ellipke}}
@end deftypefn


@c ellipke scripts/specfun/ellipke.m
@anchor{XREFellipke}
@deftypefn  {Function File} {@var{k} =} ellipke (@var{m})
@deftypefnx {Function File} {@var{k} =} ellipke (@var{m}, @var{tol})
@deftypefnx {Function File} {[@var{k}, @var{e}] =} ellipke (@dots{})
Compute complete elliptic integrals of the first K(@var{m}) and second
E(@var{m}) kind.

@var{m} must be a scalar or real array with -Inf @leq{} @var{m} @leq{} 1.

The optional input @var{tol} is currently ignored (@sc{matlab} uses this
to allow a faster, less accurate approximation).

Called with only one output, elliptic integrals of the first kind are
returned.

Reference: Milton Abramowitz and Irene A. Stegun,
@cite{Handbook of Mathematical Functions}, Chapter 17, Dover, 1965.
@seealso{@ref{XREFellipj,,ellipj}}
@end deftypefn


@c erf libinterp/corefcn/mappers.cc
@anchor{XREFerf}
@deftypefn {Mapping Function} {} erf (@var{z})
Compute the error function,
@tex
$$
 {\rm erf} (z) = {2 \over \sqrt{\pi}}\int_0^z e^{-t^2} dt
$$
@end tex
@ifnottex

@example
@group
                        z
              2        /
erf (z) = --------- *  | e^(-t^2) dt
          sqrt (pi)    /
                    t=0
@end group
@end example

@end ifnottex
@seealso{@ref{XREFerfc,,erfc}, @ref{XREFerfcx,,erfcx}, @ref{XREFerfi,,erfi}, @ref{XREFdawson,,dawson}, @ref{XREFerfinv,,erfinv}, @ref{XREFerfcinv,,erfcinv}}
@end deftypefn


@c erfc libinterp/corefcn/mappers.cc
@anchor{XREFerfc}
@deftypefn {Mapping Function} {} erfc (@var{z})
Compute the complementary error function,
@tex
$1 - {\rm erf} (z)$.
@end tex
@ifnottex
@w{@code{1 - erf (@var{z})}}.
@end ifnottex
@seealso{@ref{XREFerfcinv,,erfcinv}, @ref{XREFerfcx,,erfcx}, @ref{XREFerfi,,erfi}, @ref{XREFdawson,,dawson}, @ref{XREFerf,,erf}, @ref{XREFerfinv,,erfinv}}
@end deftypefn


@c erfcx libinterp/corefcn/mappers.cc
@anchor{XREFerfcx}
@deftypefn {Mapping Function} {} erfcx (@var{z})
Compute the scaled complementary error function,
@tex
$$
 e^{z^2} {\rm erfc} (z) \equiv e^{z^2} (1 - {\rm erf} (z))
$$
@end tex
@ifnottex

@example
exp (z^2) * erfc (z)
@end example

@end ifnottex
@seealso{@ref{XREFerfc,,erfc}, @ref{XREFerf,,erf}, @ref{XREFerfi,,erfi}, @ref{XREFdawson,,dawson}, @ref{XREFerfinv,,erfinv}, @ref{XREFerfcinv,,erfcinv}}
@end deftypefn


@c erfi libinterp/corefcn/mappers.cc
@anchor{XREFerfi}
@deftypefn {Mapping Function} {} erfi (@var{z})
Compute the imaginary error function,
@tex
$$
 -i {\rm erf} (iz) 
$$
@end tex
@ifnottex

@example
-i * erf (i*z)
@end example

@end ifnottex
@seealso{@ref{XREFerfc,,erfc}, @ref{XREFerf,,erf}, @ref{XREFerfcx,,erfcx}, @ref{XREFdawson,,dawson}, @ref{XREFerfinv,,erfinv}, @ref{XREFerfcinv,,erfcinv}}
@end deftypefn


@c erfinv libinterp/corefcn/mappers.cc
@anchor{XREFerfinv}
@deftypefn {Mapping Function} {} erfinv (@var{x})
Compute the inverse error function, i.e., @var{y} such that

@example
erf (@var{y}) == @var{x}
@end example
@seealso{@ref{XREFerf,,erf}, @ref{XREFerfc,,erfc}, @ref{XREFerfcx,,erfcx}, @ref{XREFerfi,,erfi}, @ref{XREFdawson,,dawson}, @ref{XREFerfcinv,,erfcinv}}
@end deftypefn


@c erfcinv libinterp/corefcn/mappers.cc
@anchor{XREFerfcinv}
@deftypefn {Mapping Function} {} erfcinv (@var{x})
Compute the inverse complementary error function, i.e., @var{y} such that

@example
erfc (@var{y}) == @var{x}
@end example
@seealso{@ref{XREFerfc,,erfc}, @ref{XREFerf,,erf}, @ref{XREFerfcx,,erfcx}, @ref{XREFerfi,,erfi}, @ref{XREFdawson,,dawson}, @ref{XREFerfinv,,erfinv}}
@end deftypefn


@c expint scripts/specfun/expint.m
@anchor{XREFexpint}
@deftypefn {Function File} {} expint (@var{x})
Compute the exponential integral:
@tex
$$
{\rm E_1} (x) = \int_x^\infty {e^{-t} \over t} dt
$$
@end tex
@ifnottex

@example
@group
           infinity
          /
E_1 (x) = | exp (-t)/t dt
          /
         x
@end group
@end example

@end ifnottex
Note: For compatibility, this functions uses the @sc{matlab} definition
of the exponential integral.  Most other sources refer to this particular
value as @math{E_1 (x)}, and the exponential integral is
@tex
$$
{\rm Ei} (x) = - \int_{-x}^\infty {e^{-t} \over t} dt.
$$
@end tex
@ifnottex

@example
@group
            infinity
           /
Ei (x) = - | exp (-t)/t dt
           /
         -x
@end group
@end example

@end ifnottex
The two definitions are related, for positive real values of @var{x}, by
@tex
$
E_1 (-x) = -{\rm Ei} (x) - i\pi.
$
@end tex
@ifnottex
@w{@code{E_1 (-x) = -Ei (x) - i*pi}}.
@end ifnottex
@end deftypefn


@c gamma libinterp/corefcn/mappers.cc
@anchor{XREFgamma}
@deftypefn {Mapping Function} {} gamma (@var{z})
Compute the Gamma function,
@tex
$$
 \Gamma (z) = \int_0^\infty t^{z-1} e^{-t} dt.
$$
@end tex
@ifnottex

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

@end ifnottex
@seealso{@ref{XREFgammainc,,gammainc}, @ref{XREFlgamma,,lgamma}}
@end deftypefn


@c gammainc libinterp/corefcn/gammainc.cc
@anchor{XREFgammainc}
@deftypefn  {Mapping Function} {} gammainc (@var{x}, @var{a})
@deftypefnx {Mapping Function} {} gammainc (@var{x}, @var{a}, "lower")
@deftypefnx {Mapping Function} {} gammainc (@var{x}, @var{a}, "upper")
Compute the normalized incomplete gamma function,
@tex
$$
 \gamma (x, a) = {1 \over {\Gamma (a)}}\displaystyle{\int_0^x t^{a-1} e^{-t} dt}
$$
@end tex
@ifnottex

@example
@group
                                x
                       1       /
gammainc (x, a) = ---------    | exp (-t) t^(a-1) dt
                  gamma (a)    /
                            t=0
@end group
@end example

@end ifnottex
with the limiting value of 1 as @var{x} approaches infinity.
The standard notation is @math{P(a,x)}, e.g., Abramowitz and Stegun (6.5.1).

If @var{a} is scalar, then @code{gammainc (@var{x}, @var{a})} is returned
for each element of @var{x} and vice versa.

If neither @var{x} nor @var{a} is scalar, the sizes of @var{x} and
@var{a} must agree, and @code{gammainc} is applied element-by-element.

By default the incomplete gamma function integrated from 0 to @var{x} is
computed.  If @qcode{"upper"} is given then the complementary function
integrated from @var{x} to infinity is calculated.  It should be noted that

@example
gammainc (@var{x}, @var{a}) @equiv{} 1 - gammainc (@var{x}, @var{a}, "upper")
@end example
@seealso{@ref{XREFgamma,,gamma}, @ref{XREFlgamma,,lgamma}}
@end deftypefn


@c legendre scripts/specfun/legendre.m
@anchor{XREFlegendre}
@deftypefn  {Function File} {@var{l} =} legendre (@var{n}, @var{x})
@deftypefnx {Function File} {@var{l} =} legendre (@var{n}, @var{x}, @var{normalization})
Compute the Legendre function of degree @var{n} and order
@var{m} = 0 @dots{} N@.  The optional argument, @var{normalization},
may be one of @qcode{"unnorm"}, @qcode{"sch"}, or @qcode{"norm"}.
The default is @qcode{"unnorm"}.  The value of @var{n} must be a
non-negative scalar integer.

If the optional argument @var{normalization} is missing or is
@qcode{"unnorm"}, compute the Legendre function of degree @var{n} and
order @var{m} and return all values for @var{m} = 0 @dots{} @var{n}.
The return value has one dimension more than @var{x}.

The Legendre Function of degree @var{n} and order @var{m}:

@tex
$$
P^m_n(x) = (-1)^m (1-x^2)^{m/2}{d^m\over {dx^m}}P_n (x)
$$
@end tex
@ifnottex

@example
@group
 m        m       2  m/2   d^m
P(x) = (-1) * (1-x  )    * ----  P(x)
 n                         dx^m   n
@end group
@end example

@end ifnottex

@noindent
with Legendre polynomial of degree @var{n}:

@tex
$$
P(x) = {1\over{2^n n!}}\biggl({d^n\over{dx^n}}(x^2 - 1)^n\biggr)
$$
@end tex
@ifnottex

@example
@group
          1    d^n   2    n
P(x) = ------ [----(x - 1) ]
 n     2^n n!  dx^n
@end group
@end example

@end ifnottex

@noindent
@code{legendre (3, [-1.0, -0.9, -0.8])} returns the matrix:

@example
@group
 x  |   -1.0   |   -0.9   |   -0.8
------------------------------------
m=0 | -1.00000 | -0.47250 | -0.08000
m=1 |  0.00000 | -1.99420 | -1.98000
m=2 |  0.00000 | -2.56500 | -4.32000
m=3 |  0.00000 | -1.24229 | -3.24000
@end group
@end example

If the optional argument @code{normalization} is @qcode{"sch"},
compute the Schmidt semi-normalized associated Legendre function.
The Schmidt semi-normalized associated Legendre function is related
to the unnormalized Legendre functions by the following:

For Legendre functions of degree n and order 0:

@tex
$$
SP^0_n (x) = P^0_n (x)
$$
@end tex
@ifnottex

@example
@group
  0      0
SP(x) = P(x)
  n      n
@end group
@end example

@end ifnottex

For Legendre functions of degree n and order m:

@tex
$$
SP^m_n (x) = P^m_n (x)(-1)^m\biggl({2(n-m)!\over{(n+m)!}}\biggl)^{0.5}
$$
@end tex
@ifnottex

@example
@group
  m      m         m    2(n-m)! 0.5
SP(x) = P(x) * (-1)  * [-------]
  n      n              (n+m)!
@end group
@end example

@end ifnottex

If the optional argument @var{normalization} is @qcode{"norm"},
compute the fully normalized associated Legendre function.
The fully normalized associated Legendre function is related
to the unnormalized Legendre functions by the following:

For Legendre functions of degree @var{n} and order @var{m}

@tex
$$
NP^m_n (x) = P^m_n (x)(-1)^m\biggl({(n+0.5)(n-m)!\over{(n+m)!}}\biggl)^{0.5}
$$
@end tex
@ifnottex

@example
@group
  m      m         m    (n+0.5)(n-m)! 0.5
NP(x) = P(x) * (-1)  * [-------------]
  n      n                  (n+m)!
@end group
@end example

@end ifnottex
@end deftypefn


@anchor{XREFgammaln}
@c lgamma libinterp/corefcn/mappers.cc
@anchor{XREFlgamma}
@deftypefn  {Mapping Function} {} lgamma (@var{x})
@deftypefnx {Mapping Function} {} gammaln (@var{x})
Return the natural logarithm of the gamma function of @var{x}.
@seealso{@ref{XREFgamma,,gamma}, @ref{XREFgammainc,,gammainc}}
@end deftypefn


@node Rational Approximations
@section Rational Approximations

@c rat scripts/general/rat.m
@anchor{XREFrat}
@deftypefn  {Function File} {@var{s} =} rat (@var{x}, @var{tol})
@deftypefnx {Function File} {[@var{n}, @var{d}] =} rat (@var{x}, @var{tol})

Find a rational approximation to @var{x} within the tolerance defined
by @var{tol} using a continued fraction expansion.  For example:

@example
@group
rat (pi) = 3 + 1/(7 + 1/16) = 355/113
rat (e) = 3 + 1/(-4 + 1/(2 + 1/(5 + 1/(-2 + 1/(-7)))))
        = 1457/536
@end group
@end example

Called with two arguments returns the numerator and denominator separately
as two matrices.
@seealso{@ref{XREFrats,,rats}}
@end deftypefn


@c rats libinterp/corefcn/pr-output.cc
@anchor{XREFrats}
@deftypefn {Built-in Function} {} rats (@var{x}, @var{len})
Convert @var{x} into a rational approximation represented as a string.
You can convert the string back into a matrix as follows:

@example
@group
r = rats (hilb (4));
x = str2num (r)
@end group
@end example

The optional second argument defines the maximum length of the string
representing the elements of @var{x}.  By default @var{len} is 9.
@seealso{@ref{XREFformat,,format}, @ref{XREFrat,,rat}}
@end deftypefn


@node Coordinate Transformations
@section Coordinate Transformations

@c cart2pol scripts/general/cart2pol.m
@anchor{XREFcart2pol}
@deftypefn  {Function File} {[@var{theta}, @var{r}] =} cart2pol (@var{x}, @var{y})
@deftypefnx {Function File} {[@var{theta}, @var{r}, @var{z}] =} cart2pol (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {[@var{theta}, @var{r}] =} cart2pol (@var{C})
@deftypefnx {Function File} {[@var{theta}, @var{r}, @var{z}] =} cart2pol (@var{C})
@deftypefnx {Function File} {@var{P} =} cart2pol (@dots{})

Transform Cartesian to polar or cylindrical coordinates.

@var{theta} describes the angle relative to the positive x-axis.
@var{r} is the distance to the z-axis @w{(0, 0, z)}.
@var{x}, @var{y} (, and @var{z}) must be the same shape, or scalar.
If called with a single matrix argument then each row of @var{C}
represents the Cartesian coordinate (@var{x}, @var{y} (, @var{z})).

If only a single return argument is requested then return a matrix
@var{P} where each row represents one polar/(cylindrical) coordinate
(@var{theta}, @var{phi} (, @var{z})).
@seealso{@ref{XREFpol2cart,,pol2cart}, @ref{XREFcart2sph,,cart2sph}, @ref{XREFsph2cart,,sph2cart}}
@end deftypefn


@c pol2cart scripts/general/pol2cart.m
@anchor{XREFpol2cart}
@deftypefn  {Function File} {[@var{x}, @var{y}] =} pol2cart (@var{theta}, @var{r})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} pol2cart (@var{theta}, @var{r}, @var{z})
@deftypefnx {Function File} {[@var{x}, @var{y}] =} pol2cart (@var{P})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} pol2cart (@var{P})
@deftypefnx {Function File} {@var{C} =} pol2cart (@dots{})
Transform polar or cylindrical to Cartesian coordinates.

@var{theta}, @var{r}, (and @var{z}) must be the same shape, or scalar.
@var{theta} describes the angle relative to the positive x-axis.
@var{r} is the distance to the z-axis (0, 0, z).
If called with a single matrix argument then each row of @var{P}
represents the polar/(cylindrical) coordinate (@var{theta}, @var{r} (,
@var{z})).

If only a single return argument is requested then return a matrix
@var{C} where each row represents one Cartesian coordinate
(@var{x}, @var{y} (, @var{z})).
@seealso{@ref{XREFcart2pol,,cart2pol}, @ref{XREFsph2cart,,sph2cart}, @ref{XREFcart2sph,,cart2sph}}
@end deftypefn


@c cart2sph scripts/general/cart2sph.m
@anchor{XREFcart2sph}
@deftypefn  {Function File} {[@var{theta}, @var{phi}, @var{r}] =} cart2sph (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {[@var{theta}, @var{phi}, @var{r}] =} cart2sph (@var{C})
@deftypefnx {Function File} {@var{S} =} cart2sph (@dots{})
Transform Cartesian to spherical coordinates.

@var{theta} describes the angle relative to the positive x-axis.
@var{phi} is the angle relative to the xy-plane.
@var{r} is the distance to the origin @w{(0, 0, 0)}.
@var{x}, @var{y}, and @var{z} must be the same shape, or scalar.
If called with a single matrix argument then each row of @var{C}
represents the Cartesian coordinate (@var{x}, @var{y}, @var{z}).

If only a single return argument is requested then return a matrix
@var{S} where each row represents one spherical coordinate
(@var{theta}, @var{phi}, @var{r}).
@seealso{@ref{XREFsph2cart,,sph2cart}, @ref{XREFcart2pol,,cart2pol}, @ref{XREFpol2cart,,pol2cart}}
@end deftypefn


@c sph2cart scripts/general/sph2cart.m
@anchor{XREFsph2cart}
@deftypefn  {Function File} {[@var{x}, @var{y}, @var{z}] =} sph2cart (@var{theta}, @var{phi}, @var{r})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} sph2cart (@var{S})
@deftypefnx {Function File} {@var{C} =} sph2cart (@dots{})
Transform spherical to Cartesian coordinates.

@var{theta} describes the angle relative to the positive x-axis.
@var{phi} is the angle relative to the xy-plane.
@var{r} is the distance to the origin @w{(0, 0, 0)}.
@var{theta}, @var{phi}, and @var{r} must be the same shape, or scalar.
If called with a single matrix argument then each row of @var{S}
represents the spherical coordinate (@var{theta}, @var{phi}, @var{r}).

If only a single return argument is requested then return a matrix
@var{C} where each row represents one Cartesian coordinate
(@var{x}, @var{y}, @var{z}).
@seealso{@ref{XREFcart2sph,,cart2sph}, @ref{XREFpol2cart,,pol2cart}, @ref{XREFcart2pol,,cart2pol}}
@end deftypefn


@node Mathematical Constants
@section Mathematical Constants

@c e libinterp/corefcn/data.cc
@anchor{XREFe}
@deftypefn  {Built-in Function} {} e
@deftypefnx {Built-in Function} {} e (@var{n})
@deftypefnx {Built-in Function} {} e (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} e (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} e (@dots{}, @var{class})
Return a scalar, matrix, or N-dimensional array whose elements are all equal
to the base of natural logarithms.  The constant
@tex
$e$ satisfies the equation $\log (e) = 1$.
@end tex
@ifnottex
@samp{e} satisfies the equation @code{log} (e) = 1.
@end ifnottex

When called with no arguments, return a scalar with the value @math{e}.  When
called with a single argument, return a square matrix with the dimension
specified.  When called with more than one scalar argument the first two
arguments are taken as the number of rows and columns and any further
arguments specify additional matrix dimensions.
The optional argument @var{class} specifies the return type and may be
either @qcode{"double"} or @qcode{"single"}.
@seealso{@ref{XREFlog,,log}, @ref{XREFexp,,exp}, @ref{XREFpi,,pi}, @ref{XREFI,,I}}
@end deftypefn


@c pi libinterp/corefcn/data.cc
@anchor{XREFpi}
@deftypefn  {Built-in Function} {} pi
@deftypefnx {Built-in Function} {} pi (@var{n})
@deftypefnx {Built-in Function} {} pi (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} pi (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} pi (@dots{}, @var{class})
Return a scalar, matrix, or N-dimensional array whose elements are all equal
to the ratio of the circumference of a circle to its
@tex
diameter($\pi$).
@end tex
@ifnottex
diameter.
@end ifnottex
Internally, @code{pi} is computed as @samp{4.0 * atan (1.0)}.

When called with no arguments, return a scalar with the value of
@tex
$\pi$.
@end tex
@ifnottex
pi.
@end ifnottex
When called with a single argument, return a square matrix with the dimension
specified.  When called with more than one scalar argument the first two
arguments are taken as the number of rows and columns and any further
arguments specify additional matrix dimensions.
The optional argument @var{class} specifies the return type and may be
either @qcode{"double"} or @qcode{"single"}.
@seealso{@ref{XREFe,,e}, @ref{XREFI,,I}}
@end deftypefn


@c I libinterp/corefcn/data.cc
@anchor{XREFI}
@c List other forms of function in documentation index
@findex i
@findex j
@findex J

@deftypefn  {Built-in Function} {} I
@deftypefnx {Built-in Function} {} I (@var{n})
@deftypefnx {Built-in Function} {} I (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} I (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} I (@dots{}, @var{class})
Return a scalar, matrix, or N-dimensional array whose elements are all equal
to the pure imaginary unit, defined as
@tex
$\sqrt{-1}$.
@end tex
@ifnottex
@code{sqrt (-1)}.
@end ifnottex

I, and its equivalents i, j, and J, are functions so any of the names may
be reused for other purposes (such as i for a counter variable).

When called with no arguments, return a scalar with the value @math{i}.  When
called with a single argument, return a square matrix with the dimension
specified.  When called with more than one scalar argument the first two
arguments are taken as the number of rows and columns and any further
arguments specify additional matrix dimensions.
The optional argument @var{class} specifies the return type and may be
either @qcode{"double"} or @qcode{"single"}.
@seealso{@ref{XREFe,,e}, @ref{XREFpi,,pi}, @ref{XREFlog,,log}, @ref{XREFexp,,exp}}
@end deftypefn


@c Inf libinterp/corefcn/data.cc
@anchor{XREFInf}
@c List other form of function in documentation index
@findex inf

@deftypefn  {Built-in Function} {} Inf
@deftypefnx {Built-in Function} {} Inf (@var{n})
@deftypefnx {Built-in Function} {} Inf (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} Inf (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} Inf (@dots{}, @var{class})
Return a scalar, matrix or N-dimensional array whose elements are all equal
to the IEEE representation for positive infinity.

Infinity is produced when results are too large to be represented using the
the IEEE floating point format for numbers.  Two common examples which
produce infinity are division by zero and overflow.

@example
@group
[ 1/0 e^800 ]
@result{} Inf   Inf
@end group
@end example

When called with no arguments, return a scalar with the value @samp{Inf}.
When called with a single argument, return a square matrix with the dimension
specified.  When called with more than one scalar argument the first two
arguments are taken as the number of rows and columns and any further
arguments specify additional matrix dimensions.
The optional argument @var{class} specifies the return type and may be
either @qcode{"double"} or @qcode{"single"}.
@seealso{@ref{XREFisinf,,isinf}, @ref{XREFNaN,,NaN}}
@end deftypefn


@c NaN libinterp/corefcn/data.cc
@anchor{XREFNaN}
@c List other form of function in documentation index
@findex nan

@deftypefn  {Built-in Function} {} NaN
@deftypefnx {Built-in Function} {} NaN (@var{n})
@deftypefnx {Built-in Function} {} NaN (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} NaN (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} NaN (@dots{}, @var{class})
Return a scalar, matrix, or N-dimensional array whose elements are all equal
to the IEEE symbol NaN (Not a Number).
NaN is the result of operations which do not produce a well defined numerical
result.  Common operations which produce a NaN are arithmetic with infinity
@tex
($\infty - \infty$), zero divided by zero ($0/0$),
@end tex
@ifnottex
(Inf - Inf), zero divided by zero (0/0),
@end ifnottex
and any operation involving another NaN value (5 + NaN).

Note that NaN always compares not equal to NaN (NaN != NaN).  This behavior
is specified by the IEEE standard for floating point arithmetic.  To
find NaN values, use the @code{isnan} function.

When called with no arguments, return a scalar with the value @samp{NaN}.
When called with a single argument, return a square matrix with the dimension
specified.  When called with more than one scalar argument the first two
arguments are taken as the number of rows and columns and any further
arguments specify additional matrix dimensions.
The optional argument @var{class} specifies the return type and may be
either @qcode{"double"} or @qcode{"single"}.
@seealso{@ref{XREFisnan,,isnan}, @ref{XREFInf,,Inf}}
@end deftypefn


@c eps libinterp/corefcn/data.cc
@anchor{XREFeps}
@deftypefn  {Built-in Function} {} eps
@deftypefnx {Built-in Function} {} eps (@var{x})
@deftypefnx {Built-in Function} {} eps (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} eps (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} eps (@dots{}, @var{class})
Return a scalar, matrix or N-dimensional array whose elements are all eps,
the machine precision.  More precisely, @code{eps} is the relative spacing
between any two adjacent numbers in the machine's floating point system.
This number is obviously system dependent.  On machines that support IEEE
floating point arithmetic, @code{eps} is approximately
@tex
$2.2204\times10^{-16}$ for double precision and $1.1921\times10^{-7}$
@end tex
@ifnottex
2.2204e-16 for double precision and 1.1921e-07
@end ifnottex
for single precision.

When called with no arguments, return a scalar with the value
@code{eps (1.0)}.
Given a single argument @var{x}, return the distance between @var{x} and
the next largest value.
When called with more than one argument the first two arguments are taken as
the number of rows and columns and any further
arguments specify additional matrix dimensions.
The optional argument @var{class} specifies the return type and may be
either @qcode{"double"} or @qcode{"single"}.
@seealso{@ref{XREFrealmax,,realmax}, @ref{XREFrealmin,,realmin}, @ref{XREFintmax,,intmax}, @ref{XREFbitmax,,bitmax}}
@end deftypefn


@c realmax libinterp/corefcn/data.cc
@anchor{XREFrealmax}
@deftypefn  {Built-in Function} {} realmax
@deftypefnx {Built-in Function} {} realmax (@var{n})
@deftypefnx {Built-in Function} {} realmax (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} realmax (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} realmax (@dots{}, @var{class})
Return a scalar, matrix or N-dimensional array whose elements are all equal
to the largest floating point number that is representable.  The actual
value is system dependent.  On machines that support IEEE
floating point arithmetic, @code{realmax} is approximately
@tex
$1.7977\times10^{308}$ for double precision and $3.4028\times10^{38}$
@end tex
@ifnottex
1.7977e+308 for double precision and 3.4028e+38
@end ifnottex
for single precision.

When called with no arguments, return a scalar with the value
@code{realmax (@qcode{"double"})}.
When called with a single argument, return a square matrix with the dimension
specified.  When called with more than one scalar argument the first two
arguments are taken as the number of rows and columns and any further
arguments specify additional matrix dimensions.
The optional argument @var{class} specifies the return type and may be
either @qcode{"double"} or @qcode{"single"}.
@seealso{@ref{XREFrealmin,,realmin}, @ref{XREFintmax,,intmax}, @ref{XREFbitmax,,bitmax}, @ref{XREFeps,,eps}}
@end deftypefn


@c realmin libinterp/corefcn/data.cc
@anchor{XREFrealmin}
@deftypefn  {Built-in Function} {} realmin
@deftypefnx {Built-in Function} {} realmin (@var{n})
@deftypefnx {Built-in Function} {} realmin (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} realmin (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} realmin (@dots{}, @var{class})
Return a scalar, matrix or N-dimensional array whose elements are all equal
to the smallest normalized floating point number that is representable.
The actual value is system dependent.  On machines that support
IEEE floating point arithmetic, @code{realmin} is approximately
@tex
$2.2251\times10^{-308}$ for double precision and $1.1755\times10^{-38}$
@end tex
@ifnottex
2.2251e-308 for double precision and 1.1755e-38
@end ifnottex
for single precision.

When called with no arguments, return a scalar with the value
@code{realmin (@qcode{"double"})}.
When called with a single argument, return a square matrix with the dimension
specified.  When called with more than one scalar argument the first two
arguments are taken as the number of rows and columns and any further
arguments specify additional matrix dimensions.
The optional argument @var{class} specifies the return type and may be
either @qcode{"double"} or @qcode{"single"}.
@seealso{@ref{XREFrealmax,,realmax}, @ref{XREFintmin,,intmin}, @ref{XREFeps,,eps}}
@end deftypefn