@c Copyright (C) 1996, 1997 John W. Eaton
@c This is part of the Octave manual.
@c For copying conditions, see the file gpl.texi.

@node Matrix Manipulation
@chapter Matrix Manipulation

There are a number of functions available for checking to see if the
elements of a matrix meet some condition, and for rearranging the
elements of a matrix.  For example, Octave can easily tell you if all
the elements of a matrix are finite, or are less than some specified
value.  Octave can also rotate the elements, extract the upper- or
lower-triangular parts, or sort the columns of a matrix.

@menu
* Finding Elements and Checking Conditions::  
* Rearranging Matrices::        
* Special Utility Matrices::    
* Famous Matrices::             
@end menu

@node Finding Elements and Checking Conditions
@section Finding Elements and Checking Conditions

The functions @code{any} and @code{all} are useful for determining
whether any or all of the elements of a matrix satisfy some condition.
The @code{find} function is also useful in determining which elements of
a matrix meet a specified condition.

@DOCSTRING(any)

@DOCSTRING(all)

Since the comparison operators (@pxref{Comparison Ops}) return matrices
of ones and zeros, it is easy to test a matrix for many things, not just
whether the elements are nonzero.  For example, 

@example
@group
all (all (rand (5) < 0.9))
     @result{} 0
@end group
@end example

@noindent
tests a random 5 by 5 matrix to see if all of its elements are less
than 0.9.

Note that in conditional contexts (like the test clause of @code{if} and
@code{while} statements) Octave treats the test as if you had typed
@code{all (all (condition))}.

@DOCSTRING(xor)

@DOCSTRING(is_duplicate_entry)

@DOCSTRING(diff)

@DOCSTRING(isinf)

@DOCSTRING(isnan)

@DOCSTRING(finite)

@DOCSTRING(find)
        
@DOCSTRING(common_size)

@node Rearranging Matrices
@section Rearranging Matrices

@DOCSTRING(fliplr)

@DOCSTRING(flipud)

@DOCSTRING(flipdim)

@DOCSTRING(rot90)

@DOCSTRING(rotdim)

@DOCSTRING(cat)

@DOCSTRING(horzcat)

@DOCSTRING(vertcat)

@DOCSTRING(permute)

@DOCSTRING(ipermute)

@DOCSTRING(reshape)

@DOCSTRING(circshift)

@DOCSTRING(shiftdim)

@DOCSTRING(shift)

@DOCSTRING(sort)

Since the @code{sort} function does not allow sort keys to be specified,
it can't be used to order the rows of a matrix according to the values
of the elements in various columns@footnote{For example, to first sort
based on the values in column 1, and then, for any values that are
repeated in column 1, sort based on the values found in column 2, etc.}
in a single call.  Using the second output, however, it is possible to
sort all rows based on the values in a given column.  Here's an example
that sorts the rows of a matrix based on the values in the second
column.

@example
@group
a = [1, 2; 2, 3; 3, 1];
[s, i] = sort (a (:, 2));
a (i, :)
     @result{}  3  1
         1  2
         2  3
@end group
@end example

@DOCSTRING(tril)

@DOCSTRING(vec)

@DOCSTRING(vech)

@DOCSTRING(prepad)

@node Special Utility Matrices
@section Special Utility Matrices

@DOCSTRING(eye)

@DOCSTRING(ones)

@DOCSTRING(zeros)

@DOCSTRING(repmat)

@DOCSTRING(rand)

@DOCSTRING(randn)

The @code{rand} and @code{randn} functions use separate generators.
This ensures that

@example
@group
rand ("seed", 13);
randn ("seed", 13);
u = rand (100, 1);
n = randn (100, 1);
@end group
@end example

@noindent
and

@example
@group
rand ("seed", 13);
randn ("seed", 13);
u = zeros (100, 1);
n = zeros (100, 1);
for i = 1:100
  u(i) = rand ();
  n(i) = randn ();
end
@end group
@end example

@noindent
produce equivalent results.

Normally, @code{rand} and @code{randn} obtain their initial
seeds from the system clock, so that the sequence of random numbers is
not the same each time you run Octave.  If you really do need for to
reproduce a sequence of numbers exactly, you can set the seed to a
specific value.

If it is invoked without arguments, @code{rand} and @code{randn} return a
single element of a random sequence.

The @code{rand} and @code{randn} functions use Fortran code from
@sc{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.

@DOCSTRING(randperm)

@DOCSTRING(diag)

@c XXX FIXME XXX -- is this really worth documenting?
@c
@c DOCSTRING(warn_imag_to_real)
@c 
@c XXX FIXME XXX -- this is here because it is used by @code{ones},
@c @code{zeros}, @code{rand}, etc.

The functions @code{linspace} and @code{logspace} make it very easy to
create vectors with evenly or logarithmically spaced elements.
@xref{Ranges}.

@DOCSTRING(linspace)

@DOCSTRING(logspace)

@DOCSTRING(warn_neg_dim_as_zero)

@DOCSTRING(warn_imag_to_real)

@node Famous Matrices
@section Famous Matrices

The following functions return famous matrix forms.

@DOCSTRING(hankel)

@DOCSTRING(hilb)

@DOCSTRING(invhilb)

@DOCSTRING(sylvester_matrix)

@DOCSTRING(toeplitz)

@DOCSTRING(vander)