Mercurial > forge

changeset 12642:a95bee17f7fd octave-forge

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
reorganized the documentation string to have the @deftypefnx lines one after the other. small documentation bugs corrected on the way.
author michelemartone
date Sun, 21 Jun 2015 14:34:28 +0000
parents e3998369a32e
children dc5803650a98
files main/sparsersb/doc/sparsersb.txt main/sparsersb/src/sparsersb.cc
diffstat 2 files changed, 123 insertions(+), 76 deletions(-) [+]
line wrap: on
line diff
--- a/main/sparsersb/doc/sparsersb.txt	Fri Jun 19 16:24:09 2015 +0000
+++ b/main/sparsersb/doc/sparsersb.txt	Sun Jun 21 14:34:28 2015 +0000
@@ -1,26 +1,47 @@
 
  -- Loadable Function: S = sparsersb (A)
-     Create a sparse RSB matrix from the full matrix A.
-
+ -- Loadable Function: S = sparsersb (I, J, SV, M, N)
+ -- Loadable Function: S = sparsersb (I, J, SV, M, N, NZMAX)
+ -- Loadable Function: S = sparsersb (I, J, SV)
+ -- Loadable Function: S = sparsersb (M, N)
+ -- Loadable Function: S = sparsersb (I, J, S, M, N, "unique")
+ -- Loadable Function: S = sparsersb ("set", OPN, OPV)
+ -- Loadable Function: S = sparsersb (A, "get", MIF)
+ -- Loadable Function: S = sparsersb (A, QS)
+ -- Loadable Function: sparsersb (A,"save",MTXFILENAME)
  -- Loadable Function: [S, NROWS, NCOLS, NNZ, REPINFO, FIELD, SYMMETRY]
 = sparsersb (MTXFILENAME, MTXTYPESTRING)
-     Create a sparse RSB matrix by loading the Matrix Market matrix
-     file named MTXFILENAME. The optional argument MTXTYPESTRING can
-     specify either real ("D") or complex ("Z") type. Default is real.
-     In the case MTXFILENAME is "?", a string listing the available
-     numerical types with BLAS-style characters will be returned. If
-     the file turns out to contain a Matrix Market vector, this will be
-     loaded as such.
+ -- Loadable Function: S = sparsersb (A,"render", FILENAME[, RWIDTH,
+          RHEIGHT])
+ -- Loadable Function: [O =] sparsersb (A,"autotune"[, TRANSA, NRHS,
+          MAXR, TMAX, TN, SF])
+     Create or manipulate sparse matrices using the RSB format provided
+     by librsb, as similarly as possible to `sparse'.
+
+     If A is a full matrix, convert it to a sparse matrix
+     representation, removing all zero values in the process.
+
+     Given the integer index vectors I and J, and a 1-by-`nnz' vector
+     of real or complex values SV, construct the sparse matrix
+     `S(I(K),J(K)) = SV(K)' with overall dimensions M and N.
 
- -- Loadable Function: sparsersb (A,"save",MTXFILENAME)
-     Saves a sparse RSB matrix as a Matrix Market matrix file named
-     MTXFILENAME.
+     The argument `NZMAX' is ignored but accepted for compatibility
+     with MATLAB and `sparsersb'.
+
+     If M or N are not specified their values are derived from the
+     maximum index in the vectors I and J as given by `M = max (I)', `N
+     = max (J)'.
 
- -- Loadable Function: S = sparsersb (I, J, SV, M, N, NZMAX)
-     Create a sparse RSB matrix given integer index vectors I and J, a
-     1-by-`nnz' vector of real of complex values SV, overall dimensions
-     M and N of the sparse matrix.  The argument `nzmax' is ignored but
-     accepted for compatibility with MATLAB.
+     Can load a matrix from a Matrix Market matrix file named
+     MTXFILENAME. The optional argument MTXTYPESTRING can specify
+     either real ("D") or complex ("Z") type. Default is real.  In the
+     case MTXFILENAME is "?", a string listing the available numerical
+     types with BLAS-style characters will be returned. If the file
+     turns out to contain a Matrix Market dense vector, this will be
+     loaded.
+
+     If "save" is specified, saves a sparse RSB matrix as a Matrix
+     Market matrix file named MTXFILENAME.
 
      *Note*: if multiple values are specified with the same I, J
      indices, the corresponding values in S will be added.
@@ -31,46 +52,43 @@
           s = sparsersb (i, j, s, m, n, "summation")
           s = sparsersb (i, j, s, m, n, "sum")
 
- -- Loadable Function: S = sparsersb (I, J, S, M, N, "unique")
-     Same as above, except that if more than two values are specified
-     for the same I, J indices, the last specified value will be used.
+     If the optional "unique" keyword is specified, then if more than
+     two values are specified for the same I, J indices, only the last
+     value will be used.
 
- -- Loadable Function: S = sparsersb (I, J, SV)
-     Uses `M = max (I)', `N = max (J)'
+     `sparsersb (M, N)' will create an empty MxN sparse matrix and is
+     equivalent to `sparsersb ([], [], [], M, N)'.
 
- -- Loadable Function: S = sparsersb (M, N)
-     If M and N are integers, equivalent to `sparsersb ([], [], [], M,
-     N, 0)'
+     If M or N are not specified, then `M = max (I)', `N = max (J)'.
 
- -- Loadable Function: S = sparsersb ("set", OPN, OPV)
      If OPN is a string representing a valid librsb option name and OPV
-     is a string representing a valid librsb option value, the
-     corresponding librsb option will be set to that value.
+     is a string representing a valid librsb option value, these will
+     be passed to the `rsb_lib_set_opt_str()' function.
 
- -- Loadable Function: S = sparsersb (A, "get", MIF)
      If MIF is a string specifying a valid librsb matrix info string
-     (valid for librsb's rsb_mtx_get_info_from_string()), then the
+     (valid for librsb's `rsb_mtx_get_info_from_string()'), then the
      corresponding value will be returned for matrix A. If MIF is the
      an empty string (""), matrix structure information will be
      returned.
 
- -- Loadable Function: S = sparsersb (A, S)
-     If A is a sparsersb matrix and S is a string, S will be
+     If A is a sparsersb matrix and QS is a string, QS will be
      interpreted as a query string about matrix A.
 
- -- Loadable Function: S = sparsersb (A,"render", FILENAME[, RWIDTH,
-          RHEIGHT])
-     If A is a sparsersb matrix and FILENAME is a string, A will be
-     rendered as an Encapsulated Postcript file FILENAME. Optionally,
-     width and height can be specified. Defaults are 512.
+     If A is a sparsersb matrix and the "render" keyword is specified,
+     and FILENAME is a string, A will be rendered as an Encapsulated
+     Postcript file FILENAME. Optionally, width and height can be
+     specified in `RWIDTH, RHEIGHT'. Defaults are 512.
 
- -- Loadable Function: [O =] sparsersb (A,"autotune"[, TRANSA, NRHS,
-          MAXR, TMAX, TN, SF])
-     If A is a sparsersb matrix, autotuning of the matrix will take
-     place, with SpMV and autotuning parameters. After the "autotune"
-     string, the remaining parameters are optional. If giving an output
-     argument O, that will be assigned to the autotuned matrix, and the
-     input one A will remain unchanged.
+     If A is a sparsersb matrix and the "autotune" keyword is
+     specified, autotuning of the matrix will take place, with SpMV and
+     autotuning parameters. After the "autotune" string, the remaining
+     parameters are optional. Parameter TRANSA specifies whether to
+     tune for untransposed ("n") or transposed ("t"); NRHS the number
+     of right hand sides; MAXR the number of tuning rounds; TMAX the
+     threads to use. If giving an output argument O, that will be
+     assigned to the autotuned matrix, and the input one A will remain
+     unchanged. See librsb documentation for `rsb_tune_spmm' to learn
+     more.
 
      Please note that on `sparsersb' type variables are available most,
      but not all of the operators available for `full' or `sparse'
--- a/main/sparsersb/src/sparsersb.cc	Fri Jun 19 16:24:09 2015 +0000
+++ b/main/sparsersb/src/sparsersb.cc	Sun Jun 21 14:34:28 2015 +0000
@@ -220,13 +220,19 @@
 #define RSBOI_BINOP_PREVAILING_TYPE(V1,V2) RSBOI_TYPECODE
 #endif
 #if defined(RSB_LIBRSB_VER) && (RSB_LIBRSB_VER>=10100)
-#define RSBOI_10100_DOC \
+#define RSBOI_10100_DOCH \
 "@deftypefnx {Loadable Function} {@var{s} =} "RSBOI_FNS" (@var{A},\"render\", @var{filename}[, @var{rWidth}, @var{rHeight}])\n"\
-"If @var{A} is a "RSBOI_FNS" matrix and @var{filename} is a string, @var{A} will be rendered as an Encapsulated Postcript file @var{filename}. Optionally, width and height can be specified. Defaults are 512.\n"\
 "@deftypefnx {Loadable Function} {[@var{O} =]} "RSBOI_FNS" (@var{A},\"autotune\"[, @var{transA}, @var{nrhs}, @var{maxr}, @var{tmax}, @var{tn}, @var{sf}])\n"\
-"If @var{A} is a "RSBOI_FNS" matrix, autotuning of the matrix will take place, with SpMV and autotuning parameters. After the \"autotune\" string, the remaining parameters are optional. If giving an output argument @var{O}, that will be assigned to the autotuned matrix, and the input one @var{A} will remain unchanged.\n"
+
+#define RSBOI_10100_DOC \
+\
+"If @var{A} is a "RSBOI_FNS" matrix and the \"render\" keyword is specified, and @var{filename} is a string, @var{A} will be rendered as an Encapsulated Postcript file @var{filename}. Optionally, width and height can be specified in @code{@var{rWidth}, @var{rHeight}}. Defaults are 512.\n"\
+"\n"\
+\
+"If @var{A} is a "RSBOI_FNS" matrix and the \"autotune\" keyword is specified, autotuning of the matrix will take place, with SpMV and autotuning parameters. After the \"autotune\" string, the remaining parameters are optional. Parameter @var{transA} specifies whether to tune for untransposed (\"n\") or transposed (\"t\"); @var{nrhs} the number of right hand sides; @var{maxr} the number of tuning rounds; @var{tmax} the threads to use. If giving an output argument @var{O}, that will be assigned to the autotuned matrix, and the input one @var{A} will remain unchanged. See librsb documentation for @code{rsb_tune_spmm} to learn more.\n"
 #else
 #define RSBOI_10100_DOC	""
+#define RSBOI_10100_DOCH	""
 #endif
 
 void rsboi_strerr(rsb_err_t errval)
@@ -1914,24 +1920,45 @@
 DEFUN_DLD (RSB_SPARSERSB_LABEL, args, nargout,
 "-*- texinfo -*-\n\
 @deftypefn {Loadable Function} {@var{s} =} "RSBOI_FNS" (@var{a})\n\
-Create a sparse RSB matrix from the full matrix @var{a}.\n"\
-/*is forced back to a full matrix if resulting matrix is sparse\n*/\
-"\n\
+@deftypefnx {Loadable Function} {@var{s} =} "RSBOI_FNS" (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n})\n\
+@deftypefnx {Loadable Function} {@var{s} =} "RSBOI_FNS" (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n}, @var{nzmax})\n\
+@deftypefnx {Loadable Function} {@var{s} =} "RSBOI_FNS" (@var{i}, @var{j}, @var{sv})\n\
+@deftypefnx {Loadable Function} {@var{s} =} "RSBOI_FNS" (@var{m}, @var{n})\n\
+@deftypefnx {Loadable Function} {@var{s} =} "RSBOI_FNS" (@var{i}, @var{j}, @var{s}, @var{m}, @var{n}, \"unique\")\n\
+@deftypefnx {Loadable Function} {@var{s} =} "RSBOI_FNS" (\"set\", @var{opn}, @var{opv})\n\
+@deftypefnx {Loadable Function} {@var{s} =} "RSBOI_FNS" (@var{A}, \"get\", @var{mif})\n\
+@deftypefnx {Loadable Function} {@var{s} =} "RSBOI_FNS" (@var{A}, @var{QS})\n\
+@deftypefnx {Loadable Function} "RSBOI_FNS" (@var{a},\"save\",@var{mtxfilename})\n\
 @deftypefnx {Loadable Function} {[@var{s}, @var{nrows}, @var{ncols}, @var{nnz}, @var{repinfo}, @var{field}, @var{symmetry}] =} "RSBOI_FNS" (@var{mtxfilename}, @var{mtxtypestring})\n\
-Create a sparse RSB matrix by loading the Matrix Market matrix file named @var{mtxfilename}. The optional argument @var{mtxtypestring} can specify either real (\"D\") or complex (\"Z\") type. Default is real.\n"\
-"In the case @var{mtxfilename} is \""RSBOI_LIS"\", a string listing the available numerical types with BLAS-style characters will be returned. If the file turns out to contain a Matrix Market vector, this will be loaded as such.\n"\
-
-
+"RSBOI_10100_DOCH""\
+\
+"\n"\
+"Create or manipulate sparse matrices using the RSB format provided by librsb, as similarly as possible to @code{sparse}.\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\
-@deftypefnx {Loadable Function} "RSBOI_FNS" (@var{a},\"save\",@var{mtxfilename})\n\
-Saves a sparse RSB matrix as a Matrix Market matrix file named @var{mtxfilename}.\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}.  \n\
+\nThe argument\n\
+@code{@var{nzmax}} is ignored but accepted for compatibility with @sc{Matlab} and @code{sparsersb}.\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\
+\
+Can load a matrix from a Matrix Market matrix file named @var{mtxfilename}. The optional argument @var{mtxtypestring} can specify either real (\"D\") or complex (\"Z\") type. Default is real.\n"\
+"In the case @var{mtxfilename} is \""RSBOI_LIS"\", a string listing the available numerical types with BLAS-style characters will be returned. If the file turns out to contain a Matrix Market dense vector, this will be loaded.\n"\
+\
+\
 "\n\
-@deftypefnx {Loadable Function} {@var{s} =} "RSBOI_FNS" (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n}, @var{nzmax})\n\
-Create a sparse RSB matrix given integer index vectors @var{i} and @var{j},\n\
-a 1-by-@code{nnz} vector of real of complex values @var{sv}, overall\n\
-dimensions @var{m} and @var{n} of the sparse matrix.  The argument\n\
-@code{nzmax} is ignored but accepted for compatibility with @sc{Matlab}.\n\
-\n\
+\
+If \"save\" is specified, saves a sparse RSB matrix as a Matrix Market matrix file named @var{mtxfilename}.\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.\n\
@@ -1948,24 +1975,26 @@
 "@end group\n\
 @end example\n\
 \n\
-@deftypefnx {Loadable Function} {@var{s} =} "RSBOI_FNS" (@var{i}, @var{j}, @var{s}, @var{m}, @var{n}, \"unique\")\n\
-Same as above, except that if more than two values are specified for the\n\
-same @var{i}, @var{j} indices, the last specified value will be used.\n\
+\
+If the optional \"unique\" keyword is specified, then if more than two values are specified for the\n\
+same @var{i}, @var{j} indices, only the last value will be used.\n\
 \n\
-@deftypefnx {Loadable Function} {@var{s} =} "RSBOI_FNS" (@var{i}, @var{j}, @var{sv})\n\
-Uses @code{@var{m} = max (@var{i})}, @code{@var{n} = max (@var{j})}\n\
+@code{"RSBOI_FNS" (@var{m}, @var{n})} will create an empty @var{m}x@var{n} sparse\n\
+matrix and is equivalent to @code{"RSBOI_FNS" ([], [], [], @var{m}, @var{n})}.\n\
+\n\
+\
 \n\
-@deftypefnx {Loadable Function} {@var{s} =} "RSBOI_FNS" (@var{m}, @var{n})\n\
-If @var{m} and @var{n} are integers, equivalent to @code{"RSBOI_FNS" ([], [], [], @var{m}, @var{n}, 0)}\n\
+\
+If @var{m} or @var{n} are not specified, then @code{@var{m} = max (@var{i})}, @code{@var{n} = max (@var{j})}.\n\
 \n\
-@deftypefnx {Loadable Function} {@var{s} =} "RSBOI_FNS" (\"set\", @var{opn}, @var{opv})\n\
-If @var{opn} is a string representing a valid librsb option name and @var{opv} is a string representing a valid librsb option value, the corresponding librsb option will be set to that value.\n\
+\
+If @var{opn} is a string representing a valid librsb option name and @var{opv} is a string representing a valid librsb option value, these will be passed to the @code{rsb_lib_set_opt_str()} function.\n\
 \n\
-@deftypefnx {Loadable Function} {@var{s} =} "RSBOI_FNS" (@var{A}, \"get\", @var{mif})\n\
-If @var{mif} is a string specifying a valid librsb matrix info string (valid for librsb's rsb_mtx_get_info_from_string()), then the corresponding value will be returned for matrix @var{A}. If @var{mif} is the an empty string (\"\"), matrix structure information will be returned.\n\
+\
+If @var{mif} is a string specifying a valid librsb matrix info string (valid for librsb's @code{rsb_mtx_get_info_from_string()}), then the corresponding value will be returned for matrix @var{A}. If @var{mif} is the an empty string (\"\"), matrix structure information will be returned.\n\
 \n\
-@deftypefnx {Loadable Function} {@var{s} =} "RSBOI_FNS" (@var{A}, @var{S})\n\
-If @var{A} is a "RSBOI_FNS" matrix and @var{S} is a string, @var{S} will be interpreted as a query string about matrix @var{A}.\n\
+\
+If @var{A} is a "RSBOI_FNS" matrix and @var{QS} is a string, @var{QS} will be interpreted as a query string about matrix @var{A}.\n\
 \n"\
 /*If any of @var{sv}, @var{i} or @var{j} are scalars, they are expanded\n\ 
 to have a common size.\n*/
@@ -2082,7 +2111,7 @@
 	{
 		rsb_err_t errval = RSB_ERR_NO_ERROR;
 		std::string rmf = args(2).string_value();
-		rsb_coo_idx_t pmWidth = 512, pmHeight = 512;
+		rsb_coo_idx_t pmWidth = 512, pmHeight = 512; /* Care to update the documentation when changing these. */
 		rsb_flags_t marf = RSB_MARF_EPS;
 		/* may tell the user to supply a sparsersb matrix in case input is not 'sparse' */