<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Special Utility Matrices (GNU Octave (version 5.1.0))</title>
<meta name="description" content="Special Utility Matrices (GNU Octave (version 5.1.0))">
<meta name="keywords" content="Special Utility Matrices (GNU Octave (version 5.1.0))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Matrix-Manipulation.html#Matrix-Manipulation" rel="up" title="Matrix Manipulation">
<link href="Famous-Matrices.html#Famous-Matrices" rel="next" title="Famous Matrices">
<link href="Rearranging-Matrices.html#Rearranging-Matrices" rel="prev" title="Rearranging Matrices">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">
</head>
<body lang="en">
<a name="Special-Utility-Matrices"></a>
<div class="header">
<p>
Next: <a href="Famous-Matrices.html#Famous-Matrices" accesskey="n" rel="next">Famous Matrices</a>, Previous: <a href="Rearranging-Matrices.html#Rearranging-Matrices" accesskey="p" rel="prev">Rearranging Matrices</a>, Up: <a href="Matrix-Manipulation.html#Matrix-Manipulation" accesskey="u" rel="up">Matrix Manipulation</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Special-Utility-Matrices-1"></a>
<h3 class="section">16.3 Special Utility Matrices</h3>
<a name="XREFeye"></a><dl>
<dt><a name="index-eye"></a><em></em> <strong>eye</strong> <em>(<var>n</var>)</em></dt>
<dt><a name="index-eye-1"></a><em></em> <strong>eye</strong> <em>(<var>m</var>, <var>n</var>)</em></dt>
<dt><a name="index-eye-2"></a><em></em> <strong>eye</strong> <em>([<var>m</var> <var>n</var>])</em></dt>
<dt><a name="index-eye-3"></a><em></em> <strong>eye</strong> <em>(…, <var>class</var>)</em></dt>
<dd><p>Return an identity matrix.
</p>
<p>If invoked with a single scalar argument <var>n</var>, return a square
NxN identity matrix.
</p>
<p>If supplied two scalar arguments (<var>m</var>, <var>n</var>), <code>eye</code> takes them
to be the number of rows and columns. If given a vector with two elements,
<code>eye</code> uses the values of the elements as the number of rows and
columns, respectively. For example:
</p>
<div class="example">
<pre class="example">eye (3)
⇒ 1 0 0
0 1 0
0 0 1
</pre></div>
<p>The following expressions all produce the same result:
</p>
<div class="example">
<pre class="example">eye (2)
≡
eye (2, 2)
≡
eye (size ([1, 2; 3, 4]))
</pre></div>
<p>The optional argument <var>class</var>, allows <code>eye</code> to return an array of
the specified type, like
</p>
<div class="example">
<pre class="example">val = zeros (n,m, "uint8")
</pre></div>
<p>Calling <code>eye</code> 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 <small>MATLAB</small>.
</p>
<p><strong>See also:</strong> <a href="Creating-Sparse-Matrices.html#XREFspeye">speye</a>, <a href="#XREFones">ones</a>, <a href="#XREFzeros">zeros</a>.
</p></dd></dl>
<a name="XREFones"></a><dl>
<dt><a name="index-ones"></a><em></em> <strong>ones</strong> <em>(<var>n</var>)</em></dt>
<dt><a name="index-ones-1"></a><em></em> <strong>ones</strong> <em>(<var>m</var>, <var>n</var>)</em></dt>
<dt><a name="index-ones-2"></a><em></em> <strong>ones</strong> <em>(<var>m</var>, <var>n</var>, <var>k</var>, …)</em></dt>
<dt><a name="index-ones-3"></a><em></em> <strong>ones</strong> <em>([<var>m</var> <var>n</var> …])</em></dt>
<dt><a name="index-ones-4"></a><em></em> <strong>ones</strong> <em>(…, <var>class</var>)</em></dt>
<dd><p>Return a matrix or N-dimensional array whose elements are all 1.
</p>
<p>If invoked with a single scalar integer argument <var>n</var>, return a square
NxN matrix.
</p>
<p>If invoked with two or more scalar integer arguments, or a vector of integer
values, return an array with the given dimensions.
</p>
<p>To create a constant matrix whose values are all the same use an expression
such as
</p>
<div class="example">
<pre class="example">val_matrix = val * ones (m, n)
</pre></div>
<p>The optional argument <var>class</var> specifies the class of the return array
and defaults to double. For example:
</p>
<div class="example">
<pre class="example">val = ones (m,n, "uint8")
</pre></div>
<p><strong>See also:</strong> <a href="#XREFzeros">zeros</a>.
</p></dd></dl>
<a name="XREFzeros"></a><dl>
<dt><a name="index-zeros"></a><em></em> <strong>zeros</strong> <em>(<var>n</var>)</em></dt>
<dt><a name="index-zeros-1"></a><em></em> <strong>zeros</strong> <em>(<var>m</var>, <var>n</var>)</em></dt>
<dt><a name="index-zeros-2"></a><em></em> <strong>zeros</strong> <em>(<var>m</var>, <var>n</var>, <var>k</var>, …)</em></dt>
<dt><a name="index-zeros-3"></a><em></em> <strong>zeros</strong> <em>([<var>m</var> <var>n</var> …])</em></dt>
<dt><a name="index-zeros-4"></a><em></em> <strong>zeros</strong> <em>(…, <var>class</var>)</em></dt>
<dd><p>Return a matrix or N-dimensional array whose elements are all 0.
</p>
<p>If invoked with a single scalar integer argument, return a square
NxN matrix.
</p>
<p>If invoked with two or more scalar integer arguments, or a vector of integer
values, return an array with the given dimensions.
</p>
<p>The optional argument <var>class</var> specifies the class of the return array
and defaults to double. For example:
</p>
<div class="example">
<pre class="example">val = zeros (m,n, "uint8")
</pre></div>
<p><strong>See also:</strong> <a href="#XREFones">ones</a>.
</p></dd></dl>
<a name="XREFrepmat"></a><dl>
<dt><a name="index-repmat"></a><em></em> <strong>repmat</strong> <em>(<var>A</var>, <var>m</var>)</em></dt>
<dt><a name="index-repmat-1"></a><em></em> <strong>repmat</strong> <em>(<var>A</var>, <var>m</var>, <var>n</var>)</em></dt>
<dt><a name="index-repmat-2"></a><em></em> <strong>repmat</strong> <em>(<var>A</var>, <var>m</var>, <var>n</var>, <var>p</var> …)</em></dt>
<dt><a name="index-repmat-3"></a><em></em> <strong>repmat</strong> <em>(<var>A</var>, [<var>m</var> <var>n</var>])</em></dt>
<dt><a name="index-repmat-4"></a><em></em> <strong>repmat</strong> <em>(<var>A</var>, [<var>m</var> <var>n</var> <var>p</var> …])</em></dt>
<dd><p>Repeat matrix or N-D array.
</p>
<p>Form a block matrix of size <var>m</var> by <var>n</var>, with a copy of matrix
<var>A</var> as each element.
</p>
<p>If <var>n</var> is not specified, form an <var>m</var> by <var>m</var> block matrix. For
copying along more than two dimensions, specify the number of times to copy
across each dimension <var>m</var>, <var>n</var>, <var>p</var>, …, in a vector in the
second argument.
</p>
<p><strong>See also:</strong> <a href="Broadcasting.html#XREFbsxfun">bsxfun</a>, <a href="Functions-of-a-Matrix.html#XREFkron">kron</a>, <a href="#XREFrepelems">repelems</a>.
</p></dd></dl>
<a name="XREFrepelems"></a><dl>
<dt><a name="index-repelems"></a><em></em> <strong>repelems</strong> <em>(<var>x</var>, <var>r</var>)</em></dt>
<dd><p>Construct a vector of repeated elements from <var>x</var>.
</p>
<p><var>r</var> is a 2x<var>N</var> integer matrix specifying which elements to repeat
and how often to repeat each element. Entries in the first row,
<var>r</var>(1,j), select an element to repeat. The corresponding entry in the
second row, <var>r</var>(2,j), specifies the repeat count. If <var>x</var> is a
matrix then the columns of <var>x</var> are imagined to be stacked on top of
each other for purposes of the selection index. A row vector is always
returned.
</p>
<p>Conceptually the result is calculated as follows:
</p>
<div class="example">
<pre class="example">y = [];
for i = 1:columns (<var>r</var>)
y = [y, <var>x</var>(<var>r</var>(1,i)*ones(1, <var>r</var>(2,i)))];
endfor
</pre></div>
<p><strong>See also:</strong> <a href="#XREFrepmat">repmat</a>, <a href="Rearranging-Matrices.html#XREFcat">cat</a>.
</p></dd></dl>
<a name="XREFrepelem"></a><dl>
<dt><a name="index-repelem"></a><em><var>xxx</var> =</em> <strong>repelem</strong> <em>(<var>x</var>, <var>R</var>)</em></dt>
<dt><a name="index-repelem-1"></a><em><var>xxx</var> =</em> <strong>repelem</strong> <em>(<var>x</var>, <var>R_1</var>, …, <var>R_n</var>)</em></dt>
<dd><p>Construct an array of repeated elements from <var>x</var> and repeat
instructions <var>R_1</var>, ….
</p>
<p><var>x</var> must be a scalar, vector, or N-dimensional array.
</p>
<p>A repeat instruction <var>R_j</var> must either be a scalar or a vector. If the
instruction is a scalar then each component of <var>x</var> in dimension <var>j</var>
is repeated <var>R_j</var> times. If the instruction is a vector then it must
have the same number of elements as the corresponding dimension <var>j</var> of
<var>x</var>. In this case, the <var>k</var>th component of dimension <var>j</var> is
repeated <code><var>R_j</var>(<var>k</var>)</code> times.
</p>
<p>If <var>x</var> is a scalar or vector then <code>repelem</code> may be called with just
a single repeat instruction <var>R</var> and <code>repelem</code> will return a vector
with the same orientation as the input.
</p>
<p>If <var>x</var> is a matrix then at least two <var>R_j</var>s must be specified.
</p>
<p>Note: Using <code>repelem</code> with a vector <var>x</var> and a vector for <var>R_j</var>
is equivalent to Run Length Decoding.
</p>
<p>Examples:
</p>
<div class="example">
<pre class="example">A = [1 2 3 4 5];
B = [2 1 0 1 2];
repelem (A, B)
⇒ 1 1 2 4 5 5
</pre></div>
<div class="example">
<pre class="example">A = magic (3)
⇒ A =
8 1 6
3 5 7
4 9 2
B1 = [1 2 3];
B2 = 2;
repelem (A, B1, B2)
⇒ 8 8 1 1 6 6
3 3 5 5 7 7
3 3 5 5 7 7
4 4 9 9 2 2
4 4 9 9 2 2
4 4 9 9 2 2
</pre></div>
<p>More <var>R_j</var> may be specified than the number of dimensions of <var>x</var>.
Any excess <var>R_j</var> must be scalars (because <var>x</var>’s size in those
dimensions is only 1), and <var>x</var> will be replicated in those dimensions
accordingly.
</p>
<div class="example">
<pre class="example">A = [1 2 3 4 5];
B1 = 2;
B2 = [2 1 3 0 2];
B3 = 3;
repelem (A, B1, B2, B3)
⇒ ans(:,:,1) =
1 1 2 3 3 3 5 5
1 1 2 3 3 3 5 5
ans(:,:,2) =
1 1 2 3 3 3 5 5
1 1 2 3 3 3 5 5
ans(:,:,3) =
1 1 2 3 3 3 5 5
1 1 2 3 3 3 5 5
</pre></div>
<p><var>R_j</var> must be specified in order. A placeholder of 1 may be used for
dimensions which do not need replication.
</p>
<div class="example">
<pre class="example">repelem ([-1, 0; 0, 1], 1, 2, 1, 2)
⇒ ans(:,:,1,1) =
-1 -1 0 0
0 0 1 1
ans(:,:,1,2) =
-1 -1 0 0
0 0 1 1
</pre></div>
<p>If fewer <var>R_j</var> are given than the number of dimensions in <var>x</var>,
<code>repelem</code> will assume <var>R_j</var> is 1 for those dimensions.
</p>
<div class="example">
<pre class="example">A = cat (3, [-1 0; 0 1], [-1 0; 0 1])
⇒ ans(:,:,1) =
-1 0
0 1
ans(:,:,2) =
-1 0
0 1
repelem (A,2,3)
⇒ ans(:,:,1) =
-1 -1 -1 0 0 0
-1 -1 -1 0 0 0
0 0 0 1 1 1
0 0 0 1 1 1
ans(:,:,2) =
-1 -1 -1 0 0 0
-1 -1 -1 0 0 0
0 0 0 1 1 1
0 0 0 1 1 1
</pre></div>
<p><code>repelem</code> preserves the class of <var>x</var>, and works with strings,
cell arrays, NA, and NAN inputs. If any <var>R_j</var> is 0 the output will
be an empty array.
</p>
<div class="example">
<pre class="example">repelem ("Octave", 2, 3)
⇒ OOOccctttaaavvveee
OOOccctttaaavvveee
repelem ([1 2 3; 1 2 3], 2, 0)
⇒ [](4x0)
</pre></div>
<p><strong>See also:</strong> <a href="Rearranging-Matrices.html#XREFcat">cat</a>, <a href="Functions-of-a-Matrix.html#XREFkron">kron</a>, <a href="#XREFrepmat">repmat</a>.
</p></dd></dl>
<p>The functions <code>linspace</code> and <code>logspace</code> make it very easy to
create vectors with evenly or logarithmically spaced elements.
See <a href="Ranges.html#Ranges">Ranges</a>.
</p>
<a name="XREFlinspace"></a><dl>
<dt><a name="index-linspace"></a><em></em> <strong>linspace</strong> <em>(<var>start</var>, <var>end</var>)</em></dt>
<dt><a name="index-linspace-1"></a><em></em> <strong>linspace</strong> <em>(<var>start</var>, <var>end</var>, <var>n</var>)</em></dt>
<dd><p>Return a row vector with <var>n</var> linearly spaced elements between <var>start</var>
and <var>end</var>.
</p>
<p>If the number of elements is greater than one, then the endpoints <var>start</var>
and <var>end</var> are always included in the range. If <var>start</var> is greater than
<var>end</var>, the elements are stored in decreasing order. If the number of
points is not specified, a value of 100 is used.
</p>
<p>The <code>linspace</code> function returns a row vector when both <var>start</var> and
<var>end</var> are scalars. If one, or both, inputs are vectors, then
<code>linspace</code> transforms them to column vectors and returns a matrix where
each row is an independent sequence between
<code><var>start</var>(<var><span class="nolinebreak">row_n</span></var>), <var>end</var>(<var><span class="nolinebreak">row_n</span></var>)</code><!-- /@w -->.
</p>
<p>For compatibility with <small>MATLAB</small>, return the second argument (<var>end</var>) when
only a single value (<var>n</var> = 1) is requested.
</p>
<p><strong>See also:</strong> <a href="Defining-Indexing-And-Indexed-Assignment.html#XREFcolon">colon</a>, <a href="#XREFlogspace">logspace</a>.
</p></dd></dl>
<a name="XREFlogspace"></a><dl>
<dt><a name="index-logspace"></a><em></em> <strong>logspace</strong> <em>(<var>a</var>, <var>b</var>)</em></dt>
<dt><a name="index-logspace-1"></a><em></em> <strong>logspace</strong> <em>(<var>a</var>, <var>b</var>, <var>n</var>)</em></dt>
<dt><a name="index-logspace-2"></a><em></em> <strong>logspace</strong> <em>(<var>a</var>, pi, <var>n</var>)</em></dt>
<dd><p>Return a row vector with <var>n</var> elements logarithmically spaced from
10^<var>a</var> to 10^<var>b</var>.
</p>
<p>If <var>n</var> is unspecified it defaults to 50.
</p>
<p>If <var>b</var> is equal to
pi,
the points are between
10^<var>a</var> and pi,
<em>not</em>
10^<var>a</var> and 10^pi,
in order to be compatible with the corresponding <small>MATLAB</small> function.
</p>
<p>Also for compatibility with <small>MATLAB</small>, return the right-hand side of
the range
(10^<var>b</var>)
when just a single value is requested.
</p>
<p><strong>See also:</strong> <a href="#XREFlinspace">linspace</a>.
</p></dd></dl>
<a name="XREFrand"></a><dl>
<dt><a name="index-rand"></a><em></em> <strong>rand</strong> <em>(<var>n</var>)</em></dt>
<dt><a name="index-rand-1"></a><em></em> <strong>rand</strong> <em>(<var>m</var>, <var>n</var>, …)</em></dt>
<dt><a name="index-rand-2"></a><em></em> <strong>rand</strong> <em>([<var>m</var> <var>n</var> …])</em></dt>
<dt><a name="index-rand-3"></a><em><var>v</var> =</em> <strong>rand</strong> <em>("state")</em></dt>
<dt><a name="index-rand-4"></a><em></em> <strong>rand</strong> <em>("state", <var>v</var>)</em></dt>
<dt><a name="index-rand-5"></a><em></em> <strong>rand</strong> <em>("state", "reset")</em></dt>
<dt><a name="index-rand-6"></a><em><var>v</var> =</em> <strong>rand</strong> <em>("seed")</em></dt>
<dt><a name="index-rand-7"></a><em></em> <strong>rand</strong> <em>("seed", <var>v</var>)</em></dt>
<dt><a name="index-rand-8"></a><em></em> <strong>rand</strong> <em>("seed", "reset")</em></dt>
<dt><a name="index-rand-9"></a><em></em> <strong>rand</strong> <em>(…, "single")</em></dt>
<dt><a name="index-rand-10"></a><em></em> <strong>rand</strong> <em>(…, "double")</em></dt>
<dd><p>Return a matrix with random elements uniformly distributed on the
interval (0, 1).
</p>
<p>The arguments are handled the same as the arguments for <code>eye</code>.
</p>
<p>You can query the state of the random number generator using the form
</p>
<div class="example">
<pre class="example">v = rand ("state")
</pre></div>
<p>This returns a column vector <var>v</var> of length 625. Later, you can restore
the random number generator to the state <var>v</var> using the form
</p>
<div class="example">
<pre class="example">rand ("state", v)
</pre></div>
<p>You may also initialize the state vector from an arbitrary vector of length
≤ 625 for <var>v</var>. This new state will be a hash based on the value of
<var>v</var>, not <var>v</var> itself.
</p>
<p>By default, the generator is initialized from <code>/dev/urandom</code> if it is
available, otherwise from CPU time, wall clock time, and the current
fraction of a second. Note that this differs from <small>MATLAB</small>, which
always initializes the state to the same state at startup. To obtain
behavior comparable to <small>MATLAB</small>, initialize with a deterministic state
vector in Octave’s startup files (see <a href="Startup-Files.html#Startup-Files">Startup Files</a>).
</p>
<p>To compute the pseudo-random sequence, <code>rand</code> uses the Mersenne
Twister with a period of <em>2^{19937}-1</em>
(See M. Matsumoto and T. Nishimura,
<cite>Mersenne Twister: A 623-dimensionally equidistributed uniform
pseudorandom number generator</cite>,
ACM Trans. on Modeling and Computer Simulation Vol. 8, No. 1,
pp. 3–30, January 1998,
<a href="http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html">http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html</a>).
Do <strong>not</strong> use for cryptography without securely hashing several
returned values together, otherwise the generator state can be learned after
reading 624 consecutive values.
</p>
<p>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 <code>"seed"</code> is used to specify that the old generators should
be used, as in
</p>
<div class="example">
<pre class="example">rand ("seed", val)
</pre></div>
<p>which sets the seed of the generator to <var>val</var>. The seed of the
generator can be queried with
</p>
<div class="example">
<pre class="example">s = rand ("seed")
</pre></div>
<p>However, it should be noted that querying the seed will not cause
<code>rand</code> to use the old generators, only setting the seed will. To cause
<code>rand</code> to once again use the new generators, the keyword
<code>"state"</code> should be used to reset the state of the <code>rand</code>.
</p>
<p>The state or seed of the generator can be reset to a new random value using
the <code>"reset"</code> keyword.
</p>
<p>The class of the value returned can be controlled by a trailing
<code>"double"</code> or <code>"single"</code> argument. These are the only valid
classes.
</p>
<p><strong>See also:</strong> <a href="#XREFrandn">randn</a>, <a href="#XREFrande">rande</a>, <a href="#XREFrandg">randg</a>, <a href="#XREFrandp">randp</a>.
</p></dd></dl>
<a name="XREFrandi"></a><dl>
<dt><a name="index-randi"></a><em></em> <strong>randi</strong> <em>(<var>imax</var>)</em></dt>
<dt><a name="index-randi-1"></a><em></em> <strong>randi</strong> <em>(<var>imax</var>, <var>n</var>)</em></dt>
<dt><a name="index-randi-2"></a><em></em> <strong>randi</strong> <em>(<var>imax</var>, <var>m</var>, <var>n</var>, …)</em></dt>
<dt><a name="index-randi-3"></a><em></em> <strong>randi</strong> <em>([<var>imin</var> <var>imax</var>], …)</em></dt>
<dt><a name="index-randi-4"></a><em></em> <strong>randi</strong> <em>(…, "<var>class</var>")</em></dt>
<dd><p>Return random integers in the range 1:<var>imax</var>.
</p>
<p>Additional arguments determine the shape of the return matrix. When no
arguments are specified a single random integer is returned. If one
argument <var>n</var> is specified then a square matrix (<var>n</var> x <var>n</var>)<!-- /@w -->
is returned. Two or more arguments will return a multi-dimensional matrix
(<var>m</var> x <var>n</var> x …)<!-- /@w -->.
</p>
<p>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 [<var>imin</var>, <var>imax</var>]<!-- /@w -->.
</p>
<p>The optional argument <var>class</var> will return a matrix of the requested
type. The default is <code>"double"</code>.
</p>
<p>The following example returns 150 integers in the range 1–10.
</p>
<div class="example">
<pre class="example">ri = randi (10, 150, 1)
</pre></div>
<p>Implementation Note: <code>randi</code> relies internally on <code>rand</code> which
uses class <code>"double"</code> to represent numbers. This limits the maximum
integer (<var>imax</var>) and range (<var>imax</var> - <var>imin</var>) to the value
returned by the <code>flintmax</code> function. For IEEE floating point numbers
this value is <em>2^{53} - 1</em><!-- /@w -->.
</p>
<p><strong>See also:</strong> <a href="#XREFrand">rand</a>.
</p></dd></dl>
<a name="XREFrandn"></a><dl>
<dt><a name="index-randn"></a><em></em> <strong>randn</strong> <em>(<var>n</var>)</em></dt>
<dt><a name="index-randn-1"></a><em></em> <strong>randn</strong> <em>(<var>m</var>, <var>n</var>, …)</em></dt>
<dt><a name="index-randn-2"></a><em></em> <strong>randn</strong> <em>([<var>m</var> <var>n</var> …])</em></dt>
<dt><a name="index-randn-3"></a><em><var>v</var> =</em> <strong>randn</strong> <em>("state")</em></dt>
<dt><a name="index-randn-4"></a><em></em> <strong>randn</strong> <em>("state", <var>v</var>)</em></dt>
<dt><a name="index-randn-5"></a><em></em> <strong>randn</strong> <em>("state", "reset")</em></dt>
<dt><a name="index-randn-6"></a><em><var>v</var> =</em> <strong>randn</strong> <em>("seed")</em></dt>
<dt><a name="index-randn-7"></a><em></em> <strong>randn</strong> <em>("seed", <var>v</var>)</em></dt>
<dt><a name="index-randn-8"></a><em></em> <strong>randn</strong> <em>("seed", "reset")</em></dt>
<dt><a name="index-randn-9"></a><em></em> <strong>randn</strong> <em>(…, "single")</em></dt>
<dt><a name="index-randn-10"></a><em></em> <strong>randn</strong> <em>(…, "double")</em></dt>
<dd><p>Return a matrix with normally distributed random elements having zero mean
and variance one.
</p>
<p>The arguments are handled the same as the arguments for <code>rand</code>.
</p>
<p>By default, <code>randn</code> uses the Marsaglia and Tsang
“Ziggurat technique” to transform from a uniform to a normal distribution.
</p>
<p>The class of the value returned can be controlled by a trailing
<code>"double"</code> or <code>"single"</code> argument. These are the only valid
classes.
</p>
<p>Reference: G. Marsaglia and W.W. Tsang,
<cite>Ziggurat Method for Generating Random Variables</cite>,
J. Statistical Software, vol 5, 2000,
<a href="https://www.jstatsoft.org/v05/i08/">https://www.jstatsoft.org/v05/i08/</a>
</p>
<p><strong>See also:</strong> <a href="#XREFrand">rand</a>, <a href="#XREFrande">rande</a>, <a href="#XREFrandg">randg</a>, <a href="#XREFrandp">randp</a>.
</p></dd></dl>
<a name="XREFrande"></a><dl>
<dt><a name="index-rande"></a><em></em> <strong>rande</strong> <em>(<var>n</var>)</em></dt>
<dt><a name="index-rande-1"></a><em></em> <strong>rande</strong> <em>(<var>m</var>, <var>n</var>, …)</em></dt>
<dt><a name="index-rande-2"></a><em></em> <strong>rande</strong> <em>([<var>m</var> <var>n</var> …])</em></dt>
<dt><a name="index-rande-3"></a><em><var>v</var> =</em> <strong>rande</strong> <em>("state")</em></dt>
<dt><a name="index-rande-4"></a><em></em> <strong>rande</strong> <em>("state", <var>v</var>)</em></dt>
<dt><a name="index-rande-5"></a><em></em> <strong>rande</strong> <em>("state", "reset")</em></dt>
<dt><a name="index-rande-6"></a><em><var>v</var> =</em> <strong>rande</strong> <em>("seed")</em></dt>
<dt><a name="index-rande-7"></a><em></em> <strong>rande</strong> <em>("seed", <var>v</var>)</em></dt>
<dt><a name="index-rande-8"></a><em></em> <strong>rande</strong> <em>("seed", "reset")</em></dt>
<dt><a name="index-rande-9"></a><em></em> <strong>rande</strong> <em>(…, "single")</em></dt>
<dt><a name="index-rande-10"></a><em></em> <strong>rande</strong> <em>(…, "double")</em></dt>
<dd><p>Return a matrix with exponentially distributed random elements.
</p>
<p>The arguments are handled the same as the arguments for <code>rand</code>.
</p>
<p>By default, <code>rande</code> uses the Marsaglia and Tsang
“Ziggurat technique” to transform from a uniform to an exponential
distribution.
</p>
<p>The class of the value returned can be controlled by a trailing
<code>"double"</code> or <code>"single"</code> argument. These are the only valid
classes.
</p>
<p>Reference: G. Marsaglia and W.W. Tsang,
<cite>Ziggurat Method for Generating Random Variables</cite>,
J. Statistical Software, vol 5, 2000,
<a href="https://www.jstatsoft.org/v05/i08/">https://www.jstatsoft.org/v05/i08/</a>
</p>
<p><strong>See also:</strong> <a href="#XREFrand">rand</a>, <a href="#XREFrandn">randn</a>, <a href="#XREFrandg">randg</a>, <a href="#XREFrandp">randp</a>.
</p></dd></dl>
<a name="XREFrandp"></a><dl>
<dt><a name="index-randp"></a><em></em> <strong>randp</strong> <em>(<var>l</var>, <var>n</var>)</em></dt>
<dt><a name="index-randp-1"></a><em></em> <strong>randp</strong> <em>(<var>l</var>, <var>m</var>, <var>n</var>, …)</em></dt>
<dt><a name="index-randp-2"></a><em></em> <strong>randp</strong> <em>(<var>l</var>, [<var>m</var> <var>n</var> …])</em></dt>
<dt><a name="index-randp-3"></a><em><var>v</var> =</em> <strong>randp</strong> <em>("state")</em></dt>
<dt><a name="index-randp-4"></a><em></em> <strong>randp</strong> <em>("state", <var>v</var>)</em></dt>
<dt><a name="index-randp-5"></a><em></em> <strong>randp</strong> <em>("state", "reset")</em></dt>
<dt><a name="index-randp-6"></a><em><var>v</var> =</em> <strong>randp</strong> <em>("seed")</em></dt>
<dt><a name="index-randp-7"></a><em></em> <strong>randp</strong> <em>("seed", <var>v</var>)</em></dt>
<dt><a name="index-randp-8"></a><em></em> <strong>randp</strong> <em>("seed", "reset")</em></dt>
<dt><a name="index-randp-9"></a><em></em> <strong>randp</strong> <em>(…, "single")</em></dt>
<dt><a name="index-randp-10"></a><em></em> <strong>randp</strong> <em>(…, "double")</em></dt>
<dd><p>Return a matrix with Poisson distributed random elements with mean value
parameter given by the first argument, <var>l</var>.
</p>
<p>The arguments are handled the same as the arguments for <code>rand</code>, except
for the argument <var>l</var>.
</p>
<p>Five different algorithms are used depending on the range of <var>l</var> and
whether or not <var>l</var> is a scalar or a matrix.
</p>
<dl compact="compact">
<dt>For scalar <var>l</var> ≤ 12, use direct method.</dt>
<dd><p>W.H. Press, et al., <cite>Numerical Recipes in C</cite>,
Cambridge University Press, 1992.
</p>
</dd>
<dt>For scalar <var>l</var> > 12, use rejection method.[1]</dt>
<dd><p>W.H. Press, et al., <cite>Numerical Recipes in C</cite>,
Cambridge University Press, 1992.
</p>
</dd>
<dt>For matrix <var>l</var> ≤ 10, use inversion method.[2]</dt>
<dd><p>E. Stadlober, et al., WinRand source code, available via FTP.
</p>
</dd>
<dt>For matrix <var>l</var> > 10, use patchwork rejection method.</dt>
<dd><p>E. Stadlober, et al., WinRand source code, available via FTP, or
H. Zechner, <cite>Efficient sampling from continuous and discrete
unimodal distributions</cite>, Doctoral Dissertation, 156pp., Technical
University Graz, Austria, 1994.
</p>
</dd>
<dt>For <var>l</var> > 1e8, use normal approximation.</dt>
<dd><p>L. Montanet, et al., <cite>Review of Particle Properties</cite>,
Physical Review D 50 p1284, 1994.
</p></dd>
</dl>
<p>The class of the value returned can be controlled by a trailing
<code>"double"</code> or <code>"single"</code> argument. These are the only valid
classes.
</p>
<p><strong>See also:</strong> <a href="#XREFrand">rand</a>, <a href="#XREFrandn">randn</a>, <a href="#XREFrande">rande</a>, <a href="#XREFrandg">randg</a>.
</p></dd></dl>
<a name="XREFrandg"></a><dl>
<dt><a name="index-randg"></a><em></em> <strong>randg</strong> <em>(<var>a</var>, <var>n</var>)</em></dt>
<dt><a name="index-randg-1"></a><em></em> <strong>randg</strong> <em>(<var>a</var>, <var>m</var>, <var>n</var>, …)</em></dt>
<dt><a name="index-randg-2"></a><em></em> <strong>randg</strong> <em>(<var>a</var>, [<var>m</var> <var>n</var> …])</em></dt>
<dt><a name="index-randg-3"></a><em><var>v</var> =</em> <strong>randg</strong> <em>("state")</em></dt>
<dt><a name="index-randg-4"></a><em></em> <strong>randg</strong> <em>("state", <var>v</var>)</em></dt>
<dt><a name="index-randg-5"></a><em></em> <strong>randg</strong> <em>("state", "reset")</em></dt>
<dt><a name="index-randg-6"></a><em><var>v</var> =</em> <strong>randg</strong> <em>("seed")</em></dt>
<dt><a name="index-randg-7"></a><em></em> <strong>randg</strong> <em>("seed", <var>v</var>)</em></dt>
<dt><a name="index-randg-8"></a><em></em> <strong>randg</strong> <em>("seed", "reset")</em></dt>
<dt><a name="index-randg-9"></a><em></em> <strong>randg</strong> <em>(…, "single")</em></dt>
<dt><a name="index-randg-10"></a><em></em> <strong>randg</strong> <em>(…, "double")</em></dt>
<dd>
<p>Return a matrix with <code>gamma (<var>a</var>,1)</code> distributed random elements.
</p>
<p>The arguments are handled the same as the arguments for <code>rand</code>, except
for the argument <var>a</var>.
</p>
<p>This can be used to generate many distributions:
</p>
<dl compact="compact">
<dt><code>gamma (a, b)</code> for <code>a > -1</code>, <code>b > 0</code></dt>
<dd>
<div class="example">
<pre class="example">r = b * randg (a)
</pre></div>
</dd>
<dt><code>beta (a, b)</code> for <code>a > -1</code>, <code>b > -1</code></dt>
<dd>
<div class="example">
<pre class="example">r1 = randg (a, 1)
r = r1 / (r1 + randg (b, 1))
</pre></div>
</dd>
<dt><code>Erlang (a, n)</code></dt>
<dd>
<div class="example">
<pre class="example">r = a * randg (n)
</pre></div>
</dd>
<dt><code>chisq (df)</code> for <code>df > 0</code></dt>
<dd>
<div class="example">
<pre class="example">r = 2 * randg (df / 2)
</pre></div>
</dd>
<dt><code>t (df)</code> for <code>0 < df < inf</code> (use randn if df is infinite)</dt>
<dd>
<div class="example">
<pre class="example">r = randn () / sqrt (2 * randg (df / 2) / df)
</pre></div>
</dd>
<dt><code>F (n1, n2)</code> for <code>0 < n1</code>, <code>0 < n2</code></dt>
<dd>
<div class="example">
<pre class="example">## 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
</pre></div>
</dd>
<dt>negative <code>binomial (n, p)</code> for <code>n > 0</code>, <code>0 < p <= 1</code></dt>
<dd>
<div class="example">
<pre class="example">r = randp ((1 - p) / p * randg (n))
</pre></div>
</dd>
<dt>non-central <code>chisq (df, L)</code>, for <code>df >= 0</code> and <code>L > 0</code></dt>
<dd><p>(use chisq if <code>L = 0</code>)
</p>
<div class="example">
<pre class="example">r = randp (L / 2)
r(r > 0) = 2 * randg (r(r > 0))
r(df > 0) += 2 * randg (df(df > 0)/2)
</pre></div>
</dd>
<dt><code>Dirichlet (a1, … ak)</code></dt>
<dd>
<div class="example">
<pre class="example">r = (randg (a1), …, randg (ak))
r = r / sum (r)
</pre></div>
</dd>
</dl>
<p>The class of the value returned can be controlled by a trailing
<code>"double"</code> or <code>"single"</code> argument. These are the only valid
classes.
</p>
<p><strong>See also:</strong> <a href="#XREFrand">rand</a>, <a href="#XREFrandn">randn</a>, <a href="#XREFrande">rande</a>, <a href="#XREFrandp">randp</a>.
</p></dd></dl>
<p>The generators operate in the new or old style together, it is not
possible to mix the two. Initializing any generator with
<code>"state"</code> or <code>"seed"</code> causes the others to switch to the
same style for future calls.
</p>
<p>The state of each generator is independent and calls to different
generators can be interleaved without affecting the final result. For
example,
</p>
<div class="example">
<pre class="example">rand ("state", [11, 22, 33]);
randn ("state", [44, 55, 66]);
u = rand (100, 1);
n = randn (100, 1);
</pre></div>
<p>and
</p>
<div class="example">
<pre class="example">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
</pre></div>
<p>produce equivalent results. When the generators are initialized in
the old style with <code>"seed"</code> only <code>rand</code> and <code>randn</code> are
independent, because the old <code>rande</code>, <code>randg</code> and
<code>randp</code> generators make calls to <code>rand</code> and <code>randn</code>.
</p>
<p>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.<a name="DOCF7" href="#FOOT7"><sup>7</sup></a> If you really do
need to reproduce a sequence of numbers exactly, you can set the state
or seed to a specific value.
</p>
<p>If invoked without arguments, <code>rand</code> and <code>randn</code> return a
single element of a random sequence.
</p>
<p>The original <code>rand</code> and <code>randn</code> functions use Fortran code from
<small>RANLIB</small>, 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.
</p>
<a name="XREFrandperm"></a><dl>
<dt><a name="index-randperm"></a><em></em> <strong>randperm</strong> <em>(<var>n</var>)</em></dt>
<dt><a name="index-randperm-1"></a><em></em> <strong>randperm</strong> <em>(<var>n</var>, <var>m</var>)</em></dt>
<dd><p>Return a row vector containing a random permutation of <code>1:<var>n</var></code>.
</p>
<p>If <var>m</var> is supplied, return <var>m</var> unique entries, sampled without
replacement from <code>1:<var>n</var></code>.
</p>
<p>The complexity is O(<var>n</var>) in memory and O(<var>m</var>) in time, unless
<var>m</var> < <var>n</var>/5, in which case O(<var>m</var>) memory is used as well. The
randomization is performed using rand(). All permutations are equally
likely.
</p>
<p><strong>See also:</strong> <a href="Basic-Statistical-Functions.html#XREFperms">perms</a>.
</p></dd></dl>
<div class="footnote">
<hr>
<h4 class="footnotes-heading">Footnotes</h4>
<h3><a name="FOOT7" href="#DOCF7">(7)</a></h3>
<p>The old versions of <code>rand</code> and <code>randn</code>
obtain their initial seeds from the system clock.</p>
</div>
<hr>
<div class="header">
<p>
Next: <a href="Famous-Matrices.html#Famous-Matrices" accesskey="n" rel="next">Famous Matrices</a>, Previous: <a href="Rearranging-Matrices.html#Rearranging-Matrices" accesskey="p" rel="prev">Rearranging Matrices</a>, Up: <a href="Matrix-Manipulation.html#Matrix-Manipulation" accesskey="u" rel="up">Matrix Manipulation</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
