octave: Special Utility Matrices
16.3 Special Utility Matrices
=============================
-- : eye (N)
-- : eye (M, N)
-- : eye ([M N])
-- : eye (..., CLASS)
Return an identity matrix.
If invoked with a single scalar argument N, return a square NxN
identity matrix.
If supplied two scalar arguments (M, N), ‘eye’ takes them to be the
number of rows and columns. If given a vector with two elements,
‘eye’ uses the values of the elements as the number of rows and
columns, respectively. For example:
eye (3)
⇒ 1 0 0
0 1 0
0 0 1
The following expressions all produce the same result:
eye (2)
≡
eye (2, 2)
≡
eye (size ([1, 2; 3, 4]))
The optional argument CLASS, allows ‘eye’ to return an array of the
specified type, like
val = zeros (n,m, "uint8")
Calling ‘eye’ with no arguments is equivalent to calling it with an
argument of 1. Any negative dimensions are treated as zero. These
odd definitions are for compatibility with MATLAB.
DONTPRINTYET See also: 
speye XREFspeye, ones XREFones, *noteDONTPRINTYET See also: speye XREFspeye, ones XREFones,
zeros XREFzeros.
-- : ones (N)
-- : ones (M, N)
-- : ones (M, N, K, ...)
-- : ones ([M N ...])
-- : ones (..., CLASS)
Return a matrix or N-dimensional array whose elements are all 1.
If invoked with a single scalar integer argument N, return a square
NxN matrix.
If invoked with two or more scalar integer arguments, or a vector
of integer values, return an array with the given dimensions.
To create a constant matrix whose values are all the same use an
expression such as
val_matrix = val * ones (m, n)
The optional argument CLASS specifies the class of the return array
and defaults to double. For example:
val = ones (m,n, "uint8")
See also: zeros XREFzeros.
-- : zeros (N)
-- : zeros (M, N)
-- : zeros (M, N, K, ...)
-- : zeros ([M N ...])
-- : zeros (..., CLASS)
Return a matrix or N-dimensional array whose elements are all 0.
If invoked with a single scalar integer argument, return a square
NxN matrix.
If invoked with two or more scalar integer arguments, or a vector
of integer values, return an array with the given dimensions.
The optional argument CLASS specifies the class of the return array
and defaults to double. For example:
val = zeros (m,n, "uint8")
See also: ones XREFones.
-- : repmat (A, M)
-- : repmat (A, M, N)
-- : repmat (A, M, N, P ...)
-- : repmat (A, [M N])
-- : repmat (A, [M N P ...])
Repeat matrix or N-D array.
Form a block matrix of size M by N, with a copy of matrix A as each
element.
If N is not specified, form an M by M block matrix. For copying
along more than two dimensions, specify the number of times to copy
across each dimension M, N, P, ..., in a vector in the second
argument.
DONTPRINTYET See also: bsxfun XREFbsxfun, kron XREFkron, *noteDONTPRINTYET See also: bsxfun XREFbsxfun, kron XREFkron,
repelems XREFrepelems.
-- : repelems (X, R)
Construct a vector of repeated elements from X.
R is a 2xN integer matrix specifying which elements to repeat and
how often to repeat each element. Entries in the first row,
R(1,j), select an element to repeat. The corresponding entry in
the second row, R(2,j), specifies the repeat count. If X is a
matrix then the columns of X are imagined to be stacked on top of
each other for purposes of the selection index. A row vector is
always returned.
Conceptually the result is calculated as follows:
y = [];
for i = 1:columns (R)
y = [y, X(R(1,i)*ones(1, R(2,i)))];
endfor
See also: repmat XREFrepmat, cat XREFcat.
The functions ‘linspace’ and ‘logspace’ make it very easy to create
vectors with evenly or logarithmically spaced elements. Ranges.
-- : linspace (START, END)
-- : linspace (START, END, N)
Return a row vector with N linearly spaced elements between START
and END.
If the number of elements is greater than one, then the endpoints
START and END are always included in the range. If START is
greater than END, the elements are stored in decreasing order. If
the number of points is not specified, a value of 100 is used.
The ‘linspace’ function returns a row vector when both START and
END are scalars. If one, or both, inputs are vectors, then
‘linspace’ transforms them to column vectors and returns a matrix
where each row is an independent sequence between
‘START(ROW_N), END(ROW_N)’.
For compatibility with MATLAB, return the second argument (END)
when only a single value (N = 1) is requested.
See also: colon XREFcolon, logspace XREFlogspace.
-- : logspace (A, B)
-- : logspace (A, B, N)
-- : logspace (A, pi, N)
Return a row vector with N elements logarithmically spaced from
10^A to 10^B.
If N is unspecified it defaults to 50.
If B is equal to pi, the points are between 10^A and pi, _not_ 10^A
and 10^pi, in order to be compatible with the corresponding MATLAB
function.
Also for compatibility with MATLAB, return the right-hand side of
the range (10^B) when just a single value is requested.
See also: linspace XREFlinspace.
-- : rand (N)
-- : rand (M, N, ...)
-- : rand ([M N ...])
-- : V = rand ("state")
-- : rand ("state", V)
-- : rand ("state", "reset")
-- : V = rand ("seed")
-- : rand ("seed", V)
-- : rand ("seed", "reset")
-- : rand (..., "single")
-- : rand (..., "double")
Return a matrix with random elements uniformly distributed on the
interval (0, 1).
The arguments are handled the same as the arguments for ‘eye’.
You can query the state of the random number generator using the
form
v = rand ("state")
This returns a column vector V of length 625. Later, you can
restore the random number generator to the state V using the form
rand ("state", v)
You may also initialize the state vector from an arbitrary vector
of length ≤ 625 for V. This new state will be a hash based on the
value of V, not V itself.
By default, the generator is initialized from ‘/dev/urandom’ if it
is available, otherwise from CPU time, wall clock time, and the
current fraction of a second. Note that this differs from MATLAB,
which always initializes the state to the same state at startup.
To obtain behavior comparable to MATLAB, initialize with a
deterministic state vector in Octave’s startup files (Startup
Files).
To compute the pseudo-random sequence, ‘rand’ uses the Mersenne
Twister with a period of 2^{19937}-1 (See M. Matsumoto and T.
Nishimura, ‘Mersenne Twister: A 623-dimensionally equidistributed
uniform pseudorandom number generator’, ACM Trans. on Modeling and
Computer Simulation Vol. 8, No. 1, pp. 3–30, January 1998,
<http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html>). Do
*not* use for cryptography without securely hashing several
returned values together, otherwise the generator state can be
learned after reading 624 consecutive values.
Older versions of Octave used a different random number generator.
The new generator is used by default as it is significantly faster
than the old generator, and produces random numbers with a
significantly longer cycle time. However, in some circumstances it
might be desirable to obtain the same random sequences as produced
by the old generators. To do this the keyword "seed" is used to
specify that the old generators should be used, as in
rand ("seed", val)
which sets the seed of the generator to VAL. The seed of the
generator can be queried with
s = rand ("seed")
However, it should be noted that querying the seed will not cause
‘rand’ to use the old generators, only setting the seed will. To
cause ‘rand’ to once again use the new generators, the keyword
"state" should be used to reset the state of the ‘rand’.
The state or seed of the generator can be reset to a new random
value using the "reset" keyword.
The class of the value returned can be controlled by a trailing
"double" or "single" argument. These are the only valid classes.
DONTPRINTYET See also: randn XREFrandn, rande XREFrande, *noteDONTPRINTYET See also: randn XREFrandn, rande XREFrande,
randg XREFrandg, randp XREFrandp.
-- : randi (IMAX)
-- : randi (IMAX, N)
-- : randi (IMAX, M, N, ...)
-- : randi ([IMIN IMAX], ...)
-- : randi (..., "CLASS")
Return random integers in the range 1:IMAX.
Additional arguments determine the shape of the return matrix.
When no arguments are specified a single random integer is
returned. If one argument N is specified then a square matrix
(N x N) is returned. Two or more arguments will return a
multi-dimensional matrix (M x N x ...).
The integer range may optionally be described by a two element
matrix with a lower and upper bound in which case the returned
integers will be on the interval [IMIN, IMAX].
The optional argument CLASS will return a matrix of the requested
type. The default is "double".
The following example returns 150 integers in the range 1–10.
ri = randi (10, 150, 1)
Implementation Note: ‘randi’ relies internally on ‘rand’ which uses
class "double" to represent numbers. This limits the maximum
integer (IMAX) and range (IMAX - IMIN) to the value returned by the
‘flintmax’ function. For IEEE floating point numbers this value is
2^{53} - 1.
See also: rand XREFrand.
-- : randn (N)
-- : randn (M, N, ...)
-- : randn ([M N ...])
-- : V = randn ("state")
-- : randn ("state", V)
-- : randn ("state", "reset")
-- : V = randn ("seed")
-- : randn ("seed", V)
-- : randn ("seed", "reset")
-- : randn (..., "single")
-- : randn (..., "double")
Return a matrix with normally distributed random elements having
zero mean and variance one.
The arguments are handled the same as the arguments for ‘rand’.
By default, ‘randn’ uses the Marsaglia and Tsang “Ziggurat
technique” to transform from a uniform to a normal distribution.
The class of the value returned can be controlled by a trailing
"double" or "single" argument. These are the only valid classes.
Reference: G. Marsaglia and W.W. Tsang, ‘Ziggurat Method for
Generating Random Variables’, J. Statistical Software, vol 5, 2000,
<http://www.jstatsoft.org/v05/i08/>
DONTPRINTYET See also: rand XREFrand, rande XREFrande, *noteDONTPRINTYET See also: rand XREFrand, rande XREFrande,
randg XREFrandg, randp XREFrandp.
-- : rande (N)
-- : rande (M, N, ...)
-- : rande ([M N ...])
-- : V = rande ("state")
-- : rande ("state", V)
-- : rande ("state", "reset")
-- : V = rande ("seed")
-- : rande ("seed", V)
-- : rande ("seed", "reset")
-- : rande (..., "single")
-- : rande (..., "double")
Return a matrix with exponentially distributed random elements.
The arguments are handled the same as the arguments for ‘rand’.
By default, ‘rande’ uses the Marsaglia and Tsang “Ziggurat
technique” to transform from a uniform to an exponential
distribution.
The class of the value returned can be controlled by a trailing
"double" or "single" argument. These are the only valid classes.
Reference: G. Marsaglia and W.W. Tsang, ‘Ziggurat Method for
Generating Random Variables’, J. Statistical Software, vol 5, 2000,
<http://www.jstatsoft.org/v05/i08/>
DONTPRINTYET See also: rand XREFrand, randn XREFrandn, *noteDONTPRINTYET See also: rand XREFrand, randn XREFrandn,
randg XREFrandg, randp XREFrandp.
-- : randp (L, N)
-- : randp (L, M, N, ...)
-- : randp (L, [M N ...])
-- : V = randp ("state")
-- : randp ("state", V)
-- : randp ("state", "reset")
-- : V = randp ("seed")
-- : randp ("seed", V)
-- : randp ("seed", "reset")
-- : randp (..., "single")
-- : randp (..., "double")
Return a matrix with Poisson distributed random elements with mean
value parameter given by the first argument, L.
The arguments are handled the same as the arguments for ‘rand’,
except for the argument L.
Five different algorithms are used depending on the range of L and
whether or not L is a scalar or a matrix.
For scalar L ≤ 12, use direct method.
W.H. Press, et al., ‘Numerical Recipes in C’, Cambridge
University Press, 1992.
For scalar L > 12, use rejection method.[1]
W.H. Press, et al., ‘Numerical Recipes in C’, Cambridge
University Press, 1992.
For matrix L ≤ 10, use inversion method.[2]
E. Stadlober, et al., WinRand source code, available via FTP.
For matrix L > 10, use patchwork rejection method.
E. Stadlober, et al., WinRand source code, available via FTP,
or H. Zechner, ‘Efficient sampling from continuous and
discrete unimodal distributions’, Doctoral Dissertation,
156pp., Technical University Graz, Austria, 1994.
For L > 1e8, use normal approximation.
L. Montanet, et al., ‘Review of Particle Properties’, Physical
Review D 50 p1284, 1994.
The class of the value returned can be controlled by a trailing
"double" or "single" argument. These are the only valid classes.
DONTPRINTYET See also: rand XREFrand, randn XREFrandn, *noteDONTPRINTYET See also: rand XREFrand, randn XREFrandn,
rande XREFrande, randg XREFrandg.
-- : randg (A, N)
-- : randg (A, M, N, ...)
-- : randg (A, [M N ...])
-- : V = randg ("state")
-- : randg ("state", V)
-- : randg ("state", "reset")
-- : V = randg ("seed")
-- : randg ("seed", V)
-- : randg ("seed", "reset")
-- : randg (..., "single")
-- : randg (..., "double")
Return a matrix with ‘gamma (A,1)’ distributed random elements.
The arguments are handled the same as the arguments for ‘rand’,
except for the argument A.
This can be used to generate many distributions:
‘gamma (a, b)’ for ‘a > -1’, ‘b > 0’
r = b * randg (a)
‘beta (a, b)’ for ‘a > -1’, ‘b > -1’
r1 = randg (a, 1)
r = r1 / (r1 + randg (b, 1))
‘Erlang (a, n)’
r = a * randg (n)
‘chisq (df)’ for ‘df > 0’
r = 2 * randg (df / 2)
‘t (df)’ for ‘0 < df < inf’ (use randn if df is infinite)
r = randn () / sqrt (2 * randg (df / 2) / df)
‘F (n1, n2)’ for ‘0 < n1’, ‘0 < n2’
## r1 equals 1 if n1 is infinite
r1 = 2 * randg (n1 / 2) / n1
## r2 equals 1 if n2 is infinite
r2 = 2 * randg (n2 / 2) / n2
r = r1 / r2
negative ‘binomial (n, p)’ for ‘n > 0’, ‘0 < p <= 1’
r = randp ((1 - p) / p * randg (n))
non-central ‘chisq (df, L)’, for ‘df >= 0’ and ‘L > 0’
(use chisq if ‘L = 0’)
r = randp (L / 2)
r(r > 0) = 2 * randg (r(r > 0))
r(df > 0) += 2 * randg (df(df > 0)/2)
‘Dirichlet (a1, ... ak)’
r = (randg (a1), ..., randg (ak))
r = r / sum (r)
The class of the value returned can be controlled by a trailing
"double" or "single" argument. These are the only valid classes.
DONTPRINTYET See also: rand XREFrand, randn XREFrandn, *noteDONTPRINTYET See also: rand XREFrand, randn XREFrandn,
rande XREFrande, randp XREFrandp.
The generators operate in the new or old style together, it is not
possible to mix the two. Initializing any generator with "state" or
"seed" causes the others to switch to the same style for future calls.
The state of each generator is independent and calls to different
generators can be interleaved without affecting the final result. For
example,
rand ("state", [11, 22, 33]);
randn ("state", [44, 55, 66]);
u = rand (100, 1);
n = randn (100, 1);
and
rand ("state", [11, 22, 33]);
randn ("state", [44, 55, 66]);
u = zeros (100, 1);
n = zeros (100, 1);
for i = 1:100
u(i) = rand ();
n(i) = randn ();
end
produce equivalent results. When the generators are initialized in the
old style with "seed" only ‘rand’ and ‘randn’ are independent, because
the old ‘rande’, ‘randg’ and ‘randp’ generators make calls to ‘rand’ and
‘randn’.
The generators are initialized with random states at start-up, so
that the sequences of random numbers are not the same each time you run
Octave.(1) If you really do need to reproduce a sequence of numbers
exactly, you can set the state or seed to a specific value.
If invoked without arguments, ‘rand’ and ‘randn’ return a single
element of a random sequence.
The original ‘rand’ and ‘randn’ functions use Fortran code from
RANLIB, a library of Fortran routines for random number generation,
compiled by Barry W. Brown and James Lovato of the Department of
Biomathematics at The University of Texas, M.D. Anderson Cancer Center,
Houston, TX 77030.
-- : randperm (N)
-- : randperm (N, M)
Return a row vector containing a random permutation of ‘1:N’.
If M is supplied, return M unique entries, sampled without
replacement from ‘1:N’.
The complexity is O(N) in memory and O(M) in time, unless M < N/5,
in which case O(M) memory is used as well. The randomization is
performed using rand(). All permutations are equally likely.
See also: perms XREFperms.
---------- Footnotes ----------
(1) The old versions of ‘rand’ and ‘randn’ obtain their initial seeds
from the system clock.
Info Catalog
octave: Rearranging Matrices
octave: Matrix Manipulation
octave: Famous Matrices