GNU Octave Manual Version 3by John W. Eaton, David Bateman, Søren Hauberg Paperback (6"x9"), 568 pages ISBN 095461206X RRP £24.95 ($39.95) |

## 17.1 Utility Functions

__Mapping Function:__**ceil***(*`x`)- Return the smallest integer not less than
`x`. If`x`is complex, return`ceil (real (`

.`x`)) + ceil (imag (`x`)) * I

__Function File:__**cplxpair***(*`z`,`tol`,`dim`)- Sort the numbers
`z`into complex conjugate pairs ordered by increasing real part. With identical real parts, order by increasing imaginary magnitude. Place the negative imaginary complex number first within each pair. Place all the real numbers after all the complex pairs (those with`abs (imag (`

, where the default value of`z`) /`z`) <`tol`)`tol`is`100 *`

.`eps`By default the complex pairs are sorted along the first non-singleton dimension of

`z`. If`dim`is specified, then the complex pairs are sorted along this dimension.Signal an error if some complex numbers could not be paired. Requires all complex numbers to be exact conjugates within tol, or signals an error. Note that there are no guarantees on the order of the returned pairs with identical real parts but differing imaginary parts.

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

__Function File:__`d`=**del2***(*`m`)__Function File:__`d`=**del2***(*`m`,`h`)__Function File:__`d`=**del2***(*`m`,`dx`,`dy`, ...)-
Calculates the discrete Laplace operator. If

`m`is a matrix this is defined as1 / d^2 d^2 \ D = -- * | -- M(x,y) + -- M(x,y) | 4 \ dx^2 dy^2 /

where the derivatives are calculated as finite difference approximations. The formula above is extended to N-dimensional arrays by calculating the second derivative over the higher dimensions.

The spacing between evaluation points may be defined by

`h`, which is a scalar defining the spacing in all dimensions. Or alternatively, the spacing in each dimension may be defined separately by`dx`,`dy`, etc. Scalar spacing values give equidistant spacing, whereas vector spacing values can be used to specify variable spacing. The length of the vectors must match the respective dimension of`m`. The default spacing value is 1.You need at least 3 data points for each dimension. Boundary points are calculated as the linear extrapolation of the interior points.

See also gradient, diff

__Mapping Function:__**exp***(*`x`)- Compute the exponential of
`x`. To compute the matrix exponential, see section 18 Linear Algebra.

__Function File:__`p`=**factor***(*`q`)__Function File:__[`p`,`n`] =**factor***(*`q`)-
Return prime factorization of

`q`. That is`prod (`

. If`p`) ==`q`

, returns 1.`q`== 1With two output arguments, returns the unique primes

`p`and their multiplicities. That is`prod (`

.`p`.^`n`) ==`q`

__Function File:__**factorial***(*`n`)- Return the factorial of
`n`. If`n`is scalar, this is equivalent to`prod (1:`

. If`n`)`n`is an array, the factorial of the elements of the array are returned.

__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:__**fmod***(*`x`,`y`)- Compute the floating point remainder of dividing
`x`by`y`using the C library function`fmod`

. The result has the same sign as`x`. If`y`is zero, the result is implementation-defined.

__Loadable Function:__`g`=**gcd***(*`a1`, ...)__Loadable Function:__[`g`,`v1`, ...] =**gcd***(*`a1`, ...)-
If a single argument is given then compute the greatest common divisor of the elements of this argument. Otherwise 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 element individually. All elements must be integers. For example,

gcd ([15, 20]) => 5

and

gcd ([15, 9], [20 18]) => 5 9

Optional return arguments

`v1`, etc, contain integer vectors such that,`g`=`v1`.*`a1`+`v2`.*`a2`+ ...For backward compatibility with previous versions of this function, when all arguments are scalar, a single return argument

`v1`containing all of the values of`v1`, ... is acceptable.See also lcm, min, max, ceil, floor

__Function File:__`x`=**gradient***(*`M`)__Function File:__[`x`,`y`, ...] =**gradient***(*`M`)__Function File:__[...] =**gradient***(*`M`,`s`)__Function File:__[...] =**gradient***(*`M`,`dx`,`dy`, ...)-
Calculates the gradient.

calculates the one dimensional gradient if`x`= gradient (`M`)`M`is a vector. If`M`is a matrix the gradient is calculated for each row.`[`

calculates the one dimensional gradient for each direction if`x`,`y`] = gradient (`M`)`M`if`M`is a matrix. Additional return arguments can be use for multi-dimensional matrices.Spacing values between two points can be provided by the

`dx`,`dy`or`h`parameters. If`h`is supplied it is assumed to be the spacing in all directions. Otherwise, separate values of the spacing can be supplied by the`dx`, etc variables. A scalar value specifies an equidistant spacing, while a vector value can be used to specify a variable spacing. The length must match their respective dimension of`M`.At boundary points a linear extrapolation is applied. Interior points are calculated with the first approximation of the numerical gradient

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

__Mapping Function:__**lcm***(*`x`, ...)- Compute the least common multiple of the elements of
`x`, or the list of all the arguments. For example,lcm (a1, ..., ak)

is the same as

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

All elements must be the same size or scalar.

See also gcd, min, max, ceil, floor

__Mapping Function:__**log***(*`x`)- Compute the natural logarithm for each element of
`x`. To compute the matrix logarithm, see section 18 Linear Algebra.See also log2, log10, logspace, exp

__Mapping Function:__**log10***(*`x`)- Compute the base-10 logarithm for each element of
`x`.See also log, log2, logspace, exp

__Mapping Function:__**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.See also log, log10, logspace, exp

__Mapping Function:__**max***(*`x`,`y`,`dim`)__Mapping Function:__[`w`,`iw`] =**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, or over the dimension
`dim`if defined. For two matrices (or a matrix and scalar), return the pair-wise maximum. Thus,max (max (

`x`))returns the largest element of

`x`, andmax (2:5, pi) => 3.1416 3.1416 4.0000 5.0000

compares each element of the range

`2:5`

with`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,

`max`

also returns the first index of the maximum value(s). Thus,[x, ix] = max ([1, 3, 5, 2, 5]) => x = 5 ix = 3

__Mapping Function:__**min***(*`x`,`y`,`dim`)__Mapping Function:__[`w`,`iw`] =**min***(*`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
`dim`if defined. For two matrices (or a matrix and scalar), return the pair-wise minimum. Thus,min (min (

`x`))returns the smallest element of

`x`, andmin (2:5, pi) => 2.0000 3.0000 3.1416 3.1416

compares each element of the range

`2:5`

with`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,

`min`

also returns the first index of the minimum value(s). Thus,[x, ix] = min ([1, 3, 0, 2, 5]) => x = 0 ix = 3

__Mapping Function:__**mod***(*`x`,`y`)- Compute modulo function. Conceptually this is given by
x - y .* floor (x ./ y)

and is written in a manner that the correct modulus is returned for integer types. This function handles negative values correctly. That is

`mod (-1, 3)`

is 2, not -1 as`rem (-1, 3)`

returns. Also,`mod (`

returns`x`, 0)`x`.An error message is printed if the dimensions of the arguments do not agree, or if either of the arguments is complex.

See also rem, round

__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`))See also pow2

__Function File:__**nthroot***(*`x`,`n`)-
Compute the n-th root of

`x`, returning real results for real components of`x`. For examplenthroot (-1, 3) => -1 (-1) ^ (1 / 3) => 0.50000 - 0.86603i

__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).See also nextpow2

__Function File:__**primes***(*`n`)-
Return all primes up to

`n`.Note that if you need a specific number of primes, you can use the fact the distance from one prime to the next is on average proportional to the logarithm of the prime. Integrating, you find that there are about k primes less than k \log ( 5 k ).

The algorithm used is called the Sieve of Erastothenes.

__Mapping Function:__**rem***(*`x`,`y`)- Return the remainder of

, computed using the expression`x`/`y`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.

See also mod, round

__Mapping Function:__**round***(*`x`)- Return the integer nearest to
`x`. If`x`is complex, return`round (real (`

.`x`)) + round (imag (`x`)) * ISee also rem

__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 section 18 Linear Algebra.

ISBN 095461206X | GNU Octave Manual Version 3 | See the print edition |