Mercurial > hg > octave-nkf
changeset 19004:53af80da6781 stable
doc: Update documentation of sparse functions including seealso links.
* data.cc (Fall, Fany): Use non-zero instead of nonzero.
* data.cc (Fnnz, Fnzmax, Ffull): Rewrite docstrings, include more seealso links.
* sparse.cc (Fsparse): Rewrite docstring to include example of "sum" behavior
and "unique" behavior. Add more seealso links.
* sparse.cc (Fspalloc): Rewrite docstring, include more seealso links.
* spparms.cc (Fspparms): Add seealso links.
* amd.cc (Famd): Use nonzero instead of "non zero".
* nonzeros.m: Add seealso links.
* spaugment.m: Rewrite docstring, include more seealso links.
* spconvert.m: Rewrite docstring, include more seealso links.
* speye.m: Rewrite docstring, include more seealso links.
* spones.m: Add seealso links.
* sprand.m: Rewrite docstring, include more seealso links.
* sprandn.m: Rewrite docstring, include more seealso links.
* sprandsym.m: Rewrite docstring, include more seealso links.
* spy.m: Rewrite docstring, include more seealso links.
author | Rik <rik@octave.org> |
---|---|
date | Sun, 08 Jun 2014 16:32:12 -0700 |
parents | 48828394487d |
children | 2e68c34521e0 4c3c3cf9ef58 |
files | libinterp/corefcn/data.cc libinterp/corefcn/sparse.cc libinterp/corefcn/spparms.cc libinterp/dldfcn/amd.cc scripts/sparse/nonzeros.m scripts/sparse/spaugment.m scripts/sparse/spconvert.m scripts/sparse/speye.m scripts/sparse/spones.m scripts/sparse/sprand.m scripts/sparse/sprandn.m scripts/sparse/sprandsym.m scripts/sparse/spy.m |
diffstat | 13 files changed, 122 insertions(+), 79 deletions(-) [+] |
line wrap: on
line diff
--- a/libinterp/corefcn/data.cc +++ b/libinterp/corefcn/data.cc @@ -112,11 +112,11 @@ @deftypefn {Built-in Function} {} all (@var{x})\n\ @deftypefnx {Built-in Function} {} all (@var{x}, @var{dim})\n\ For a vector argument, return true (logical 1) if all elements of the vector\n\ -are nonzero.\n\ +are non-zero.\n\ \n\ For a matrix argument, return a row vector of logical ones and\n\ zeros with each element indicating whether all of the elements of the\n\ -corresponding column of the matrix are nonzero. For example:\n\ +corresponding column of the matrix are non-zero. For example:\n\ \n\ @example\n\ @group\n\ @@ -159,11 +159,11 @@ @deftypefn {Built-in Function} {} any (@var{x})\n\ @deftypefnx {Built-in Function} {} any (@var{x}, @var{dim})\n\ For a vector argument, return true (logical 1) if any element of the vector\n\ -is nonzero.\n\ +is non-zero.\n\ \n\ For a matrix argument, return a row vector of logical ones and\n\ zeros with each element indicating whether any of the elements of the\n\ -corresponding column of the matrix are nonzero. For example:\n\ +corresponding column of the matrix are non-zero. For example:\n\ \n\ @example\n\ @group\n\ @@ -2677,9 +2677,9 @@ DEFUN (nnz, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {@var{scalar} =} nnz (@var{a})\n\ -Return the number of non zero elements in @var{a}.\n\ -@seealso{sparse, nzmax}\n\ +@deftypefn {Built-in Function} {@var{n} =} nnz (@var{a})\n\ +Return the number of non-zero elements in @var{a}.\n\ +@seealso{nzmax, nonzeros, find}\n\ @end deftypefn") { octave_value retval; @@ -2694,12 +2694,12 @@ DEFUN (nzmax, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {@var{scalar} =} nzmax (@var{SM})\n\ +@deftypefn {Built-in Function} {@var{n} =} nzmax (@var{SM})\n\ Return the amount of storage allocated to the sparse matrix @var{SM}.\n\ +\n\ Note that Octave tends to crop unused memory at the first opportunity\n\ -for sparse objects. There are some cases of user created sparse objects\n\ -where the value returned by @dfn{nzmax} will not be the same as @dfn{nnz},\n\ -but in general they will give the same result.\n\ +for sparse objects. Thus, in general the value of @code{nzmax} will be the\n\ +the same as @code{nnz} except for some cases of user-created sparse objects.\n\ @seealso{nnz, spalloc, sparse}\n\ @end deftypefn") { @@ -5223,9 +5223,9 @@ DEFUN (full, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {@var{FM} =} full (@var{SM})\n\ -Return a full storage matrix from a sparse, diagonal, permutation matrix\n\ +Return a full storage matrix from a sparse, diagonal, permutation matrix,\n\ or a range.\n\ -@seealso{sparse}\n\ +@seealso{sparse, issparse}\n\ @end deftypefn") { octave_value retval;
--- a/libinterp/corefcn/sparse.cc +++ b/libinterp/corefcn/sparse.cc @@ -60,37 +60,69 @@ DEFUN (sparse, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {@var{s} =} sparse (@var{a})\n\ -@deftypefnx {Built-in Function} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n}, @var{nzmax})\n\ +@deftypefnx {Built-in Function} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n})\n\ @deftypefnx {Built-in Function} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv})\n\ +@deftypefnx {Built-in Function} {@var{s} =} sparse (@var{m}, @var{n})\n\ @deftypefnx {Built-in Function} {@var{s} =} sparse (@var{i}, @var{j}, @var{s}, @var{m}, @var{n}, \"unique\")\n\ -@deftypefnx {Built-in Function} {@var{s} =} sparse (@var{m}, @var{n})\n\ -Create a sparse matrix from the full matrix or row, column, value triplets.\n\ +@deftypefnx {Built-in Function} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n}, @var{nzmax})\n\ +Create a sparse matrix from a full matrix or row, column, value triplets.\n\ +\n\ If @var{a} is a full matrix, convert it to a sparse matrix representation,\n\ removing all zero values in the process.\n\ \n\ -Given the integer index vectors @var{i} and @var{j}, a 1-by-@code{nnz} vector\n\ -of real of complex values @var{sv}, overall dimensions @var{m} and @var{n}\n\ -of the sparse matrix. The argument @code{nzmax} is ignored but accepted for\n\ -compatibility with @sc{matlab}. If @var{m} or @var{n} are not specified\n\ -their values are derived from the maximum index in the vectors @var{i} and\n\ -@var{j} as given by @code{@var{m} = max (@var{i})},\n\ -@code{@var{n} = max (@var{j})}.\n\ +Given the integer index vectors @var{i} and @var{j}, and a 1-by-@code{nnz}\n\ +vector of real or complex values @var{sv}, construct the sparse matrix\n\ +@code{S(@var{i}(@var{k}),@var{j}(@var{k})) = @var{sv}(@var{k})} with overall\n\ +dimensions @var{m} and @var{n}. If any of @var{sv}, @var{i} or @var{j} are\n\ +scalars, they are expanded to have a common size.\n\ +\n\ +If @var{m} or @var{n} are not specified their values are derived from the\n\ +maximum index in the vectors @var{i} and @var{j} as given by\n\ +@code{@var{m} = max (@var{i})}, @code{@var{n} = max (@var{j})}.\n\ +\n\ +@strong{Note}: if multiple values are specified with the same @var{i},\n\ +@var{j} indices, the corresponding value in @var{s} will be the sum of the\n\ +values at the repeated location. See @code{accumarray} for an example of how\n\ +to produce different behavior, such as taking the minimum instead.\n\ +\n\ +If the option @qcode{\"unique\"} is given, and more than one value is\n\ +specified at the same @var{i}, @var{j} indices, then the last specified\n\ +value will be used.\n\ +\n\ +@code{sparse (@var{m}, @var{n})} will create an empty @var{m}x@var{n} sparse\n\ +matrix and is equivalent to @code{sparse ([], [], [], @var{m}, @var{n})}\n\ +\n\ +The argument @code{nzmax} is ignored but accepted for compatibility with\n\ +@sc{matlab}.\n\ +\n\ +Example 1 (sum at repeated indices):\n\ \n\ -@strong{Note}: if multiple values are specified with the same\n\ -@var{i}, @var{j} indices, the corresponding values in @var{s} will\n\ -be added. See @code{accumarray} for an example of how to produce different\n\ -behavior, such as taking the minimum instead.\n\ +@example\n\ +@group\n\ +@var{i} = [1 1 2]; @var{j} = [1 1 2]; @var{sv} = [3 4 5];\n\ +sparse (@var{i}, @var{j}, @var{sv}, 3, 4)\n\ +@result{} \n\ +Compressed Column Sparse (rows = 3, cols = 4, nnz = 2 [17%])\n\ +\n\ + (1, 1) -> 7\n\ + (2, 2) -> 5\n\ +@end group\n\ +@end example\n\ \n\ -Given the option @qcode{\"unique\"}, if more than two values are specified\n\ -for the same @var{i}, @var{j} indices, the last specified value will be\n\ -used.\n\ +Example 2 (\"unique\" option):\n\ \n\ -@code{sparse (@var{m}, @var{n})} is equivalent to\n\ -@code{sparse ([], [], [], @var{m}, @var{n}, 0)}\n\ +@example\n\ +@group\n\ +@var{i} = [1 1 2]; @var{j} = [1 1 2]; @var{sv} = [3 4 5];\n\ +sparse (@var{i}, @var{j}, @var{sv}, 3, 4, \"unique\")\n\ +@result{} \n\ +Compressed Column Sparse (rows = 3, cols = 4, nnz = 2 [17%])\n\ \n\ -If any of @var{sv}, @var{i} or @var{j} are scalars, they are expanded\n\ -to have a common size.\n\ -@seealso{full, accumarray}\n\ + (1, 1) -> 4\n\ + (2, 2) -> 5\n\ +@end group\n\ +@end example\n\ +@seealso{full, accumarray, spalloc, spdiags, speye, spones, sprand, sprandn, sprandsym, spconvert, spfun}\n\ @end deftypefn") { octave_value retval; @@ -191,10 +223,11 @@ "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {@var{s} =} spalloc (@var{m}, @var{n}, @var{nz})\n\ Create an @var{m}-by-@var{n} sparse matrix with pre-allocated space for at\n\ -most @var{nz} nonzero elements. This is useful for building the matrix\n\ -incrementally by a sequence of indexed assignments. Subsequent indexed\n\ -assignments will reuse the pre-allocated memory, provided they are of one of\n\ -the simple forms\n\ +most @var{nz} nonzero elements.\n\ +\n\ +This is useful for building a matrix incrementally by a sequence of indexed\n\ +assignments. Subsequent indexed assignments after @code{spalloc} will reuse\n\ +the pre-allocated memory, provided they are of one of the simple forms\n\ \n\ @itemize\n\ @item @code{@var{s}(I:J) = @var{x}}\n\ @@ -215,8 +248,8 @@ @end itemize\n\ \n\ Partial movement of data may still occur, but in general the assignment will\n\ -be more memory and time-efficient under these circumstances. In particular,\n\ -it is possible to efficiently build a pre-allocated sparse matrix from\n\ +be more memory and time efficient under these circumstances. In particular,\n\ +it is possible to efficiently build a pre-allocated sparse matrix from a\n\ contiguous block of columns.\n\ \n\ The amount of pre-allocated memory for a given matrix may be queried using\n\
--- a/libinterp/corefcn/spparms.cc +++ b/libinterp/corefcn/spparms.cc @@ -100,6 +100,7 @@ @qcode{\"defaults\"}. The special keyword @qcode{\"tight\"} can be used to\n\ set the mmd solvers to attempt a sparser solution at the potential cost of\n\ longer running time.\n\ +@seealso{chol, colamd, lu, qr, symamd}\n\ @end deftypefn") { octave_value_list retval;
--- a/libinterp/dldfcn/amd.cc +++ b/libinterp/dldfcn/amd.cc @@ -73,7 +73,7 @@ The value of dense must be a positive scalar and its default value is 10.0\n\ \n\ @item @var{opts}.aggressive\n\ -If this value is a non zero scalar, then @code{amd} performs aggressive\n\ +If this value is a nonzero scalar, then @code{amd} performs aggressive\n\ absorption. The default is not to perform aggressive absorption.\n\ @end table\n\ \n\
--- a/scripts/sparse/nonzeros.m +++ b/scripts/sparse/nonzeros.m @@ -19,6 +19,7 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} nonzeros (@var{s}) ## Return a vector of the non-zero values of the sparse matrix @var{s}. +## @seealso{find, nnz} ## @end deftypefn function t = nonzeros (s)
--- a/scripts/sparse/spaugment.m +++ b/scripts/sparse/spaugment.m @@ -18,7 +18,9 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {@var{s} =} spaugment (@var{A}, @var{c}) -## Create the augmented matrix of @var{A}. This is given by +## Create the augmented matrix of @var{A}. +## +## This is given by ## ## @example ## @group @@ -47,7 +49,7 @@ ## As the matrix @var{s} is symmetric indefinite it can be factorized ## with @code{lu}, and the minimum norm solution can therefore be found ## without the need for a @code{qr} factorization. As the residual -## error will be @code{zeros (@var{m}, @var{m})} for under determined +## error will be @code{zeros (@var{m}, @var{m})} for underdetermined ## problems, and example can be ## ## @example @@ -69,6 +71,7 @@ ## ## In general the left division operator is more stable and faster than ## using the @code{spaugment} function. +## @seealso{mldivide} ## @end deftypefn function s = spaugment (A, c)
--- a/scripts/sparse/spconvert.m +++ b/scripts/sparse/spconvert.m @@ -18,12 +18,14 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {@var{x} =} spconvert (@var{m}) -## This function converts for a simple sparse matrix format easily -## produced by other programs into Octave's internal sparse format. The -## input @var{x} is either a 3 or 4 column real matrix, containing -## the row, column, real and imaginary parts of the elements of the +## Convert a simple sparse matrix format easily generated by other programs +## into Octave's internal sparse format. +## +## The input @var{m} is either a 3 or 4 column real matrix, containing +## the row, column, real, and imaginary parts of the elements of the ## sparse matrix. An element with a zero real and imaginary part can ## be used to force a particular matrix size. +## @seealso{sparse} ## @end deftypefn function s = spconvert (m)
--- a/scripts/sparse/speye.m +++ b/scripts/sparse/speye.m @@ -17,17 +17,18 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {@var{y} =} speye (@var{m}) -## @deftypefnx {Function File} {@var{y} =} speye (@var{m}, @var{n}) -## @deftypefnx {Function File} {@var{y} =} speye (@var{sz}) -## Return a sparse identity matrix. This is significantly more -## efficient than @code{sparse (eye (@var{m}))} as the full matrix -## is not constructed. +## @deftypefn {Function File} {@var{s} =} speye (@var{m}, @var{n}) +## @deftypefnx {Function File} {@var{s} =} speye (@var{m}) +## @deftypefnx {Function File} {@var{s} =} speye (@var{sz}) +## Return a sparse identity matrix of size @var{m}x@var{n}. ## -## Called with a single argument a square matrix of size @var{m} by -## @var{m} is created. Otherwise a matrix of @var{m} by @var{n} is -## created. If called with a single vector argument, this argument -## is taken to be the size of the matrix to create. +## The implementation is significantly more efficient than +## @code{sparse (eye (@var{m}))} as the full matrix is not constructed. +## +## Called with a single argument a square matrix of size +## @var{m}-by-@var{m} is created. If called with a single vector argument +## @var{sz}, this argument is taken to be the size of the matrix to create. +## @seealso{sparse, spdiags, eye} ## @end deftypefn function s = speye (m, n)
--- a/scripts/sparse/spones.m +++ b/scripts/sparse/spones.m @@ -20,6 +20,7 @@ ## @deftypefn {Function File} {@var{r} =} spones (@var{S}) ## Replace the non-zero entries of @var{S} with ones. This creates a ## sparse matrix with the same structure as @var{S}. +## @seealso{sparse, sprand, sprandn, sprandsym, spfun, spy} ## @end deftypefn function r = spones (S)
--- a/scripts/sparse/sprand.m +++ b/scripts/sparse/sprand.m @@ -23,13 +23,13 @@ ## @deftypefn {Function File} {} sprand (@var{m}, @var{n}, @var{d}) ## @deftypefnx {Function File} {} sprand (@var{s}) ## Generate a random sparse matrix. The size of the matrix will be -## @var{m} by @var{n}, with a density of values given by @var{d}. -## @var{d} should be between 0 and 1. Values will be uniformly -## distributed between 0 and 1. +## @var{m}x@var{n}, with a density of values given by @var{d}. @var{d} must +## be between 0 and 1 inclusive. Values will be uniformly distributed between +## 0 and 1. ## ## If called with a single matrix argument, a random sparse matrix is ## generated wherever the matrix @var{S} is non-zero. -## @seealso{sprandn, sprandsym} +## @seealso{sprandn, sprandsym, spones, sparse} ## @end deftypefn ## Author: Paul Kienzle <pkienzle@users.sf.net>
--- a/scripts/sparse/sprandn.m +++ b/scripts/sparse/sprandn.m @@ -23,13 +23,13 @@ ## @deftypefn {Function File} {} sprandn (@var{m}, @var{n}, @var{d}) ## @deftypefnx {Function File} {} sprandn (@var{s}) ## Generate a random sparse matrix. The size of the matrix will be -## @var{m} by @var{n}, with a density of values given by @var{d}. -## @var{d} should be between 0 and 1. Values will be normally -## distributed with mean of zero and variance 1. +## @var{m}x@var{n}, with a density of values given by @var{d}. @var{d} must be +## between 0 and 1 inclusive. Values will be normally distributed with a mean +## of zero and a variance of 1. ## ## If called with a single matrix argument, a random sparse matrix is ## generated wherever the matrix @var{S} is non-zero. -## @seealso{sprand, sprandsym} +## @seealso{sprand, sprandsym, spones, sparse} ## @end deftypefn ## Author: Paul Kienzle <pkienzle@users.sf.net>
--- a/scripts/sparse/sprandsym.m +++ b/scripts/sparse/sprandsym.m @@ -20,15 +20,15 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} sprandsym (@var{n}, @var{d}) ## @deftypefnx {Function File} {} sprandsym (@var{s}) -## Generate a symmetric random sparse matrix. The size of the matrix will be -## @var{n} by @var{n}, with a density of values given by @var{d}. -## @var{d} should be between 0 and 1. Values will be normally -## distributed with mean of zero and variance 1. +## Generate a symmetric random sparse matrix. ## -## If called with a single matrix argument, a random sparse matrix is -## generated wherever the matrix @var{S} is non-zero in its lower -## triangular part. -## @seealso{sprand, sprandn} +## The size of the matrix will be @var{n}x@var{n}, with a density of values +## given by @var{d}. @var{d} must be between 0 and 1 inclusive. Values will +## be normally distributed with a mean of zero and a variance of 1. +## +## If called with a single matrix argument, a random sparse matrix is generated +## wherever the matrix @var{S} is non-zero in its lower triangular part. +## @seealso{sprand, sprandn, spones, sparse} ## @end deftypefn function S = sprandsym (n, d)
--- a/scripts/sparse/spy.m +++ b/scripts/sparse/spy.m @@ -20,11 +20,12 @@ ## @deftypefn {Function File} {} spy (@var{x}) ## @deftypefnx {Function File} {} spy (@dots{}, @var{markersize}) ## @deftypefnx {Function File} {} spy (@dots{}, @var{line_spec}) -## Plot the sparsity pattern of the sparse matrix @var{x}. If the argument -## @var{markersize} is given as a scalar value, it is used to determine the -## point size in the plot. If the string @var{line_spec} is given it is -## passed to @code{plot} and determines the appearance of the plot. -## @seealso{plot} +## Plot the sparsity pattern of the sparse matrix @var{x}. +## +## If the argument @var{markersize} is given as a scalar value, it is used to +## determine the point size in the plot. If the string @var{line_spec} is +## given it is passed to @code{plot} and determines the appearance of the plot. +## @seealso{plot, gplot} ## @end deftypefn function spy (x, varargin)