X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fmatrices.texi;h=83eccb8d62a7edde2361e2adbb3addb04d31b97c;hb=45c2e0a826edbc00a4ea916338668271d5d2edf2;hp=1fce72b7dafa4a1102b02b523af1c787fab86afb;hpb=a24e86e3e941804ca6b9a70cff5c6ae5f02e6daf;p=pspp

diff --git a/doc/matrices.texi b/doc/matrices.texi
index 1fce72b7da..83eccb8d62 100644
--- a/doc/matrices.texi
+++ b/doc/matrices.texi
@@ -1120,219 +1120,330 @@ Examples:
 
 The matrix language support numerous functions in multiple categories.
 The following subsections document each of the currently supported
-functions.  In the descriptions, function arguments that must be
-scalars are given names beginning with @var{s}, those that must be
-vectors are given names beginning with @var{v}, and general matrix
-arguments are given names beginning with @var{m}.
+functions.  The first letter of each parameter's name indicate the
+required argument type:
 
-@node Elementwise Matrix Functions
-@subsubsection Elementwise Matrix Functions
+@table @var
+@item s
+A scalar.
 
-@deftypefn {Matrix Function} {} ABS (@var{m})
-@end deftypefn
+@item n
+A nonnegative integer scalar.  (Non-integers are accepted and silently
+rounded down to the nearest integer.)
 
-@deftypefn {Matrix Function} {} ALL (@var{m})
-@end deftypefn
+@item V
+A row or column vector.
 
-@deftypefn {Matrix Function} {} ANY (@var{m})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} ARSIN (@var{m})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} ARTAN (@var{m})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} COS (@var{m})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} EXP (@var{m})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} LG10 (@var{m})
-@end deftypefn
-
-
-@deftypefn {Matrix Function} {} LN (@var{m})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} MOD (@var{m}, @var{s})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} RND (@var{m})
-@end deftypefn
-
-
-@deftypefn {Matrix Function} {} SIN (@var{m})
-@end deftypefn
-
-
-@deftypefn {Matrix Function} {} SQRT (@var{m})
-@end deftypefn
-
-
-@deftypefn {Matrix Function} {} TRUNC (@var{m})
-@end deftypefn
+@item M
+A matrix.
+@end table
 
+@node Matrix Elementwise Functions
+@subsubsection Elementwise Functions
+
+These functions act on each element of their argument independently,
+like the elementwise operators (@pxref{Matrix Elementwise Binary
+Operators}).
+
+@deffn {Matrix Function} ABS (@var{M})
+Takes the absolute value of each element of @var{M}.
+
+@t{ABS(@{-1, 2; -3, 0@}) @result{} @{1, 2; 3, 0@}}
+@end deffn
+
+@deffn {Matrix Function} ARSIN (@var{M})
+@deffnx {Matrix Function} ARTAN (@var{M})
+Computes the inverse sine or tangent, respectively, of each element in
+@var{M}.  The results are in radians, between @math{-\pi/2} and
+@math{+\pi/2}, inclusive.
+
+The value of @math{\pi} can be computed as @code{4*ARTAN(1)}.
+@end deffn
+
+@deffn {Matrix Function} COS (@var{M})
+@deffnx {Matrix Function} SIN (@var{M})
+Computes the cosine or sine, respectively, of each element in @var{M},
+which must be in radians.
+@end deffn
+
+@deffn {Matrix Function} EXP (@var{M})
+Computes @math{e^x} for each element @var{x} in @var{M}.
+@end deffn
+
+@deffn {Matrix Function} LG10 (@var{M})
+@deffnx {Matrix Function} LN (@var{M})
+Takes the logarithm with base 10 or base @math{e}, respectively, of
+each element in @var{M}.
+@end deffn
+
+@deffn {Matrix Function} MOD (@var{M}, @var{s})
+Takes each element in @var{M} modulo nonzero scalar value @var{s},
+that is, the remainder of division by @var{s}.  The sign of the result
+is the same as the sign of the dividend.
+@end deffn
+
+@deffn {Matrix Function} RND (@var{M})
+@deffnx {Matrix Function} TRUNC (@var{M})
+Rounds each element of @var{M} to an integer.  @code{RND} rounds to
+the nearest integer, with halves rounded to even integers, and
+@code{TRUNC} rounds toward zero.
+@end deffn
+
+@deffn {Matrix Function} SQRT (@var{M})
+Takes the square root of each element of @var{M}, which must not be
+negative.
+@end deffn
+
+@node Matrix Logical Functions
+@subsubsection Logical Functions
+
+@deffn {Matrix Function} ALL (@var{M})
+Returns a scalar with value 1 if all of the elements in @var{M} are
+nonzero, or 0 if at least one element is zero.
+@end deffn
+
+@deffn {Matrix Function} ANY (@var{M})
+Returns a scalar with value 1 if any of the elements in @var{M} is
+nonzero, or 0 if all of them are zero.
+@end deffn
 
 @node Matrix Construction Functions
-@subsection Matrix Construction Functions
-
-@deftypefn {Matrix Function} {} BLOCK (@var{m1}, @var{m2}, @dots{})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} IDENT (@var{s})
-@deftypefnx {Matrix Function} {} IDENT (@var{sr}, @var{sc})
-@end deftypefn
-
-
-@deftypefn {Matrix Function} {} MAGIC (@var{m})
-@end deftypefn
-
-
-@deftypefn {Matrix Function} {} MAKE (@var{sr}, @var{sc}, @var{sv})
-@end deftypefn
-
-
-@deftypefn {Matrix Function} {} MDIAG (@var{v})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} RESHAPE (@var{m}, @var{sr}, @var{sc})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} TRANSPOS (@var{m})
-@deftypefnx {Matrix Function} {} T (@var{m})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} UNIFORM (@var{sr}, @var{sc})
-@end deftypefn
+@subsubsection Matrix Construction Functions
+
+@deffn {Matrix Function} BLOCK (@var{M1}, @dots{}, @var{Mn})
+Returns a block diagonal matrix with as many rows as the sum of its
+arguments' row counts and as many columns as the sum of their columns.
+Each argument matrix is placed along the main diagonal of the result,
+and all other elements are zero.
+@end deffn
+
+@deffn {Matrix Function} IDENT (@var{n})
+@deffnx {Matrix Function} IDENT (@var{nr}, @var{nc})
+Returns an identity matrix, whose main diagonal elements are one and
+whose other elements are zero.  The returned matrix has @var{n} rows
+and columns or @var{nr} rows and @var{nc} columns, respectively.
+@end deffn
+
+@deffn {Matrix Function} MAGIC (@var{n})
+Returns an @math{@var{n}@times{}@var{n}} matrix that contains each of
+the integers @math{1@dots{}@var{n}} once, in which each column, each
+row, and each diagonal sums to @math{n(n^2+1)/2}.  There are many
+magic squares with given dimensions, but this function always returns
+the same one for a given value of @var{n}.
+@end deffn
+
+@deffn {Matrix Function} MAKE (@var{nr}, @var{nc}, @var{s})
+Returns an @math{@var{nr}@times{}@var{nc}} matrix whose elements are
+all @var{s}.
+@end deffn
+
+@deffn {Matrix Function} MDIAG (@var{V})
+Returns a @math{|@var{V}|@times{}|@var{V}|} matrix whose main diagonal
+comes from @var{V} and whose other elements are zero.
+@end deffn
+
+@deffn {Matrix Function} RESHAPE (@var{M}, @var{nr}, @var{nc})
+Returns an @math{@var{nr}@times{}@var{nc}} matrix whose elements come
+from @var{M}, which must have the same number of elements as the new
+matrix, copying elements from @var{M} to the new matrix row by row.
+@end deffn
+
+@deffn {Matrix Function} T (@var{M})
+@deffnx {Matrix Function} TRANSPOS (@var{M})
+Returns @var{M} with rows exchanged for columns.
+@end deffn
+
+@deffn {Matrix Function} UNIFORM (@var{nr}, @var{nc})
+Returns a @math{@var{nr}@times{}@var{nc}} matrix in which each element
+is randomly chosen from a uniform distribution of real numbers between
+0 and 1.
+@end deffn
 
 @node Matrix Minimum and Maximum and Sum Functions
-@subsection Minimum, Maximum, and Sum Functions
-
-@deftypefn {Matrix Function} {} CMAX (@var{m})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} CMIN (@var{m})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} CSSQ (@var{m})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} CSUM (@var{m})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} MMAX (@var{m})
-@end deftypefn
-
-
-@deftypefn {Matrix Function} {} MMIN (@var{m})
-@end deftypefn
-
-
-@deftypefn {Matrix Function} {} MSSQ (@var{m})
-@end deftypefn
-
-
-@deftypefn {Matrix Function} {} MSUM (@var{m})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} RMAX (@var{m})
-@end deftypefn
+@subsubsection Minimum, Maximum, and Sum Functions
+
+@deffn {Matrix Function} CMIN (@var{M})
+@deffnx {Matrix Function} CMAX (@var{M})
+@deffnx {Matrix Function} CSUM (@var{M})
+@deffnx {Matrix Function} CSSQ (@var{M})
+Returns a row vector with the same number of columns as @var{M}, in
+which each element is the minimum, maximum, sum, or sum of squares,
+respectively, of the elements in the same column of @var{M}.
+@end deffn
+
+@deffn {Matrix Function} MMIN (@var{M})
+@deffnx {Matrix Function} MMAX (@var{M})
+@deffnx {Matrix Function} MSUM (@var{M})
+@deffnx {Matrix Function} MSSQ (@var{M})
+Returns the minimum, maximum, sum, or sum of squares, respectively, of
+the elements of @var{M}.
+@end deffn
+
+@deffn {Matrix Function} RMIN (@var{M})
+@deffnx {Matrix Function} RMAX (@var{M})
+@deffnx {Matrix Function} RSUM (@var{M})
+@deffnx {Matrix Function} RSSQ (@var{M})
+Returns a column vector with the same number of rows as @var{M}, in
+which each element is the minimum, maximum, sum, or sum of squares,
+respectively, of the elements in the same row of @var{M}.
+@end deffn
+
+@deffn {Matrix Function} SSCP (@var{M})
+Returns @math{@var{M}^T @times{} @var{M}}.
+@end deffn
+
+@deffn {Matrix Function} TRACE (@var{M})
+Returns the sum of the elements along @var{M}'s main diagonal,
+equivalent to @code{MSUM(DIAG(@var{M}))}.
+@end deffn
 
 
-@deftypefn {Matrix Function} {} RMIN (@var{m})
-@end deftypefn
-
-
-@deftypefn {Matrix Function} {} RSSQ (@var{m})
-@end deftypefn
-
+@node Matrix Property Functions
+@subsubsection Matrix Property Functions
 
-@deftypefn {Matrix Function} {} RSUM (@var{m})
-@end deftypefn
+@deffn {Matrix Function} NROW (@var{M})
+@deffnx {Matrix Function} NCOL (@var{M})
+Returns the number of row or columns, respectively, in @var{M}.
+@end deffn
 
-@deftypefn {Matrix Function} {} SSCP (@var{m})
-@end deftypefn
+@deffn {Matrix Function} DIAG (@var{M})
+Returns a column vector containing a copy of @var{M}'s main diagonal.
+The vector's length is the lesser of @code{NCOL(@var{M})} and
+@code{NROW(@var{M})}.
+@end deffn
 
-@node Matrix Property Functions
-@subsection Matrix Property Functions
+@node Matrix Rank Ordering Functions
+@subsubsection Matrix Rank Ordering Functions
 
-@deftypefn {Matrix Function} {} DIAG (@var{m})
-@end deftypefn
+The @code{GRADE} and @code{RANK} functions each take a matrix @var{M}
+and return a matrix @var{r} with the same dimensions.  Each element in
+@var{r} ranges between 1 and the number of elements @var{n} in
+@var{M}, inclusive.  When the elements in @var{M} all have unique
+values, both of these functions yield the same results: the smallest
+element in @var{M} corresponds to value 1 in @var{r}, the next
+smallest to 2, and so on, up to the largest to @var{n}.  When multiple
+elements in @var{M} have the same value, these functions use different
+rules for handling the ties.
 
-@deftypefn {Matrix Function} {} NCOL (@var{m})
-@end deftypefn
+@deffn {Matrix Function} GRADE (@var{M})
+Returns a ranking of @var{M}, turning duplicate values into sequential
+ranks.  The returned matrix always contains each of the integers 1
+through the number of elements in the matrix exactly once.
 
-@deftypefn {Matrix Function} {} NROW (@var{m})
-@end deftypefn
+@t{GRADE(@{1, 0, 3; 3, 1, 2; 3, 0, 5@})} @result{} @t{@{3, 1, 6; 7, 4, 5; 8, 2, 9@}}
+@end deffn
 
-@node Matrix Rank Ordering Functions
-@subsection Matrix Rank Ordering Functions
+@deffn {Matrix Function} RNKORDER (@var{M})
+Returns a ranking of @var{M}, turning duplicate values into the mean
+of their sequential ranks.
 
-@deftypefn {Matrix Function} {} GRADE (@var{m})
-@end deftypefn
+@t{RNKORDER(@{1, 0, 3; 3, 1, 2; 3, 0, 5@})} @*@w{ }@result{} @t{@{3.5, 1.5, 7; 7, 3.5, 5; 7, 1.5, 9@}}
+@end deffn
 
-@deftypefn {Matrix Function} {} RNKORDER (@var{m})
-@end deftypefn
+@noindent
+One may use @code{GRADE} to sort a vector:
 
+@example
+COMPUTE v(GRADE(v))=v.   /* Sort v in ascending order.
+COMPUTE v(GRADE(-v))=v.  /* Sort v in descending order.
+@end example
 
 @node Matrix Algebra Functions
-@subsection Matrix Algebra Functions
+@subsubsection Matrix Algebra Functions
 
-@deftypefn {Matrix Function} {} CHOL (@var{m})
-@end deftypefn
+@deffn {Matrix Function} CHOL (@var{M})
+Matrix @var{M} must be an @math{@var{n}@times{}@var{n}} symmetric
+positive-definite matrix.  Returns an @math{@var{n}@times{}@var{n}}
+matrix @var{B} such that @math{@var{B}^T@times{}@var{B}=@var{M}}.
+@end deffn
 
-@deftypefn {Matrix Function} {} DESIGN (@var{m})
-@end deftypefn
+@deffn {Matrix Function} DESIGN (@var{M})
+Returns a design matrix for @var{M}.  The design matrix has the same
+number of rows as @var{M}.  Each column @var{c} in @var{M}, from left
+to right, yields a group of columns in the output.  For each unique
+value @var{v} in @var{c}, from top to bottom, add a column to the
+output in which @var{v} becomes 1 and other values become 0.
 
-@deftypefn {Matrix Function} {} DET (@var{m})
-@end deftypefn
+@pspp{} issues a warning if a column only contains a single unique value.
 
-@deftypefn {Matrix Function} {} EVAL (@var{m})
-@end deftypefn
+@format
+@t{DESIGN(@{1; 2; 3@}) @result{} @{1, 0, 0; 0, 1, 0; 0, 0, 1@}}
+@t{DESIGN(@{5; 8; 5@}) @result{} @{1, 0; 0, 1; 1, 0@}}
+@t{DESIGN(@{1, 5; 2, 8; 3, 5@})}
+ @result{} @t{@{1, 0, 0, 1, 0; 0, 1, 0, 0, 1; 0, 0, 1, 1, 0@}}
+@t{DESIGN(@{5; 5; 5@})} @result{} (warning)
+@end format
+@end deffn
 
-@deftypefn {Matrix Function} {} GINV (@var{m})
-@end deftypefn
+@deffn {Matrix Function} DET (@var{M})
+Returns the determinant of square matrix @var{M}.
+@end deffn
 
+@deffn {Matrix Function} EVAL (@var{M})
+Returns a column vector containing the eigenvalues of symmetric matrix
+@var{M}, sorted in ascending order.
 
-@deftypefn {Matrix Function} {} GSCH (@var{m})
-@end deftypefn
+Use @code{CALL EIGEN} (@pxref{CALL EIGEN}) to compute eigenvalues and
+eigenvectors of a matrix.
+@end deffn
 
+@deffn {Matrix Function} GINV (@var{M})
+Returns the @math{@var{k}@times{}@var{n}} matrix @var{A} that is the
+@dfn{generalized inverse} of @math{@var{n}@times{}@var{k}} matrix
+@var{M}, defined such that
+@math{@var{M}@times{}@var{A}@times{}@var{M}=@var{M}} and
+@math{@var{A}@times{}@var{M}@times{}@var{A}=@var{A}}.
+@end deffn
 
-@deftypefn {Matrix Function} {} INV (@var{m})
-@end deftypefn
 
+@deffn {Matrix Function} GSCH (@var{M})
+@end deffn
 
-@deftypefn {Matrix Function} {} KRONEKER (@var{m1}, @var{m2})
-@end deftypefn
 
+@deffn {Matrix Function} INV (@var{M})
+Returns the @math{@var{n}@times{}@var{n}} matrix @var{A} that is the
+inverse of @math{@var{n}@times{}@var{n}} matrix @var{M}, defined such
+that @math{@var{M}@times{}@var{A} = @var{A}@times{}@var{M} = I}, where
+@var{I} is the identity matrix.  @var{M} must not be singular, that
+is, @math{\det(@var{M}) \ne 0}.
+@end deffn
 
+@deffn {Matrix Function} KRONEKER (@var{Ma}, @var{Mb})
+Returns the @math{@var{pm}@times{}@var{qn}} matrix @var{P} that is the
+@dfn{Kroneker product} of @math{@var{m}@times{}@var{n}} matrix
+@var{Ma} and @math{@var{p}@times{}@var{q}} matrix @var{Mb}.  One may
+view @var{P} as the concatenation of multiple
+@math{@var{p}@times{}@var{q}} blocks, each of which is the scalar
+product of @var{Mb} by a different element of @var{Ma}.  For example,
+when @code{A} is a @math{2@times{}2} matrix, @code{KRONEKER(A, B)} is
+equivalent to @code{@{A(1,1)*B, A(1,2)*B; A(2,1)*B, A(2,2)*B@}}.
+@end deffn
 
-@deftypefn {Matrix Function} {} RANK (@var{m})
-@end deftypefn
+@deffn {Matrix Function} RANK (@var{M})
+@end deffn
 
 
 
 
-@deftypefn {Matrix Function} {} SOLVE (@var{ma}, @var{mb})
-@end deftypefn
+@deffn {Matrix Function} SOLVE (@var{Ma}, @var{Mb})
+@end deffn
 
 
-@deftypefn {Matrix Function} {} SVAL (@var{m})
-@end deftypefn
+@deffn {Matrix Function} SVAL (@var{M})
+@end deffn
 
 
-@deftypefn {Matrix Function} {} SWEEP (@var{m}, @var{s})
-@end deftypefn
+@deffn {Matrix Function} SWEEP (@var{M}, @var{n})
+@end deffn
 
 
-@deftypefn {Matrix Function} {} TRACE (@var{m})
-@end deftypefn
+@node Matrix IO
+@subsubsection I/O
 
+@deffn {Matrix Function} EOF (@var{file})
+@end deffn
 
-@node Matrix IO
-@subsection I/O
+@node Matrix CALL command
+@subsection The @code{CALL} Command
 
-@deftypefn {Matrix Function} {} EOF (@var{file})
-@end deftypefn
+@anchor{CALL EIGEN}