From 271203bf7fa683aae1b12fddf92f047fce294fe0 Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Thu, 7 Oct 2021 22:52:54 -0700 Subject: [PATCH] docs --- doc/matrices.texi | 164 +++++++++++++++++++++++++++++----------------- 1 file changed, 105 insertions(+), 59 deletions(-) diff --git a/doc/matrices.texi b/doc/matrices.texi index d0e3b7be55..8adf29b035 100644 --- a/doc/matrices.texi +++ b/doc/matrices.texi @@ -1120,10 +1120,23 @@ 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: + +@table @samp +@item s +Any scalar. + +@item n +A scalar with a nonnegative integer value. (Non-integers are rounded +down to the nearest integer.) + +@item v +A row or column vector. + +@item m +A matrix. +@end table @node Matrix Elementwise Functions @subsubsection Elementwise Functions @@ -1179,7 +1192,6 @@ Takes the square root of each element of @var{m}, which must not be negative. @end deftypefn - @node Matrix Logical Functions @subsubsection Logical Functions @@ -1196,105 +1208,143 @@ nonzero, or 0 if all of them are zero. @node Matrix Construction Functions @subsubsection Matrix Construction Functions -@deftypefn {Matrix Function} {} BLOCK (@var{m1}, @var{m2}, @dots{}) +@deftypefn {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 deftypefn -@deftypefn {Matrix Function} {} IDENT (@var{s}) -@deftypefnx {Matrix Function} {} IDENT (@var{sr}, @var{sc}) +@deftypefn {Matrix Function} {} IDENT (@var{n}) +@deftypefnx {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 deftypefn - -@deftypefn {Matrix Function} {} MAGIC (@var{m}) +@deftypefn {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 deftypefn - -@deftypefn {Matrix Function} {} MAKE (@var{sr}, @var{sc}, @var{sv}) +@deftypefn {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 deftypefn - @deftypefn {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 deftypefn -@deftypefn {Matrix Function} {} RESHAPE (@var{m}, @var{sr}, @var{sc}) +@deftypefn {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 deftypefn -@deftypefn {Matrix Function} {} TRANSPOS (@var{m}) -@deftypefnx {Matrix Function} {} T (@var{m}) +@deftypefn {Matrix Function} {} T (@var{m}) +@deftypefnx {Matrix Function} {} TRANSPOS (@var{m}) +Returns @var{m} with rows exchanged for columns. @end deftypefn -@deftypefn {Matrix Function} {} UNIFORM (@var{sr}, @var{sc}) +@deftypefn {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 deftypefn @node Matrix Minimum and Maximum and Sum Functions @subsubsection Minimum, Maximum, and Sum Functions -@deftypefn {Matrix Function} {} CMAX (@var{m}) -@end deftypefn - @deftypefn {Matrix Function} {} CMIN (@var{m}) +@deftypefnx {Matrix Function} {} CMAX (@var{m}) +@deftypefnx {Matrix Function} {} CSUM (@var{m}) +@deftypefnx {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 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}) +@deftypefnx {Matrix Function} {} MMAX (@var{m}) +@deftypefnx {Matrix Function} {} MSUM (@var{m}) +@deftypefnx {Matrix Function} {} MSSQ (@var{m}) +Returns the minimum, maximum, sum, or sum of squares, respectively, of +the elements of @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 - - @deftypefn {Matrix Function} {} RMIN (@var{m}) +@deftypefnx {Matrix Function} {} RMAX (@var{m}) +@deftypefnx {Matrix Function} {} RSUM (@var{m}) +@deftypefnx {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 deftypefn - -@deftypefn {Matrix Function} {} RSSQ (@var{m}) +@deftypefn {Matrix Function} {} SSCP (@var{m}) +Returns @code{T(@var{m}) * @var{m}}. @end deftypefn - -@deftypefn {Matrix Function} {} RSUM (@var{m}) +@deftypefn {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 deftypefn -@deftypefn {Matrix Function} {} SSCP (@var{m}) -@end deftypefn @node Matrix Property Functions @subsubsection Matrix Property Functions -@deftypefn {Matrix Function} {} DIAG (@var{m}) -@end deftypefn - -@deftypefn {Matrix Function} {} NCOL (@var{m}) +@deftypefn {Matrix Function} {} NROW (@var{m}) +@deftypefnx {Matrix Function} {} NCOL (@var{m}) +Returns the number of row or columns, respectively, in @var{m}. @end deftypefn -@deftypefn {Matrix Function} {} NROW (@var{m}) +@deftypefn {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 deftypefn @node Matrix Rank Ordering Functions @subsubsection Matrix Rank Ordering Functions @deftypefn {Matrix Function} {} GRADE (@var{m}) +Returns a matrix with the same dimensions as @var{m} in which each +elements is a unique integer, from 1 to the number of elements in +@var{m}, that corresponds to its rank within @var{m}. The smallest +element in @var{m} corresponds to value 1 in the returned matrix, the +next smallest to value 2, and so on. When multiple elements in +@var{m} have the same value, they are assigned consecutive unique +ranks in the return matrix. @end deftypefn +@noindent +The @code{GRADE} function can be used to sort a vector. For example, +the following syntax: + +@example +MATRIX. +COMPUTE v=@{2, 5, 1, 4, 9, 7, 8, 10, 6, 3@}. +COMPUTE v(GRADE(v))=v. +PRINT v. +END MATRIX. +@end example + +@noindent yields the following sorted output: + +@example +v + 1 2 3 4 5 6 7 8 9 10 +@end example + @deftypefn {Matrix Function} {} RNKORDER (@var{m}) @end deftypefn - @node Matrix Algebra Functions @subsubsection Matrix Algebra Functions @@ -1341,11 +1391,7 @@ nonzero, or 0 if all of them are zero. @end deftypefn -@deftypefn {Matrix Function} {} SWEEP (@var{m}, @var{s}) -@end deftypefn - - -@deftypefn {Matrix Function} {} TRACE (@var{m}) +@deftypefn {Matrix Function} {} SWEEP (@var{m}, @var{n}) @end deftypefn -- 2.30.2