Mercurial > hg > octave-nkf
diff libinterp/corefcn/sparse.cc @ 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 | 2dcc4398950d |
children | c53e11fab75f |
line wrap: on
line diff
--- 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\