rsb_err_trsb_coo_cleanup(rsb_coo_idx_t*nnzp,void*VA,rsb_coo_idx_t*IA,rsb_coo_idx_t*JA,rsb_nnz_idx_tnnzA,rsb_coo_idx_tnrA,rsb_coo_idx_tncA,rsb_type_ttypecode,rsb_flags_tflagsA)
Compacts the given COO input arrays representing a sparse matrix $A$. Will either sum together duplicates
or use the last one, depending on whether RSB_FLAG_DUPLICATES_KEEP_LAST or RSB_FLAG_DUPLICATES_SUM is
present in flagsA.
It is important that the input is sorted and flagsA shall contain RSB_FLAG_SORTED_INPUT, otherwise the
algorithm's complexity will be quadratic.
Parametersnnzp Pointer to the number of nonzeroes after the cleanup.
VA,IA,JA Output numerical values (VA) array; output row (IA) and column (JA) indices arrays.
nnzA The number of nonzeroes in the input arrays representing matrix $A$.
nrA,ncA The number of rows and columns of the sparse matrix $A$.
typecode A valid type code for the given (numerical array) input pointer (see
matrix_type_symbols_section).
flagsA A valid combination of matrix storage flags. If unsure, use RSB_FLAG_NOFLAGS.
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Seealsorsb_time, rsb_coo_sortrsb_coo_sortWarning
This is an experimental librsb-1.3 function.
Note
By invoking with swapped IA and JA (and swapping nrA and ncA as well) one can obtain column major
order.
Examples:
rsb_err_t errval = RSB_ERR_NO_ERROR;
rsb_nnz_idx_t nnzA = 4;
const rsb_coo_idx_t nrA = 4;
const rsb_coo_idx_t ncA = 4;
rsb_coo_idx_t IA[] = { 1, 1, 1, 2 };
rsb_coo_idx_t JA[] = { 1, 1, 3, 2 };
RSB_DEFAULT_TYPE VA[] = { 1, 10, 13, 22 };
const rsb_type_t typecode = RSB_NUMERICAL_TYPE_DEFAULT;
rsb_flags_t flagsA = RSB_FLAG_DUPLICATES_SUM | RSB_FLAG_SORTED_INPUT;
// IA={1,1,1,2} JA={1,1,3,2} VA={1,10,13,22} nnzA=4 nrA=4 nca=4
if((errval = rsb_lib_init(RSB_NULL_INIT_OPTIONS))
!= RSB_ERR_NO_ERROR) goto err;
errval = rsb_coo_cleanup(&nnzA, VA, IA, JA,
nnzA, nrA, ncA, typecode, flagsA );
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_coo_cleanup!\n");
goto err;
}
// IA={1,1,2} JA={1,3,2} VA={11,13,22} nnzA=3 nrA=4 nca=4
rsb_err_t errval = RSB_ERR_NO_ERROR;
rsb_nnz_idx_t nnzA = 3;
const rsb_coo_idx_t nrA = 2;
const rsb_coo_idx_t ncA = 2;
rsb_coo_idx_t IA[] = { 1, 1, 1 };
rsb_coo_idx_t JA[] = { 2, 1, 1 };
RSB_DEFAULT_TYPE VA[] = { 1, 2, 3 };
const rsb_type_t typecode = RSB_NUMERICAL_TYPE_DEFAULT;
const rsb_flags_t flagsA = RSB_FLAG_DUPLICATES_SUM
| RSB_FLAG_SORTED_INPUT
| RSB_FLAG_FORTRAN_INDICES_INTERFACE;
// IA={1,1,1} JA={2,1,1} VA={1,2,3} nnzA=3 nrA=2 nca=2
errval =rsb_coo_sort(VA, IA, JA, nnzA, nrA, ncA, typecode, flagsA);
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_coo_cleanup!\n");
goto err;
}
// IA={1,1,1} JA={1,1,2} VA={2,3,1} nnzA=3 nrA=2 nca=2
errval = rsb_coo_cleanup(&nnzA, VA, IA, JA, nnzA,
nrA, ncA, typecode, flagsA );
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_coo_cleanup!\n");
goto err;
}
// IA={1,1} JA={1,2} VA={5,1} nnzA=2 nrA=2 nca=2
rsb_err_trsb_coo_sort(void*VA,rsb_coo_idx_t*IA,rsb_coo_idx_t*JA,rsb_nnz_idx_tnnzA,rsb_coo_idx_tnrA,rsb_coo_idx_tncA,rsb_type_ttypecode,rsb_flags_tflagsA)
Sorts row-major the given COO input arrays representing a sparse matrix $A$.
ParametersVA,IA,JA Output numerical values (VA) array; output row (IA) and column (JA) indices arrays.
nnzA The number of nonzeroes in the input arrays representing matrix $A$.
nrA,ncA The number of rows and columns of the sparse matrix $A$. If any of nrA or ncA is zero, no
sort occurs.
typecode A valid type code for the given (numerical array) input pointer (see
matrix_type_symbols_section).
flagsA A valid combination of matrix storage flags. If unsure, use RSB_FLAG_NOFLAGS.
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Seealsorsb_time, rsb_coo_sortNote
By invoking with swapped IA and JA (and swapping nrA and ncA as well) one can obtain column major
order.
rsb_err_trsb_file_mtx_get_dims(constchar*filename,rsb_coo_idx_t*nrp,rsb_coo_idx_t*ncp,rsb_coo_idx_t*nzp,rsb_flags_t*flagsp)
Reads structural information (dimensions, structural flags) for a matrix file into user specified (and
optionally NULL) variables.
Parametersfilename The specified matrix file name (cannot be NULL).
nrp,ncp Output pointers to rows and columns count variables (can be NULL).
nzp Output pointer to the nonzeroes count variable (can be NULL).
flagsp Output pointer to the detected structural flags variable. Will be a combination of
RSB_FLAG_LOWER, RSB_FLAG_UPPER, RSB_FLAG_SYMMETRIC, RSB_FLAG_HERMITIAN.
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error. If read dimensions are illegal (see
rsb_coo_idx_t,rsb_nnz_idx_t), RSB_ERR_LIMITS will be returned.
Example getting dimensions of a sparse matrix stored in a Matrix Market file:
if(RSB_ERR_NO_ERROR!=(errval =
rsb_file_mtx_get_dims("pd.mtx",&nrA,&ncA,&nnzA,NULL)))
{
if(errval != RSB_ERR_UNSUPPORTED_FEATURE)
goto err; /* may have not configured what needed */
}
Note
The only sparse matrix file format currently supported is Matrix Market. E.g.:
%%MatrixMarket matrix coordinate real symmetric
%
% A Hilbert Matrix of order 3, so with 3 rows, 3 columns, and 6 nonzeroes.
%
3 3 6
1 1 1.0
2 1 0.5
2 2 0.33
3 1 0.33
3 2 0.25
3 3 0.2
In the above example header on the first line, you can specify either real or complex or pattern for
the numerical type. Either general, symmetric, hermitian can be specified for the structure. In case
of pattern matrices, only coordinate indices will be loaded (saving pattern matrices is not yet
supported); in case of real matrices, also one coefficient value will be saved/loaded; in the case of
complex matrices, both the real and imaginary parts will be saved/loaded in addition to the indices.
Upper/lower flags will not be reported; hermitiannes do.
Seealsorsb_mtx_get_coo, rsb_mtx_get_csr, rsb_mtx_get_rows_sparse, rsb_mtx_get_coo_block, rsb_mtx_get_prec,
rsb_mtx_get_nrm, rsb_mtx_get_vec, rsb_file_mtx_get_dims, rsb_mtx_get_valsstructrsb_mtx_t*rsb_file_mtx_load(constrsb_char_t*filename,rsb_flags_tflagsA,rsb_type_ttypecode,rsb_err_t*errvalp)
Loads a sparse matrix from the specified matrix file, assembling it in the format specified by flags,
using the numerical type representation as specified by the user. Extra input errors or warnings
verbosity can be enabled via the ./configure --enable-internals-error-verbosity option.
Parametersfilename The specified matrix file name (cannot be NULL).
flagsA A valid combination of matrix storage flags.
typecode A valid type code for the given (numerical array) input pointer (see
matrix_type_symbols_section).
errvalp An optional (can be NULL) pointer to rsb_err_t where the error status will be written to.
Returns
On success, a valid pointer (struct rsb_mtx_t*) to the newly allocated matrix structure; on error,
NULL.
Note
The only sparse matrix file format currently supported is Matrix Market. E.g.:
%%MatrixMarket matrix coordinate real symmetric
%
% A Hilbert Matrix of order 3, so with 3 rows, 3 columns, and 6 nonzeroes.
%
3 3 6
1 1 1.0
2 1 0.5
2 2 0.33
3 1 0.33
3 2 0.25
3 3 0.2
In the above example header on the first line, you can specify either real or complex or pattern for
the numerical type. Either general, symmetric, hermitian can be specified for the structure. In case
of pattern matrices, only coordinate indices will be loaded (saving pattern matrices is not yet
supported); in case of real matrices, also one coefficient value will be saved/loaded; in the case of
complex matrices, both the real and imaginary parts will be saved/loaded in addition to the indices.
Example loading a matrix from a Matrix Market file:
mtxAp = rsb_file_mtx_load("pd.mtx",
RSB_FLAG_NOFLAGS,typecode,NULL);
if(!mtxAp)
{
return EXIT_FAILURE;
}
Seealsorsb_mtx_get_info, rsb_mtx_get_info_str, rsb_file_mtx_save, rsb_file_vec_load, rsb_file_mtx_loadrsb_err_trsb_file_mtx_rndr(void*pmp,constchar*filename,rsb_coo_idx_tpmlWidth,rsb_coo_idx_tpmWidth,rsb_coo_idx_tpmHeight,rsb_marf_trflags)
Renders as pixel map the matrix contained in a matrix file.
Parameterspmp Pixel map array pointer.
filename The specified matrix file name (cannot be NULL).
pmlWidth stride between lines (in pixels; no less than pmWidth).
pmWidth Pixel map width (in pixels or points).
pmHeight Pixel map height (in pixels or points).
rflags The color mode; only RSB_MARF_RGB is supported for now (1 byte per channel, 3 channels ---
red, green, blue): this requires array pmp to be at least (3*pmlWidth*pmHeight) bytes large.
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Note
At the time being, pmlWidth is required to be equal to pmWidth.
Example rendering a matrix from a Matrix Market file to a pixelmap in memory:
/* matrices can be rendered from file to a pixelmap as well */
{
unsigned char pixmap[3*2*2];
if(RSB_ERR_NO_ERROR!=(errval =
rsb_file_mtx_rndr(pixmap,"pd.mtx",2,2,2,RSB_MARF_RGB)))
goto err;
}
Seealsorsb_mtx_rndr, rsb_file_mtx_rndrrsb_err_trsb_file_mtx_save(conststructrsb_mtx_t*mtxAp,constrsb_char_t*filename)
Saves the given matrix to the specified matrix file.
ParametersmtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
filename The specified output file name (if NULL or '' (the empty string), will write to standard
output).
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Warning
Some structural info contained in the matrix structural flags may be lost in the output data.
Note
The only sparse matrix file format currently supported is Matrix Market. E.g.:
%%MatrixMarket matrix coordinate real symmetric
%
% A Hilbert Matrix of order 3, so with 3 rows, 3 columns, and 6 nonzeroes.
%
3 3 6
1 1 1.0
2 1 0.5
2 2 0.33
3 1 0.33
3 2 0.25
3 3 0.2
In the above example header on the first line, you can specify either real or complex or pattern for
the numerical type. Either general, symmetric, hermitian can be specified for the structure. In case
of pattern matrices, only coordinate indices will be loaded (saving pattern matrices is not yet
supported); in case of real matrices, also one coefficient value will be saved/loaded; in the case of
complex matrices, both the real and imaginary parts will be saved/loaded in addition to the indices.
Example, printing a matrix to standard output:
if(RSB_ERR_NO_ERROR!=(errval = rsb_file_mtx_save(mtxAp,NULL)))
{
if(errval != RSB_ERR_UNSUPPORTED_FEATURE)
goto err;
}
Seealsorsb_mtx_get_info, rsb_mtx_get_info_str, rsb_file_mtx_save, rsb_file_vec_load, rsb_file_mtx_loadrsb_err_trsb_file_vec_load(constrsb_char_t*filename,rsb_type_ttypecode,void*Yp,rsb_coo_idx_t*yvlp)
Loads a dense vector from the specified file, using the numerical type representation as specified by the
user. This function is intended to be called in two steps: first with Yp=NULL, in order to write the
vector length to *yvlp ; then, with yvlp=NULL, to get Yp written.
Parametersfilename The specified vector file name (cannot be NULL).
typecode A valid type code for the given (numerical array) input pointer (see
matrix_type_symbols_section).
Yp The input array vector.
yvlp An optional pointer (can be NULL). If supplied, vector length will be written here, and no
vector will be read.
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Example loading vector matrix from file
/* also vectors can be loaded */
if(RSB_ERR_NO_ERROR!=(errval =
rsb_file_vec_load("vf.mtx",typecode,NULL,&vl )))
goto err;
/* we expect vf.mtx to be 6 rows long */
if( vl != 6 )
{
goto err;
}
if(RSB_ERR_NO_ERROR!=(errval =
rsb_file_vec_load("vf.mtx",typecode,XV, NULL )))
goto err;
Note
The only dense vector file format currently supported is Matrix Market. E.g.:
%%MatrixMarket matrix array complex general
% Test MatrixMarket file with a complex vector.
% Note: a blank line like the following is OK.
6 1
11.000000000000000E+000 12.000000000000000E+000
21.000000000000000E+000 22.000000000000000E+000
31.000000000000000E+000 32.000000000000000E+000
41.000000000000000E+000 42.000000000000000E+000
51.000000000000000E+000 52.000000000000000E+000
61.000000000000000E+000 62.000000000000000E+000
In the above example header on the first line, you can specify either real or complex or pattern for
the numerical type.
Seealsorsb_mtx_get_info, rsb_mtx_get_info_str, rsb_file_mtx_save, rsb_file_vec_load, rsb_file_mtx_loadrsb_err_trsb_file_vec_save(constrsb_char_t*filename,rsb_type_ttypecode,constvoid*Yp,rsb_coo_idx_tyvl)
Saves a dense vector to the specified file, using the numerical type representation as specified by the
user. This function assumes Yp!=NULL and yvl>0.
Parametersfilename The specified vector file name (cannot be NULL).
typecode A valid type code for the given (numerical array) input pointer (see
matrix_type_symbols_section).
Yp The output array vector.
yvl Output vector length.
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Note
The only dense vector file format currently supported is Matrix Market. E.g.:
%%MatrixMarket matrix array complex general
% Test MatrixMarket file with a complex vector.
% Note: a blank line like the following is OK.
6 1
11.000000000000000E+000 12.000000000000000E+000
21.000000000000000E+000 22.000000000000000E+000
31.000000000000000E+000 32.000000000000000E+000
41.000000000000000E+000 42.000000000000000E+000
51.000000000000000E+000 52.000000000000000E+000
61.000000000000000E+000 62.000000000000000E+000
In the above example header on the first line, you can specify either real or complex or pattern for
the numerical type.
Example printing to standard output:
errval = rsb_file_vec_save(NULL, typecode, X, nrA);
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error printing vector!\n");
goto err;
}
Seealsorsb_mtx_get_info, rsb_mtx_get_info_str, rsb_file_mtx_save, rsb_file_vec_load, rsb_file_mtx_loadrsb_err_trsb_lib_exit(structrsb_initopts*iop)
Finalize librsb.
rsb_lib_exit should be called after having freed all matrices.
If not all of the data structures were properly deallocated before, this function may still attempt
finalizing the library and return the RSB_ERR_MEMORY_LEAK error code (this depends on the --enable-
allocator-wrapper configure time option). Any allocated memory will be lost (librsb does not keep track
of allocated matrices).
Internal library state will be cleared. After this call, it is legal to initialize the library again, by
calling rsb_lib_init().
On an error, the library state may be inconsistent, so it is advisable to either terminate program
execution (rather than forcing a new initialization with rsb_lib_init()).
Parameter iop is reserved for future use; for now it is safe to pass RSB_NULL_EXIT_OPTIONS.
It should be safe to call rsb_lib_exit() more than once.
Parametersiop A pointer to a rsb_initopts structure with library options. It may be NULL (or better,
RSB_NULL_INIT_OPTIONS/RSB_NULL_EXIT_OPTIONS) for specifying default options.
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
An example snippet declaring an error variable accumulator at program's beginning:
rsb_err_t errval = RSB_ERR_NO_ERROR;
and finalizing the library at program's end:
if((errval = rsb_lib_exit(RSB_NULL_EXIT_OPTIONS))
!= RSB_ERR_NO_ERROR)
{
printf("Error finalizing the library!\n");
goto err;
}
Seealsorsb_lib_init, rsb_lib_set_opt_str, rsb_lib_reinit, rsb_lib_exit, rsb_lib_get_opt, rsb_lib_set_opt, or
(deprecated) macrosRSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET,
RSB_REINIT_SINGLE_VALUE, RSB_REINIT_SINGLE_VALUE_C_IOP..
rsb_err_trsb_lib_get_opt(enumrsb_opt_tiof,void*iop)
Gets value of a library option.
A value specified by the request flag iof will be fetched from the library internal state and *iop will
be updated accordingly.
Parametersiof library options flags. See rsb_opt_t for a list of valid options.
iop library options value output pointer (pointed location will be updated).
SeealsoRSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET, RSB_REINIT_SINGLE_VALUE,
RSB_REINIT_SINGLE_VALUE_C_IOPrsb_lib_init, rsb_lib_set_opt_str, rsb_lib_reinit, rsb_lib_exit, rsb_lib_get_opt, rsb_lib_set_opt, or
(deprecated) macrosRSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET,
RSB_REINIT_SINGLE_VALUE, RSB_REINIT_SINGLE_VALUE_C_IOP..
rsb_err_trsb_lib_init(structrsb_initopts*iop)
This is the library initialization function.
It must be called only once before using any other library function.
It is allowed to call it again after rsb_lib_exit().
To fine-tune the library behaviour, one may specify a number of options via the iop parameter.
Options may be specified also after rsb_lib_init() by calling rsb_lib_reinit().
One may call RSB_REINIT_SINGLE_VALUE_GET with flag RSB_IO_WANT_IS_INITIALIZED_MARKER to verify whether
the library has been initialized or not.
If the RSB_NUM_THREADS environment variable is set, rsb_lib_init() uses it and sets the number of active
threads, thus overriding what detected by the OpenMP runtime (e.g. OMP_NUM_THREADS).
Parametersiop A pointer to a rsb_initopts structure with library options. It may be NULL (or better,
RSB_NULL_INIT_OPTIONS/RSB_NULL_EXIT_OPTIONS) for specifying default options.
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
An example snippet declaring an error variable accumulator at program's beginning:
rsb_err_t errval = RSB_ERR_NO_ERROR;
and initializing the library soon thereafter:
if((errval = rsb_lib_init(RSB_NULL_INIT_OPTIONS)) !=
RSB_ERR_NO_ERROR)
{
printf("Error initializing the library!\n");
goto err;
}
Seealsorsb_lib_init, rsb_lib_set_opt_str, rsb_lib_reinit, rsb_lib_exit, rsb_lib_get_opt, rsb_lib_set_opt, or
(deprecated) macrosRSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET,
RSB_REINIT_SINGLE_VALUE, RSB_REINIT_SINGLE_VALUE_C_IOP..
rsb_err_trsb_lib_reinit(structrsb_initopts*iop)
Changes the library operation options which were set at initialization time either by a user or as
defaults.
Not all options may be supported, depending on build time library settings.
If an unsupported option was specified, an appropriate error (e.g.: RSB_ERR_UNSUPPORTED_OPERATION) will
be returned.
On the first error, option processing is interrupted and the remaining options (if any) are not
processed.
Program execution may continue safely even if an error code is returned (that is, library status should
be consistent).
Parametersiop A pointer to a rsb_initopts structure with library options. It may be NULL (or better,
RSB_NULL_INIT_OPTIONS/RSB_NULL_EXIT_OPTIONS) for specifying default options.
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
rsb_err_t errval = RSB_ERR_NO_ERROR;
struct rsb_initopts io;
rsb_int_t ione={1};
enum rsb_opt_t keys[]={RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE};
void*values[]={&ione};
io.action=RSB_IO_SPECIFIER_SET;
io.keys=keys;
io.values=values;
io.n_pairs=1;
if((errval = rsb_lib_init(RSB_NULL_INIT_OPTIONS))
!= RSB_ERR_NO_ERROR) goto err;
// won't print anything
if((errval = rsb_lib_reinit(&io))
!= RSB_ERR_NO_ERROR) goto err;
// may print verbose message (depends on configure)
if((errval = rsb_lib_reinit(NULL))
!= RSB_ERR_NO_ERROR) goto err;
// may print verbose message (depends on configure)
if((errval = rsb_lib_set_opt_str(
"RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE","0"))
!= RSB_ERR_NO_ERROR) goto err;
// won't print anything anymore
if((errval = rsb_lib_exit(&io))
!= RSB_ERR_NO_ERROR) goto err;
Seealsorsb_lib_init, rsb_lib_set_opt_str, rsb_lib_reinit, rsb_lib_exit, rsb_lib_get_opt, rsb_lib_set_opt, or
(deprecated) macrosRSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET,
RSB_REINIT_SINGLE_VALUE, RSB_REINIT_SINGLE_VALUE_C_IOP..
rsb_err_trsb_lib_set_opt(enumrsb_opt_tiof,constvoid*iop)
Sets value of a library option.
A value specified by the request flag iof will be fetched from *iop and will be used to update the
selected option in the library internal state.
Parametersiof library options flags. See rsb_opt_t for a list of valid options.
iop library options value output pointer (pointed location will be updated).
Example snip:
rsb_int_t evi=1;
/* Setting a single optional library parameter. */
errval = rsb_lib_set_opt(
RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE, &evi);
if(errval != RSB_ERR_NO_ERROR)
{
/*! [Copy error message to string] */
char errbuf[256];
rsb_strerror_r(errval,&errbuf[0],sizeof(errbuf));
printf("Failed setting the"
" RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE"
" library option (reason string:\n%s).\n",errbuf);
/*! [Copy error message to string] */
if(errval&RSB_ERRS_UNSUPPORTED_FEATURES)
{
printf("This error may be safely ignored.\n");
}
else
{
printf("Some unexpected error occurred!\n");
goto err;
}
}
else
{
printf("Setting back the "
"RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE"
" library option.\n");
evi = 0;
errval = rsb_lib_set_opt(RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE,
&evi);
errval = RSB_ERR_NO_ERROR;
}
SeealsoRSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET, RSB_REINIT_SINGLE_VALUE,
RSB_REINIT_SINGLE_VALUE_C_IOPrsb_lib_init, rsb_lib_set_opt_str, rsb_lib_reinit, rsb_lib_exit, rsb_lib_get_opt, rsb_lib_set_opt, or
(deprecated) macrosRSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET,
RSB_REINIT_SINGLE_VALUE, RSB_REINIT_SINGLE_VALUE_C_IOP..
rsb_err_trsb_lib_set_opt_str(constrsb_char_t*opnp,constrsb_char_t*opvp)
Specifies individual library options in order to fine-tune the library behaviour.
Both the option name and the value shall be expressed as strings, identical to their preprocessor
identifiers (see rsb_opt_t ). The opnp string will be translated internally to the corresponding request
flag values, and the passed value will be parsed out of the opvp string.
Parametersopnp A pointer to a library option input name string (may not be NULL).
opvp A pointer to a library option input value string (may not be NULL).
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
rsb_err_t errval = RSB_ERR_NO_ERROR;
struct rsb_initopts io;
rsb_int_t ione={1};
enum rsb_opt_t keys[]={RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE};
void*values[]={&ione};
io.action=RSB_IO_SPECIFIER_SET;
io.keys=keys;
io.values=values;
io.n_pairs=1;
if((errval = rsb_lib_init(RSB_NULL_INIT_OPTIONS))
!= RSB_ERR_NO_ERROR) goto err;
// won't print anything
if((errval = rsb_lib_reinit(&io))
!= RSB_ERR_NO_ERROR) goto err;
// may print verbose message (depends on configure)
if((errval = rsb_lib_reinit(NULL))
!= RSB_ERR_NO_ERROR) goto err;
// may print verbose message (depends on configure)
if((errval = rsb_lib_set_opt_str(
"RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE","0"))
!= RSB_ERR_NO_ERROR) goto err;
// won't print anything anymore
if((errval = rsb_lib_exit(&io))
!= RSB_ERR_NO_ERROR) goto err;
Seealsorsb_lib_init, rsb_lib_set_opt_str, rsb_lib_reinit, rsb_lib_exit, rsb_lib_get_opt, rsb_lib_set_opt, or
(deprecated) macrosRSB_REINIT_SINGLE_VALUE_GET, RSB_REINIT_SINGLE_VALUE_SET,
RSB_REINIT_SINGLE_VALUE, RSB_REINIT_SINGLE_VALUE_C_IOP..
rsb_err_trsb_mtx_add_to_dense(constvoid*alphap,conststructrsb_mtx_t*mtxAp,rsb_nnz_idx_tldB,rsb_nnz_idx_tnrB,rsb_nnz_idx_tncB,rsb_bool_trowmajorB,void*Bp)
Dense matrix B is updated by adding scaled sparse matrix ${A}$ to it: $B <- B + alpha {A} $
Parametersalphap Optional pointer (if NULL, will default to 1) to a numerical value (of the same type as
matrix).
mtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
ldB Leading dimension of Bp array.
nrB,ncB The number of rows and columns for the dense matrix $B$.
rowmajorBRSB_BOOL_TRUE if the dense matrix $B$ is considered stored as row major, or RSB_BOOL_FALSE
if as column major.
Bp Array representing the dense matrix $B$.
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Example snip:
const rsb_nnz_idx_t ldB = 4, nrB = 3, ncB = 3;
const rsb_bool_t rowmajorB = RSB_BOOL_TRUE;
RSB_DEFAULT_TYPE Bp[ /*ldB*nrB*/ ] = {
-1, -1, -1, -1,
-1, -1, -1, -1,
-1, -1, -1, -1
};
RSB_DEFAULT_TYPE *alphap = NULL;
errval = rsb_mtx_add_to_dense(alphap, mtxAp, ldB,
nrB, ncB, rowmajorB, Bp);
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_mtx_add_to_dense!\n");
goto err;
}
Note
Please note that it suffices to 'transpose' Bp's description parameters to get $A$ transposed summed
in.
Symmetry is currently not expanded.
Threaded, for large enough matrices.
Seealsorsb_spmsp_to_dense, rsb_sppsp, rsb_spmsp, rsb_mtx_add_to_densestructrsb_mtx_t*rsb_mtx_alloc_from_coo_begin(rsb_nnz_idx_tnnzA,rsb_type_ttypecode,rsb_coo_idx_tnrA,rsb_coo_idx_tncA,rsb_flags_tflagsA,rsb_err_t*errvalp)
Creates an empty matrix structure in assembly state. The user then populates it using rsb_mtx_set_vals()
repeatedly; then assembles it with rsb_mtx_alloc_from_coo_end().
ParametersnnzA A rough estimate of the number of nonzeroes matrix $A$ will host (used for optimizing arrays
allocation). If you do not know yet, you can specify zero.
typecode A valid type code for the given (numerical array) input pointer (see
matrix_type_symbols_section).
nrA,ncA The number of rows and columns of the sparse matrix $A$.
flagsA A valid combination of index conversion and matrix storage flags and other meaningful flags.
The encouraged base choice here is RSB_FLAG_DEFAULT_RSB_MATRIX_FLAGS. If Fortran (1 based) indices
are being used for the IA, JA arrays, then the RSB_FLAG_FORTRAN_INDICES_INTERFACE flag should be
added. If symmetric storage is desired, then RSB_FLAG_SYMMETRIC (or RSB_FLAG_HERMITIAN, for Hermitian
matrices) is necessary, in combination with either RSB_FLAG_LOWER or RSB_FLAG_UPPER. If you intend to
use this matrix for triangular solution (e.g.: rsb_spsv()/rsb_spsm()), it needs to be triangular and
specified with either RSB_FLAG_LOWER_TRIANGULAR or RSB_FLAG_UPPER_TRIANGULAR, and not have
RSB_FLAG_LOWER_SYMMETRIC or RSB_FLAG_LOWER_HERMITIAN. Nonzeroes non complying with the specified
flags will be ignored. If a matrix is both RSB_FLAG_LOWER_TRIANGULAR and RSB_FLAG_UPPER_TRIANGULAR at
the same time, then it's diagonal, for which shorthand: RSB_FLAG_DIAGONAL can be used. If
RSB_FLAG_UNIT_DIAG_IMPLICIT is present, diagonal entries will be not represented but assumed to be
unitary. If RSB_FLAG_DUPLICATES_SUM is present, duplicate entries will be summed together. If
RSB_FLAG_DISCARD_ZEROS is present, zeroes will be discarded.
errvalp An optional (can be NULL) pointer to rsb_err_t where the error status will be written to.
Returns
Pointer to a rsb_mtx_t matrix structure in assembly state, or NULL (on error).
Warning
This function has not been thoroughly tested.
Seealsorsb_mtx_alloc_from_coo_const, rsb_mtx_alloc_from_coo_inplace, rsb_mtx_free, rsb_mtx_clone,
rsb_mtx_alloc_from_csr_const, rsb_mtx_alloc_from_csc_const, rsb_mtx_alloc_from_csr_inplace,
rsb_mtx_switch_to_csr, rsb_mtx_alloc_from_coo_begin, rsb_mtx_alloc_from_coo_endstructrsb_mtx_t*rsb_mtx_alloc_from_coo_const(constvoid*VA,constrsb_coo_idx_t*IA,constrsb_coo_idx_t*JA,rsb_nnz_idx_tnnzA,rsb_type_ttypecode,rsb_coo_idx_tnrA,rsb_coo_idx_tncA,rsb_blk_idx_tbrA,rsb_blk_idx_tbcA,rsb_flags_tflagsA,rsb_err_t*errvalp)
Given as input COO arrays VA,IA,JA, allocates and assembles an RSB matrix using separate arrays.
ParametersVA,IA,JA Input numerical values (VA) array; row (IA) and column (JA) input indices arrays.
nnzA The number of nonzeroes in the input arrays representing matrix $A$.
typecode A valid type code for the given (numerical array) input pointer (see
matrix_type_symbols_section).
nrA,ncA The number of rows and columns of the sparse matrix $A$. If any of nrA or ncA is zero, it
will be detected on the basis of the IA and JA arrays and flagsA.
brA,bcA Blocking parameters: brA should be set to 1 or RSB_DEFAULT_ROW_BLOCKING (currently unused,
reserved for future use); bcA should be set to 1 or RSB_DEFAULT_ROW_BLOCKING (currently unused,
reserved for future use).
flagsA A valid combination of index conversion and matrix storage flags and other meaningful flags.
The encouraged base choice here is RSB_FLAG_DEFAULT_RSB_MATRIX_FLAGS. If Fortran (1 based) indices
are being used for the IA, JA arrays, then the RSB_FLAG_FORTRAN_INDICES_INTERFACE flag should be
added. If symmetric storage is desired, then RSB_FLAG_SYMMETRIC (or RSB_FLAG_HERMITIAN, for Hermitian
matrices) is necessary, in combination with either RSB_FLAG_LOWER or RSB_FLAG_UPPER. If you intend to
use this matrix for triangular solution (e.g.: rsb_spsv()/rsb_spsm()), it needs to be triangular and
specified with either RSB_FLAG_LOWER_TRIANGULAR or RSB_FLAG_UPPER_TRIANGULAR, and not have
RSB_FLAG_LOWER_SYMMETRIC or RSB_FLAG_LOWER_HERMITIAN. Nonzeroes non complying with the specified
flags will be ignored. If a matrix is both RSB_FLAG_LOWER_TRIANGULAR and RSB_FLAG_UPPER_TRIANGULAR at
the same time, then it's diagonal, for which shorthand: RSB_FLAG_DIAGONAL can be used. If
RSB_FLAG_UNIT_DIAG_IMPLICIT is present, diagonal entries will be not represented but assumed to be
unitary. If RSB_FLAG_DUPLICATES_SUM is present, duplicate entries will be summed together. If
RSB_FLAG_DISCARD_ZEROS is present, zeroes will be discarded.
errvalp An optional (can be NULL) pointer to rsb_err_t where the error status will be written to.
Returns
On success, a valid pointer (struct rsb_mtx_t*) to the newly allocated matrix structure; on error,
NULL.
Example snip:
mtxAp = rsb_mtx_alloc_from_coo_const(
VA,IA,JA,nnzA,typecode,nrA,ncA,
brA,bcA,RSB_FLAG_NOFLAGS,NULL);
if(!mtxAp)
{
return EXIT_FAILURE;
}
And another, with duplicate sum flags:
mtxAp = rsb_mtx_alloc_from_coo_const(
VA,IA,JA,nnzA,typecode,nrA,ncA,brA,bcA,
RSB_FLAG_NOFLAGS /* default format will be chosen */
|RSB_FLAG_DUPLICATES_SUM/* duplicates will be summed */
,&errval);
if((!mtxAp) || (errval != RSB_ERR_NO_ERROR))
{
printf("Error while allocating the matrix!\n");
goto err;
}
And yet another, allocating a triangular matrix:
mtxAp = rsb_mtx_alloc_from_coo_const(
VA,IA,JA,nnzA,typecode,nrA,ncA,brA,bcA,
RSB_FLAG_DEFAULT_RSB_MATRIX_FLAGS /* force rsb */
| RSB_FLAG_DUPLICATES_SUM/* sum dups */
| RSB_FLAG_UNIT_DIAG_IMPLICIT/* ask diagonal implicit */
| RSB_FLAG_TRIANGULAR /* need triangle for spsv */
, &errval);
if((!mtxAp) || (errval != RSB_ERR_NO_ERROR))
{
printf("Error while allocating the matrix!\n");
goto err;
}
printf("Correctly allocated a matrix with %ld nonzeroes.\n",
(long int)nnzA);
Seealsorsb_mtx_alloc_from_coo_const, rsb_mtx_alloc_from_coo_inplace, rsb_mtx_free, rsb_mtx_clone,
rsb_mtx_alloc_from_csr_const, rsb_mtx_alloc_from_csc_const, rsb_mtx_alloc_from_csr_inplace,
rsb_mtx_switch_to_csr, rsb_mtx_alloc_from_coo_begin, rsb_mtx_alloc_from_coo_endrsb_err_trsb_mtx_alloc_from_coo_end(structrsb_mtx_t**mtxApp)
Assembles RSB arrays for a matrix in build state created with rsb_mtx_alloc_from_coo_begin() and
populated with rsb_mtx_set_vals().
After assembly, any operation on the matrix is allowed.
ParametersmtxApp rsb_mtx_t pointer to an unassembled matrix address.
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Warning
This function has not been thoroughly tested.
Note
Note that the memory location of the matrix will be changed by this call, and the (old) *mtxApp
address value will be not valid anymore.
Seealsorsb_mtx_alloc_from_coo_const, rsb_mtx_alloc_from_coo_inplace, rsb_mtx_free, rsb_mtx_clone,
rsb_mtx_alloc_from_csr_const, rsb_mtx_alloc_from_csc_const, rsb_mtx_alloc_from_csr_inplace,
rsb_mtx_switch_to_csr, rsb_mtx_alloc_from_coo_begin, rsb_mtx_alloc_from_coo_endstructrsb_mtx_t*rsb_mtx_alloc_from_coo_inplace(void*VA,rsb_coo_idx_t*IA,rsb_coo_idx_t*JA,rsb_nnz_idx_tnnzA,rsb_type_ttypecode,rsb_coo_idx_tnrA,rsb_coo_idx_tncA,rsb_blk_idx_tbrA,rsb_blk_idx_tbcA,rsb_flags_tflagsA,rsb_err_t*errvalp)
Given as input COO arrays VA,IA,JA, allocates and assembles an RSB matrix reusing input arrays.
Assumes all three VA,IA,JA arrays are at least max(nnzA,nrA+1,ncA+1) sized. The user is expected NOT to
use these arrays until the matrix has been destroyed with rsb_mtx_free(). Then, it is possible to use
these arrays again.
ParametersVA,IA,JA Input/output numerical values array (VA); row (IA) and column (JA) indices arrays.
nnzA The number of nonzeroes in the input arrays representing matrix $A$.
typecode A valid type code for the given (numerical array) input pointer (see
matrix_type_symbols_section).
nrA,ncA The number of rows and columns of the sparse matrix $A$.
brA,bcA Blocking parameters: brA should be set to 1 or RSB_DEFAULT_ROW_BLOCKING (currently unused,
reserved for future use); bcA should be set to 1 or RSB_DEFAULT_ROW_BLOCKING (currently unused,
reserved for future use).
flagsA A valid combination of index conversion and matrix storage flags and other meaningful flags.
The encouraged base choice here is RSB_FLAG_DEFAULT_RSB_MATRIX_FLAGS. If Fortran (1 based) indices
are being used for the IA, JA arrays, then the RSB_FLAG_FORTRAN_INDICES_INTERFACE flag should be
added. If symmetric storage is desired, then RSB_FLAG_SYMMETRIC (or RSB_FLAG_HERMITIAN, for Hermitian
matrices) is necessary, in combination with either RSB_FLAG_LOWER or RSB_FLAG_UPPER. If you intend to
use this matrix for triangular solution (e.g.: rsb_spsv()/rsb_spsm()), it needs to be triangular and
specified with either RSB_FLAG_LOWER_TRIANGULAR or RSB_FLAG_UPPER_TRIANGULAR, and not have
RSB_FLAG_LOWER_SYMMETRIC or RSB_FLAG_LOWER_HERMITIAN. Nonzeroes non complying with the specified
flags will be ignored. If a matrix is both RSB_FLAG_LOWER_TRIANGULAR and RSB_FLAG_UPPER_TRIANGULAR at
the same time, then it's diagonal, for which shorthand: RSB_FLAG_DIAGONAL can be used. If
RSB_FLAG_UNIT_DIAG_IMPLICIT is present, diagonal entries will be not represented but assumed to be
unitary. If RSB_FLAG_DUPLICATES_SUM is present, duplicate entries will be summed together. If
RSB_FLAG_DISCARD_ZEROS is present, zeroes will be discarded.
errvalp An optional (can be NULL) pointer to rsb_err_t where the error status will be written to.
Returns
On success, a valid pointer (struct rsb_mtx_t*) to the newly allocated matrix structure; on error,
NULL.
Seealsorsb_mtx_alloc_from_coo_const, rsb_mtx_alloc_from_coo_inplace, rsb_mtx_free, rsb_mtx_clone,
rsb_mtx_alloc_from_csr_const, rsb_mtx_alloc_from_csc_const, rsb_mtx_alloc_from_csr_inplace,
rsb_mtx_switch_to_csr, rsb_mtx_alloc_from_coo_begin, rsb_mtx_alloc_from_coo_endstructrsb_mtx_t*rsb_mtx_alloc_from_csc_const(constvoid*VA,constrsb_coo_idx_t*IA,constrsb_coo_idx_t*CP,rsb_nnz_idx_tnnzA,rsb_type_ttypecode,rsb_coo_idx_tnrA,rsb_coo_idx_tncA,rsb_blk_idx_tbrA,rsb_blk_idx_tbcA,rsb_flags_tflagsA,rsb_err_t*errvalp)
Given input read only CSC format arrays, allocates and assembles an RSB matrix (stored in separate
arrays).
ParametersVA,IA,CP Input numerical values (VA) array, input row indices (IA) and compressed column (CP) indices
arrays.
nnzA The number of nonzeroes in the input arrays representing matrix $A$.
typecode A valid type code for the given (numerical array) input pointer (see
matrix_type_symbols_section).
nrA,ncA The number of rows and columns of the sparse matrix $A$.
brA,bcA Blocking parameters: brA should be set to 1 or RSB_DEFAULT_ROW_BLOCKING (currently unused,
reserved for future use); bcA should be set to 1 or RSB_DEFAULT_ROW_BLOCKING (currently unused,
reserved for future use).
flagsA A valid combination of index conversion and matrix storage flags and other meaningful flags.
The encouraged base choice here is RSB_FLAG_DEFAULT_RSB_MATRIX_FLAGS. If Fortran (1 based) indices
are being used for the IA, JA arrays, then the RSB_FLAG_FORTRAN_INDICES_INTERFACE flag should be
added. If symmetric storage is desired, then RSB_FLAG_SYMMETRIC (or RSB_FLAG_HERMITIAN, for Hermitian
matrices) is necessary, in combination with either RSB_FLAG_LOWER or RSB_FLAG_UPPER. If you intend to
use this matrix for triangular solution (e.g.: rsb_spsv()/rsb_spsm()), it needs to be triangular and
specified with either RSB_FLAG_LOWER_TRIANGULAR or RSB_FLAG_UPPER_TRIANGULAR, and not have
RSB_FLAG_LOWER_SYMMETRIC or RSB_FLAG_LOWER_HERMITIAN. Nonzeroes non complying with the specified
flags will be ignored. If a matrix is both RSB_FLAG_LOWER_TRIANGULAR and RSB_FLAG_UPPER_TRIANGULAR at
the same time, then it's diagonal, for which shorthand: RSB_FLAG_DIAGONAL can be used. If
RSB_FLAG_UNIT_DIAG_IMPLICIT is present, diagonal entries will be not represented but assumed to be
unitary. If RSB_FLAG_DUPLICATES_SUM is present, duplicate entries will be summed together. If
RSB_FLAG_DISCARD_ZEROS is present, zeroes will be discarded.
errvalp An optional (can be NULL) pointer to rsb_err_t where the error status will be written to.
Returns
On success, a valid pointer (struct rsb_mtx_t*) to the newly allocated matrix structure; on error,
NULL.
Seealsorsb_mtx_alloc_from_coo_const, rsb_mtx_alloc_from_coo_inplace, rsb_mtx_free, rsb_mtx_clone,
rsb_mtx_alloc_from_csr_const, rsb_mtx_alloc_from_csc_const, rsb_mtx_alloc_from_csr_inplace,
rsb_mtx_switch_to_csr, rsb_mtx_alloc_from_coo_begin, rsb_mtx_alloc_from_coo_end
Example:
rsb_err_t errval = RSB_ERR_NO_ERROR;
struct rsb_mtx_t *mtxAp = NULL;
const rsb_blk_idx_t brA = RSB_DEFAULT_BLOCKING,
bcA = RSB_DEFAULT_BLOCKING;
const rsb_nnz_idx_t nnzA = 4;
const rsb_coo_idx_t nrA = 3;
const rsb_coo_idx_t ncA = 3;
const rsb_coo_idx_t IA[] = { 0, 2, 1, 2 };
const rsb_coo_idx_t CP[] = { 0, 2, 3, 4 };
const RSB_DEFAULT_TYPE VA[] = { 11, 31, 22, 33 };
const rsb_type_t typecode = RSB_NUMERICAL_TYPE_DEFAULT;
if(rsb_lib_init(RSB_NULL_INIT_OPTIONS)!=RSB_ERR_NO_ERROR)
{
return EXIT_FAILURE;
}
mtxAp = rsb_mtx_alloc_from_csc_const(
VA,IA,CP,nnzA,typecode,nrA,ncA,
brA,bcA,RSB_FLAG_NOFLAGS,NULL);
if(!mtxAp)
{
return EXIT_FAILURE;
}
rsb_file_mtx_save(mtxAp, NULL);
structrsb_mtx_t*rsb_mtx_alloc_from_csr_const(constvoid*VA,constrsb_coo_idx_t*RP,constrsb_coo_idx_t*JA,rsb_nnz_idx_tnnzA,rsb_type_ttypecode,rsb_coo_idx_tnrA,rsb_coo_idx_tncA,rsb_blk_idx_tbrA,rsb_blk_idx_tbcA,rsb_flags_tflagsA,rsb_err_t*errvalp)
Given input read only CSR format arrays, allocates and assembles an RSB matrix (stored in separate
arrays).
ParametersVA,RP,JA Input numerical values (VA) array; compressed rows (RP) and column (JA) input indices
arrays.
nnzA The number of nonzeroes in the input arrays representing matrix $A$.
typecode A valid type code for the given (numerical array) input pointer (see
matrix_type_symbols_section).
nrA,ncA The number of rows and columns of the sparse matrix $A$.
brA,bcA Blocking parameters: brA should be set to 1 or RSB_DEFAULT_ROW_BLOCKING (currently unused,
reserved for future use); bcA should be set to 1 or RSB_DEFAULT_ROW_BLOCKING (currently unused,
reserved for future use).
flagsA A valid combination of index conversion and matrix storage flags and other meaningful flags.
The encouraged base choice here is RSB_FLAG_DEFAULT_RSB_MATRIX_FLAGS. If Fortran (1 based) indices
are being used for the IA, JA arrays, then the RSB_FLAG_FORTRAN_INDICES_INTERFACE flag should be
added. If symmetric storage is desired, then RSB_FLAG_SYMMETRIC (or RSB_FLAG_HERMITIAN, for Hermitian
matrices) is necessary, in combination with either RSB_FLAG_LOWER or RSB_FLAG_UPPER. If you intend to
use this matrix for triangular solution (e.g.: rsb_spsv()/rsb_spsm()), it needs to be triangular and
specified with either RSB_FLAG_LOWER_TRIANGULAR or RSB_FLAG_UPPER_TRIANGULAR, and not have
RSB_FLAG_LOWER_SYMMETRIC or RSB_FLAG_LOWER_HERMITIAN. Nonzeroes non complying with the specified
flags will be ignored. If a matrix is both RSB_FLAG_LOWER_TRIANGULAR and RSB_FLAG_UPPER_TRIANGULAR at
the same time, then it's diagonal, for which shorthand: RSB_FLAG_DIAGONAL can be used. If
RSB_FLAG_UNIT_DIAG_IMPLICIT is present, diagonal entries will be not represented but assumed to be
unitary. If RSB_FLAG_DUPLICATES_SUM is present, duplicate entries will be summed together. If
RSB_FLAG_DISCARD_ZEROS is present, zeroes will be discarded.
errvalp An optional (can be NULL) pointer to rsb_err_t where the error status will be written to.
Returns
On success, a valid pointer (struct rsb_mtx_t*) to the newly allocated matrix structure; on error,
NULL.
Seealsorsb_mtx_alloc_from_coo_const, rsb_mtx_alloc_from_coo_inplace, rsb_mtx_free, rsb_mtx_clone,
rsb_mtx_alloc_from_csr_const, rsb_mtx_alloc_from_csc_const, rsb_mtx_alloc_from_csr_inplace,
rsb_mtx_switch_to_csr, rsb_mtx_alloc_from_coo_begin, rsb_mtx_alloc_from_coo_endstructrsb_mtx_t*rsb_mtx_alloc_from_csr_inplace(void*VA,rsb_nnz_idx_t*RP,rsb_coo_idx_t*JA,rsb_nnz_idx_tnnzA,rsb_type_ttypecode,rsb_coo_idx_tnrA,rsb_coo_idx_tncA,rsb_blk_idx_tbrA,rsb_blk_idx_tbcA,rsb_flags_tflagsA,rsb_err_t*errvalp)
Given as input CSR arrays VA,RP,JA , allocates and assembles an RSB matrix reusing input arrays.
Assumes all three VA,IA,JA arrays are at least max(nnzA,nrA+1,ncA+1) sized. The user is expected NOT to
use these arrays until the matrix has been destroyed with rsb_mtx_free(). Then, it is possible to use
these arrays again.
ParametersVA,RP,JA Input numerical values (VA) array; compressed rows (RP) and column (JA) input indices
arrays. Will not be freed by rsb_mtx_free().
nnzA The number of nonzeroes in the input arrays representing matrix $A$.
typecode A valid type code for the given (numerical array) input pointer (see
matrix_type_symbols_section).
nrA,ncA The number of rows and columns of the sparse matrix $A$.
brA,bcA Blocking parameters: brA should be set to 1 or RSB_DEFAULT_ROW_BLOCKING (currently unused,
reserved for future use); bcA should be set to 1 or RSB_DEFAULT_ROW_BLOCKING (currently unused,
reserved for future use).
flagsA A valid combination of index conversion and matrix storage flags and other meaningful flags.
The encouraged base choice here is RSB_FLAG_DEFAULT_RSB_MATRIX_FLAGS. If Fortran (1 based) indices
are being used for the IA, JA arrays, then the RSB_FLAG_FORTRAN_INDICES_INTERFACE flag should be
added. If symmetric storage is desired, then RSB_FLAG_SYMMETRIC (or RSB_FLAG_HERMITIAN, for Hermitian
matrices) is necessary, in combination with either RSB_FLAG_LOWER or RSB_FLAG_UPPER. If you intend to
use this matrix for triangular solution (e.g.: rsb_spsv()/rsb_spsm()), it needs to be triangular and
specified with either RSB_FLAG_LOWER_TRIANGULAR or RSB_FLAG_UPPER_TRIANGULAR, and not have
RSB_FLAG_LOWER_SYMMETRIC or RSB_FLAG_LOWER_HERMITIAN. Nonzeroes non complying with the specified
flags will be ignored. If a matrix is both RSB_FLAG_LOWER_TRIANGULAR and RSB_FLAG_UPPER_TRIANGULAR at
the same time, then it's diagonal, for which shorthand: RSB_FLAG_DIAGONAL can be used. If
RSB_FLAG_UNIT_DIAG_IMPLICIT is present, diagonal entries will be not represented but assumed to be
unitary. If RSB_FLAG_DUPLICATES_SUM is present, duplicate entries will be summed together. If
RSB_FLAG_DISCARD_ZEROS is present, zeroes will be discarded.
errvalp An optional (can be NULL) pointer to rsb_err_t where the error status will be written to.
Returns
On success, a valid pointer (struct rsb_mtx_t*) to the newly allocated matrix structure; on error,
NULL.
Seealsorsb_mtx_alloc_from_coo_const, rsb_mtx_alloc_from_coo_inplace, rsb_mtx_free, rsb_mtx_clone,
rsb_mtx_alloc_from_csr_const, rsb_mtx_alloc_from_csc_const, rsb_mtx_alloc_from_csr_inplace,
rsb_mtx_switch_to_csr, rsb_mtx_alloc_from_coo_begin, rsb_mtx_alloc_from_coo_endrsb_err_trsb_mtx_clone(structrsb_mtx_t**mtxBpp,rsb_type_ttypecode,rsb_trans_ttransA,constvoid*alphap,conststructrsb_mtx_t*mtxAp,rsb_flags_tflags)
This function clones a given matrix, allocating a fresh data structure or overwriting an existing one.
Target type (specified by typecode) can be different from that in the matrix. If alphap=NULL, the cloned
matrix will not be scaled.
This new structure will be completely separated and independent from the original one.
Examples:
// will clone the matrix exactly
errval = rsb_mtx_clone(&mtxBp,RSB_NUMERICAL_TYPE_SAME_TYPE,RSB_TRANSPOSITION_N,NULL,mtxAp,RSB_FLAG_IDENTICAL_FLAGS);
// will clone the transpose of the matrix
errval = rsb_mtx_clone(&mtxBp,RSB_NUMERICAL_TYPE_SAME_TYPE,RSB_TRANSPOSITION_T,NULL,mtxAp,RSB_FLAG_IDENTICAL_FLAGS);
// will clone the lower triangle of the matrix
errval = rsb_mtx_clone(&mtxBp,RSB_NUMERICAL_TYPE_SAME_TYPE,RSB_TRANSPOSITION_N,NULL,mtxAp,RSB_FLAG_TRIANGULAR|RSB_FLAG_LOWER);
ParametersmtxBpp Valid rsb_mtx_t pointer to an address for matrix $B$. If *mtxBpp==NULL, a fresh clone will be
assigned there; if not, the existing matrix structure will be freed and allocated to host the new
one. The case *mtxBpp==mtxAp is supported.
typecode A valid type code for the desired output matrix (see matrix_type_symbols_section).
transA Transposition parameter for $A$ (see matrix_transposition_flags_section).
alphap Optional pointer (if NULL, will default to 1) to a numerical value for scaling the output. Of
the type code of mtxAp.
mtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
flags Either RSB_FLAG_IDENTICAL_FLAGS or a combination of other flags, e.g.:
RSB_FLAG_C_INDICES_INTERFACE, RSB_FLAG_SYMMETRIC, RSB_FLAG_HERMITIAN, RSB_FLAG_TRIANGULAR,
RSB_FLAG_UPPER, RSB_FLAG_LOWER, RSB_FLAG_UNIT_DIAG_IMPLICIT, RSB_FLAG_DISCARD_ZEROS. Flag
RSB_FLAG_EXTERNALLY_ALLOCATED_ARRAYS is forbidden. Flag RSB_FLAG_FORTRAN_INDICES_INTERFACE is
ignored.
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Example snip:
if( RSB_ERR_NO_ERROR != (errval =
rsb_mtx_clone(&mtxAp,RSB_NUMERICAL_TYPE_SAME_TYPE,
RSB_TRANSPOSITION_T,NULL,mtxAp,RSB_FLAG_IDENTICAL_FLAGS)))
{
goto err;
}
Seealsorsb_mtx_alloc_from_coo_const, rsb_mtx_alloc_from_coo_inplace, rsb_mtx_free, rsb_mtx_clone,
rsb_mtx_alloc_from_csr_const, rsb_mtx_alloc_from_csc_const, rsb_mtx_alloc_from_csr_inplace,
rsb_mtx_switch_to_csr, rsb_mtx_alloc_from_coo_begin, rsb_mtx_alloc_from_coo_endstructrsb_mtx_t*rsb_mtx_free(structrsb_mtx_t*mtxAp)
Frees a previously allocated sparse matrix structure.
In the case the matrix has the RSB_FLAG_EXTERNALLY_ALLOCATED_ARRAYS flag, the main three data arrays
VA,IA,JA will not be freed by rsb_mtx_free (see
rsb_mtx_alloc_from_coo_inplace,rsb_mtx_alloc_from_csr_inplace).
ParametersmtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
Returns
Always NULL.
Example freeing a sparse matrix:
rsb_mtx_free(mtxAp);
Seealsorsb_mtx_alloc_from_coo_const, rsb_mtx_alloc_from_coo_inplace, rsb_mtx_free, rsb_mtx_clone,
rsb_mtx_alloc_from_csr_const, rsb_mtx_alloc_from_csc_const, rsb_mtx_alloc_from_csr_inplace,
rsb_mtx_switch_to_csr, rsb_mtx_alloc_from_coo_begin, rsb_mtx_alloc_from_coo_endrsb_err_trsb_mtx_get_coo(conststructrsb_mtx_t*mtxAp,void*VA,rsb_coo_idx_t*IA,rsb_coo_idx_t*JA,rsb_flags_tflags)
Returns the matrix converted in a coordinate storage format.
Elements will be stored in no particular order.
If there are structural or fill-in zero elements, these will be skipped.
Writes as many entries as there are nonzeroes (use
rsb_mtx_get_info(mtxAp,RSB_MIF_MATRIX_NNZ__TO__RSB_NNZ_INDEX_T,&nnz)) to find out how many in order to
allocate the arrays correctly.
ParametersmtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
VA,IA,JA Output numerical values (VA) array; output row (IA) and column (JA) indices arrays.
flags Either RSB_FLAG_FORTRAN_INDICES_INTERFACE or RSB_FLAG_C_INDICES_INTERFACE (see flags_section
flags section).
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Seealsorsb_mtx_get_coo, rsb_mtx_get_csr, rsb_mtx_get_rows_sparse, rsb_mtx_get_coo_block, rsb_mtx_get_prec,
rsb_mtx_get_nrm, rsb_mtx_get_vec, rsb_file_mtx_get_dims, rsb_mtx_get_valsrsb_err_trsb_mtx_get_coo_block(conststructrsb_mtx_t*mtxAp,void*VA,rsb_coo_idx_t*IA,rsb_coo_idx_t*JA,rsb_coo_idx_tfrA,rsb_coo_idx_tlrA,rsb_coo_idx_tfcA,rsb_coo_idx_tlcA,constrsb_coo_idx_t*IREN,constrsb_coo_idx_t*JREN,rsb_nnz_idx_t*rnzp,rsb_flags_tflags)
Writes in COO format the specified submatrix.
Works in two stages: first the user invokes it with VA,IA,JA set to NULL to get *rnzp. Then the VA,IA,JA
arrays can be allocated, and the function called again, this time with rnzp=NULL but the VA,IA,JA arrays
pointers non NULL (or at least, one of them).
ParametersmtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
VA,IA,JA Output numerical values (VA) array; output row (IA) and column (JA) indices arrays.
frA,lrA First and last row indices.
fcA,lcA First and last column indices.
IREN,JREN Renumbering arrays for IA and JA (respectively rows count and columns count sized). If
NULL, no renumbering will be used.
rnzp A pointer where the number of relevant nonzero elements will be written to.
flags Either RSB_FLAG_FORTRAN_INDICES_INTERFACE or RSB_FLAG_C_INDICES_INTERFACE (see flags_section
flags section).
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Examples:
rsb_coo_idx_t nzi;
rsb_coo_idx_t *IA = NULL;
rsb_coo_idx_t *JA = NULL;
const rsb_coo_idx_t IREN[]={0,1,2,3};
const rsb_coo_idx_t JREN[]={3,2,1,0};
RSB_DEFAULT_TYPE *VA = NULL;
const size_t so = sizeof(RSB_DEFAULT_TYPE);
const size_t si = sizeof(rsb_coo_idx_t);
rsb_err_t errval;
rsb_flags_t flagsA = RSB_FLAG_NOFLAGS;
rsb_nnz_idx_t rnz = 0;
rsb_coo_idx_t frA=0,lrA=1; // first two rows
rsb_coo_idx_t fcA=0,lcA=4; // 5 (all) columns
// get the nnz count only
errval=rsb_mtx_get_coo_block
(mtxAp,NULL,NULL,NULL,frA,lrA,fcA,lcA,NULL,NULL,&rnz,flagsA);
if(errval != RSB_ERR_NO_ERROR )
goto err;
// allocate VA, IA, JA to rnz elements
IA = calloc(rnz, si);
JA = calloc(rnz, si);
VA = calloc(rnz, so);
// get the rnz values then
errval=rsb_mtx_get_coo_block
(mtxAp, VA, IA, JA,frA,lrA,fcA,lcA,NULL,NULL,NULL,flagsA);
if(errval != RSB_ERR_NO_ERROR )
goto err;
for(nzi=0;nzi<rnz;++nzi)
printf("%d/%d %d %d -> %d\n",(int)nzi,(int)rnz,
(int)IA[nzi],(int)JA[nzi],(int)VA[nzi]);
// get the rnz values again, renumbered
errval=rsb_mtx_get_coo_block
(mtxAp, VA, IA, JA,frA,lrA,fcA,lcA,IREN,JREN,NULL,flagsA);
if(errval != RSB_ERR_NO_ERROR )
goto err;
for(nzi=0;nzi<rnz;++nzi)
printf("%d/%d %d %d -> %d\n",(int)nzi,(int)rnz,
(int)IA[nzi],(int)JA[nzi],(int)VA[nzi]);
free(VA);
free(IA);
free(JA);
And other examples:
// get nnz count first
errval=rsb_mtx_get_coo_block(mtxAp,NULL,NULL,NULL,frA,lrA,fcA,lcA,NULL,NULL,&rnz,flags )
// allocate VA, IA, JA to rnz elements
...
// get the rnz values then
errval=rsb_mtx_get_coo_block(mtxAp, VA, IA, JA,frA,lrA,fcA,lcA,NULL,NULL,NULL,flags )
Warning
Expect this function to change soon (e.g.: have scaling parameters, etc.). Contact the author if you
intend to use it.
Seealsorsb_mtx_get_coo, rsb_mtx_get_csr, rsb_mtx_get_rows_sparse, rsb_mtx_get_coo_block, rsb_mtx_get_prec,
rsb_mtx_get_nrm, rsb_mtx_get_vec, rsb_file_mtx_get_dims, rsb_mtx_get_valsrsb_err_trsb_mtx_get_csr(rsb_type_ttypecode,conststructrsb_mtx_t*mtxAp,void*VA,rsb_nnz_idx_t*RP,rsb_coo_idx_t*JA,rsb_flags_tflags)
Fills the given arrays with the matrix expressed in the CSR format.
Parameterstypecode A valid type code for the given (numerical array) input pointer (see
matrix_type_symbols_section).
mtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
VA,RP,JA Output numerical values (VA) array, compressed row indices (RP) and column indices (JA)
arrays.
flags Either RSB_FLAG_FORTRAN_INDICES_INTERFACE or RSB_FLAG_C_INDICES_INTERFACE (see flags_section
flags section).
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Seealsorsb_mtx_get_coo, rsb_mtx_get_csr, rsb_mtx_get_rows_sparse, rsb_mtx_get_coo_block, rsb_mtx_get_prec,
rsb_mtx_get_nrm, rsb_mtx_get_vec, rsb_file_mtx_get_dims, rsb_mtx_get_valsrsb_err_trsb_mtx_get_info(conststructrsb_mtx_t*mtxAp,enumrsb_mif_tmiflags,void*minfop)
Returns a specified matrix (numerical) property.
ParametersmtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
miflags A valid value of matrix info flags (see rsb_mif_t for valid values).
minfop Pointer to a variable of the right type, according to the matrix info flag specification (see
rsb_mif_t).
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Example snip:
rsb_real_t isopnnz;
const enum rsb_mif_t miflags =
RSB_MIF_INDEX_STORAGE_IN_BYTES_PER_NNZ__TO__RSB_REAL_T;
errval = rsb_mtx_get_info(mtxAp, miflags, &isopnnz);
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_mtx_get_info!\n");
goto err;
}
printf("RSB matrix uses %lf bytes per nnz.\n",(double)isopnnz);
Seealsorsb_mtx_get_info, rsb_mtx_get_info_str, rsb_file_mtx_save, rsb_file_vec_load, rsb_file_mtx_loadrsb_err_trsb_mtx_get_info_str(conststructrsb_mtx_t*mtxAp,constrsb_char_t*mis,void*minfop,size_tbuflen)
Returns a specified matrix (numerical) property, via a string form query.
ParametersmtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
mis A string specifying any identifier among the matrix info ones. See rsb_mif_t for a list of valid
identifiers that can be supplied in string form.
minfop Pointer to a variable of the right type, according to the matrix info flag specification (see
rsb_mif_t).
buflen If greater than 0, minfop will be treated as a string of length buflen and filled with the
desired value via the standard snprintf()function.ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Example snip:
rsb_mtx_get_info_str(mtxAp,"RSB_MIF_MATRIX_INFO__TO__CHAR_P",
ib,sizeof(ib));
printf("%s",ib);
Seealsorsb_mtx_get_info, rsb_mtx_get_info_str, rsb_file_mtx_save, rsb_file_vec_load, rsb_file_mtx_loadrsb_err_trsb_mtx_get_nrm(conststructrsb_mtx_t*mtxAp,void*Np,enumrsb_extff_tflags)
Computes a matrix norm (either infinite-norm or or 2-norm or 1-norm).
ParametersmtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
Np Points to a scalar value which will be overwritten with the selected norm.
flags Either RSB_EXTF_NORM_ONE or RSB_EXTF_NORM_TWO or RSB_EXTF_NORM_INF.
In case of a complex type, only the real part will be written to Np.
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Seealsorsb_mtx_get_coo, rsb_mtx_get_csr, rsb_mtx_get_rows_sparse, rsb_mtx_get_coo_block, rsb_mtx_get_prec,
rsb_mtx_get_nrm, rsb_mtx_get_vec, rsb_file_mtx_get_dims, rsb_mtx_get_valsrsb_err_trsb_mtx_get_prec(void*opdp,conststructrsb_mtx_t*mtxAp,rsb_precf_tprec_flags,constvoid*ipdp)
A function computing a simple preconditioner out of mtxAp.
Parametersopdp Preconditioner data pointer (output).
mtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
prec_flags Valid preconditioner request flags (currently, only RSB_PRECF_ILU0 is supported; for it,
*opdp will be overwritten with two rsb_mtx_t pointers, respectively a lower and an upper matrix.).
ipdp Preconditioner data pointer (input) (ignored at the moment).
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Example:
struct rsb_mtx_t *mtxAp = NULL; /* matrix structure pointer */
struct rsb_mtx_t *mtxLUp [2]; /* matrix structure pointer */
rsb_precf_t prec_flags = RSB_PRECF_ILU0;
if((errval = rsb_lib_init(RSB_NULL_INIT_OPTIONS)) !=
RSB_ERR_NO_ERROR)
{
printf("Error initializing the library!\n");
goto err;
}
mtxAp = rsb_mtx_alloc_from_coo_const(
VA,IA,JA,nnzA,typecode,nrA,ncA,brA,bcA,
RSB_FLAG_DEFAULT_RSB_MATRIX_FLAGS /* force rsb */
| RSB_FLAG_DUPLICATES_SUM /* sum dups */
| RSB_FLAG_TRIANGULAR /* need triangle for spsv */
, &errval);
if((!mtxAp) || (errval != RSB_ERR_NO_ERROR))
{
printf("Error while allocating the matrix!\n");
goto err;
}
errval = rsb_mtx_get_prec(mtxLUp,mtxAp, prec_flags, NULL);
if( errval != RSB_ERR_NO_ERROR )
{
printf("Error while calling rsb_mtx_get_prec!\n");
goto err;
}
// ...
rsb_mtx_free(mtxLUp[0]);
rsb_mtx_free(mtxLUp[1]);
rsb_mtx_free(mtxAp );
Note
Matrix should be square, have at least two rows, and have at least one nonzero.
Seealsorsb_mtx_get_coo, rsb_mtx_get_csr, rsb_mtx_get_rows_sparse, rsb_mtx_get_coo_block, rsb_mtx_get_prec,
rsb_mtx_get_nrm, rsb_mtx_get_vec, rsb_file_mtx_get_dims, rsb_mtx_get_valsrsb_err_trsb_mtx_get_rows_sparse(rsb_trans_ttransA,constvoid*alphap,conststructrsb_mtx_t*mtxAp,void*VA,rsb_coo_idx_t*IA,rsb_coo_idx_t*JA,rsb_coo_idx_tfrA,rsb_coo_idx_tlrA,rsb_nnz_idx_t*rnzp,rsb_flags_tflags)
Writes to the given COO arrays the specified submatrix.
Invoke with VA,IA,JA set to NULL in order to get the nonzeroes count written to *rnzp, and know how large
the arrays should be.
IA can be NULL (in this case it will be ignored). The written rows are ordered.
ParametersmtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
VA,IA,JA Output numerical values (VA) array; input row (IA) and column (JA) indices arrays.
frA,lrA First and last row indices.
rnzp A pointer where the number of relevant nonzero elements will be written to.
alphap Optional pointer (if NULL, will default to 1) to a numerical value (of the same type as
matrix).
transA Transposition parameter for $A$ (see matrix_transposition_flags_section).
flags Either RSB_FLAG_FORTRAN_INDICES_INTERFACE or RSB_FLAG_C_INDICES_INTERFACE (see flags_section
flags section).
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Example snip:
rsb_coo_idx_t IA[] = { 0, 0, 0, 0 };
rsb_coo_idx_t JA[] = { 0, 0, 0, 0 };
RSB_DEFAULT_TYPE VA[] = { -1, -1, -1, -1 };
rsb_trans_t transA = RSB_TRANSPOSITION_N;
const rsb_coo_idx_t frA = 2, lrA = 2;
rsb_nnz_idx_t rnz;
RSB_DEFAULT_TYPE *alphap = NULL;
errval = rsb_mtx_get_rows_sparse(transA, NULL, mtxAp, NULL,
NULL, NULL, frA, lrA, &rnz, RSB_FLAG_NOFLAGS);
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_mtx_get_rows_sparse!\n");
goto err;
}
printf("Rows between %d and %d have %d nnz\n",
(int)frA,(int)lrA,(int)rnz);
errval = rsb_mtx_get_rows_sparse(transA, alphap, mtxAp,
VA, IA, JA, frA, lrA, &rnz, RSB_FLAG_NOFLAGS);
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_mtx_get_vals!\n");
goto err;
}
Seealsorsb_mtx_get_coo, rsb_mtx_get_csr, rsb_mtx_get_rows_sparse, rsb_mtx_get_coo_block, rsb_mtx_get_prec,
rsb_mtx_get_nrm, rsb_mtx_get_vec, rsb_file_mtx_get_dims, rsb_mtx_get_valsrsb_err_trsb_mtx_get_vals(conststructrsb_mtx_t*mtxAp,void*VA,constrsb_coo_idx_t*IA,constrsb_coo_idx_t*JA,rsb_nnz_idx_tnnz,rsb_flags_tflags)
Gets the specified matrix elements, if found. Please note that unlike rsb_mtx_set_vals, the matrix has to
be fully assembled here.
ParametersmtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
VA,IA,JA Output numerical values (VA) array; input row (IA) and column (JA) indices arrays.
nnz The number of nonzeroes in the input arrays.
flags Either RSB_FLAG_FORTRAN_INDICES_INTERFACE or RSB_FLAG_C_INDICES_INTERFACE (see flags_section
flags section).
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Example snip:
const rsb_coo_idx_t IA[] = { 2, 0, 2, 0 };
const rsb_coo_idx_t JA[] = { 2, 0, 0, 0 };
RSB_DEFAULT_TYPE VA[] = { -1, -1, -1, -1 };
errval = rsb_mtx_get_vals(mtxAp, VA, IA, JA, nnzA, RSB_FLAG_NOFLAGS);
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_mtx_get_vals!\n");
goto err;
}
Seealsorsb_mtx_get_coo, rsb_mtx_get_csr, rsb_mtx_get_rows_sparse, rsb_mtx_get_coo_block, rsb_mtx_get_prec,
rsb_mtx_get_nrm, rsb_mtx_get_vec, rsb_file_mtx_get_dims, rsb_mtx_get_valsrsb_err_trsb_mtx_get_vec(conststructrsb_mtx_t*mtxAp,void*Dp,enumrsb_extff_tflags)
Will overwrite a supplied array with a specific vector quantity.
ParametersmtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
Dp A valid pointer to a numerical vector array $D$.
flags Either one of the different extraction filter flags (e.g.: RSB_EXTF_DIAG, RSB_EXTF_SUMS_ROW,
...) .
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Seealsorsb_mtx_get_coo, rsb_mtx_get_csr, rsb_mtx_get_rows_sparse, rsb_mtx_get_coo_block, rsb_mtx_get_prec,
rsb_mtx_get_nrm, rsb_mtx_get_vec, rsb_file_mtx_get_dims, rsb_mtx_get_valsrsb_err_trsb_mtx_rndr(constchar*filename,conststructrsb_mtx_t*mtxAp,rsb_coo_idx_tpmWidth,rsb_coo_idx_tpmHeight,rsb_marf_trflags)
Renders a matrix to a file. Currently, only Encapsulated Postscript (EPS) is supported.
Parametersfilename The specified output file name (if NULL or '' (the empty string), will write to standard
output).
mtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
pmWidth Pixel map width (in pixels or points).
pmHeight Pixel map height (in pixels or points).
rflags The color mode; only RSB_MARF_RGB is supported for now (1 byte per channel, 3 channels ---
red, green, blue): this requires array pmp to be at least (3*pmlWidth*pmHeight) bytes large.
Example rendering a sparse matrix to Postscript:
if(RSB_ERR_NO_ERROR!=(errval =
rsb_mtx_rndr("pd.eps",mtxAp,512,512,RSB_MARF_EPS_B)))
goto err;
Setting environment variable RSB_USE_HOSTNAME=0 prevents hostname being in the EPS plot internal
comments.
Seealsorsb_mtx_rndr, rsb_file_mtx_rndrrsb_err_trsb_mtx_set_vals(structrsb_mtx_t*mtxAp,constvoid*VA,constrsb_coo_idx_t*IA,constrsb_coo_idx_t*JA,rsb_nnz_idx_tnnz,rsb_flags_tflags)
Updates the specified matrix elements, if found in the nonzero pattern.
In the special case of a matrix in assembly state (that is, one that has been created as empty with
rsb_mtx_alloc_from_coo_begin() and not yet assembled with rsb_mtx_alloc_from_coo_end() ) all the supplied
matrix elements will be accepted: whether already present or not.
ParametersmtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
VA,IA,JA Input numerical values (VA) array; row (IA) and column (JA) input indices arrays.
nnz The number of nonzeroes in the input arrays.
flags Either RSB_FLAG_FORTRAN_INDICES_INTERFACE or RSB_FLAG_C_INDICES_INTERFACE plus either
RSB_FLAG_DUPLICATES_SUM (to sum into) or RSB_FLAG_DUPLICATES_KEEP_LAST (to overwrite entries) (see
flags_section flags section).
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Seealsorsb_mtx_upd_vals, rsb_mtx_set_valsrsb_err_trsb_mtx_switch_to_coo(structrsb_mtx_t*mtxAp,void**VAp,rsb_coo_idx_t**IAp,rsb_coo_idx_t**JAp,rsb_flags_tflags)
Switches a matrix to COO arrays in place.
ParametersmtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
VAp,IAp,JAp Output numerical values (VAp) array pointer; output row (IAp) and column (JAp) indices
arrays pointers.
flags A combination of RSB_FLAG_C_INDICES_INTERFACE, RSB_FLAG_FORTRAN_INDICES_INTERFACE,
RSB_FLAG_FORTRAN_INDICES_INTERFACE. (see flags_section flags section).
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Note
This function is only valid if mtxAp has been assembled in place (that is, in the arrays that are
being reclaimed), so with e.g.: rsb_mtx_alloc_from_coo_inplace(). Please also note that the matrix
will get freed internally and so mtxAp will not be usable in any way afterwards.
Warning
This function has not been thoroughly tested.
Example:
rsb_coo_idx_t *RP = NULL;
rsb_coo_idx_t *JA = NULL;
RSB_DEFAULT_TYPE *VA = NULL;
errval = rsb_mtx_switch_to_coo(mtxAp, (void**)&VA,
&RP, &JA, RSB_FLAG_NOFLAGS);
// NOTE: no rsb_mtx_free() necessary now..
Seealsorsb_mtx_switch_to_coo,rsb_mtx_switch_to_coorsb_err_trsb_mtx_switch_to_csr(structrsb_mtx_t*mtxAp,void**VAp,rsb_coo_idx_t**IAp,rsb_coo_idx_t**JAp,rsb_flags_tflags)
Switches the matrix to the CSR format, in-place.
ParametersmtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
VAp,IAp,JAp Output numerical values (VAp) array pointer; output row (IAp) and column (JAp) indices
arrays pointers.
flags A valid combination of index conversion flags (that is, RSB_FLAG_C_INDICES_INTERFACE and
RSB_FLAG_FORTRAN_INDICES_INTERFACE) and other meaningful flags. Symmetry flags shall be the same as
in the matrix in use, because symmetry expansion may happen otherwise. Flags
RSB_FLAG_EXTERNALLY_ALLOCATED_ARRAYS are forbidden.
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Note
This function is only valid if mtxAp has been assembled in place (that is, in the arrays that are
being reclaimed), so with e.g.: rsb_mtx_alloc_from_coo_inplace(). Please also note that the matrix
will get freed internally and so mtxAp will not be usable in any way afterwards.
Warning
This function has not been thoroughly tested.
Example:
rsb_coo_idx_t *IA = NULL;
rsb_coo_idx_t *JA = NULL;
RSB_DEFAULT_TYPE *VA = NULL;
errval = rsb_mtx_switch_to_csr(mtxAp, (void**)&VA,
&IA, &JA, RSB_FLAG_NOFLAGS);
// NOTE: no rsb_mtx_free() necessary now..
Seealsorsb_mtx_switch_to_coo,rsb_mtx_switch_to_coorsb_err_trsb_mtx_upd_vals(structrsb_mtx_t*mtxAp,enumrsb_elopf_telop_flags,constvoid*omegap)
$ A <- op (A,Omega) $ Updates the matrix $A$ by applying either a row-wise or an elemental operation
$op$, which is determined by elop_flags. If an unary operation is selected, omegap can be NULL.
ParametersmtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
elop_flags Elemental operation specification flags (see rsb_elopf_t for valid choices).
omegap Pointer to a numerical location(s) (of the same type as matrix).
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Example snip:
enum rsb_elopf_t elop_flags = RSB_ELOPF_NEG;
const RSB_DEFAULT_TYPE omegap[] = {10};
errval = rsb_mtx_upd_vals(mtxAp, elop_flags, NULL);
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_mtx_upd_vals!\n");
goto err;
}
elop_flags = RSB_ELOPF_MUL;
errval = rsb_mtx_upd_vals(mtxAp, elop_flags, omegap);
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_mtx_upd_vals!\n");
goto err;
}
Seealsorsb_mtx_upd_vals, rsb_mtx_set_valsrsb_err_trsb_perror(void*stream,rsb_err_terrval)
Prints out to the specified stream a string corresponding to the error code (using <stdio.h>'s fprintf).
If stream==NULL, will print out to the default output stream; see RSB_IO_WANT_OUTPUT_STREAM .
Parametersstream A (FILE*) pointer, as declared in <stdio.h>; can be NULL.
errval A valid error flag value (see rsb_err_t).
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Seealsorsb_perror, rsb_strerror_rrsb_trans_trsb_psblas_trans_to_rsb_trans(constcharpsbtrans)
Translate a PSBLAS transposition value character to a librsb one.
See the PSBLAS library website/documentation for valid input values.
Parameterspsbtrans Transposition parameter value valid in the PSBLAS library.
Returns
A valid transposition code; that is RSB_TRANSPOSITION_N for 'N', RSB_TRANSPOSITION_T for 'T',
RSB_TRANSPOSITION_C for 'C', (See matrix_transposition_flags_section).
Example snip:
Seealsorsb_psblas_trans_to_rsb_transrsb_err_trsb_spmm(rsb_trans_ttransA,constvoid*alphap,conststructrsb_mtx_t*mtxAp,rsb_coo_idx_tnrhs,rsb_flags_torder,constvoid*Bp,rsb_nnz_idx_tldB,constvoid*betap,void*Cp,rsb_nnz_idx_tldC)
Updates a dense matrix with the product of sparse matrix by dense matrix; that is, computes $ C <- beta*
C + alpha* opa(A) * B $.
$opa( A )=A$ if transA=RSB_TRANSPOSITION_N;$opa(A)=A^T$iftransA=RSB_TRANSPOSITION_T;$opa(A)=A^H$iftransA=RSB_TRANSPOSITION_C;If--enable-rsb-num-threadshasbeenspecifiedatconfiguretime,theRSB_NUM_THREADSenvironmentvariablewilloverridethenumberofexecutingthreadsspecifiedbyOMP_NUM_THREADS.(SeealsoRSB_IO_WANT_EXECUTING_THREADS).Settingorder=RSB_FLAG_WANT_COLUMN_MAJOR_ORDERwithldC=0andldB=0implies'compact'defaults,thatisnoextrastridebetweenthecolumns.ParameterstransA Transposition parameter for $A$ (see matrix_transposition_flags_section).
alphap Optional pointer (if NULL, will default to 1) to a numerical value (of the same type as
matrix).
mtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
nrhs The number of right hand side vectors (cannot be <1).
order A flag among RSB_FLAG_WANT_COLUMN_MAJOR_ORDER and RSB_FLAG_WANT_ROW_MAJOR_ORDER. For contiguous
vector arrays, you probably want RSB_FLAG_WANT_COLUMN_MAJOR_ORDER.
Bp The input vector array.
ldB Leading dimension of Bp array.
betap Optional pointer (if NULL, will default to 1) to a numerical value.
Cp The output vector array.
ldC Leading dimension of Cp array.
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Note
Starting from version 1.3, librsb uses C++ kernels for rsb_spmv/rsb_spmm. Assuming you configured
--enable-debug-getenvs, you may set environment variable RSB_WANT_RSBPP=0 to turn use the old C
kernels.
Seealsorsb_spmv, rsb_spmm, rsb_spata, rsb_tune_spmmstructrsb_mtx_t*rsb_spmsp(rsb_type_ttypecode,rsb_trans_ttransA,constvoid*alphap,conststructrsb_mtx_t*mtxAp,rsb_trans_ttransB,constvoid*betap,conststructrsb_mtx_t*mtxBp,rsb_err_t*errvalp)
Computes the weighted product of two sparse matrices in a new sparse matrix (also known as SpGEMM
operation): $C <- alpha * opa(A) * beta * opb(B) $ Symmetry/Hermitian flags are ignored by this
operation.
$opa( A )=A$ if transA=RSB_TRANSPOSITION_N;$opa(A)=A^T$iftransA=RSB_TRANSPOSITION_T;$opa(A)=A^H$iftransA=RSB_TRANSPOSITION_C;$opb(B)=B$iftransB=RSB_TRANSPOSITION_N;$opb(B)=B^T$iftransB=RSB_TRANSPOSITION_T;$opb(B)=B^H$iftransB=RSB_TRANSPOSITION_C;Parameterstypecode A valid type code for the given (numerical array) input pointer (see
matrix_type_symbols_section).
transA Transposition parameter for $A$ (see matrix_transposition_flags_section).
alphap Optional pointer (if NULL, will default to 1) to a numerical value (of the same type as
matrix).
mtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
transB Transposition parameter for $B$ (see matrix_transposition_flags_section).
betap Optional pointer (if NULL, will default to 1) to a numerical value.
mtxBp Valid rsb_mtx_t pointer to matrix $B$ representation.
errvalp An optional (can be NULL) pointer to rsb_err_t where the error status will be written to.
Returns
On success, a valid pointer (struct rsb_mtx_t*) to the newly allocated matrix structure; on error,
NULL.
Example snip:
const rsb_trans_t transA = RSB_TRANSPOSITION_N;
const rsb_trans_t transB = RSB_TRANSPOSITION_N;
RSB_DEFAULT_TYPE *alphap = NULL;
RSB_DEFAULT_TYPE *betap = NULL;
struct rsb_mtx_t * mtxCp = NULL;
mtxCp = rsb_spmsp(typecode, transA, alphap, mtxAp,
transB, betap, mtxAp, &errval);
if( !mtxCp )
{
printf("Error calling rsb_spmsp!\n");
goto err;
}
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_spmsp!\n");
goto err;
}
Warning
Parameters alphap,betap,transA,transB are not yet taken in consideration. The following defaults are
valid: $alpha=1.0$ and $beta=1.0$, and transA=transB=RSB_TRANSPOSITION_N.Seealsorsb_spmsp_to_dense, rsb_sppsp, rsb_spmsp, rsb_mtx_add_to_densersb_err_trsb_spmsp_to_dense(rsb_type_ttypecode,rsb_trans_ttransA,constvoid*alphap,conststructrsb_mtx_t*mtxAp,rsb_trans_ttransB,constvoid*betap,conststructrsb_mtx_t*mtxBp,rsb_nnz_idx_tldC,rsb_nnz_idx_tnrC,rsb_nnz_idx_tncC,rsb_bool_trowmajorC,void*Cp)
Computes the product of sparse matrices and adds it to a dense matrix: $C <- alpha opa(A) * beta * opb(B)
$.
$opa( A )=A$ if transA=RSB_TRANSPOSITION_N;$opa(A)=A^T$iftransA=RSB_TRANSPOSITION_T;$opa(A)=A^H$iftransA=RSB_TRANSPOSITION_C;$opb(B)=B$iftransB=RSB_TRANSPOSITION_N;$opb(B)=B^T$iftransB=RSB_TRANSPOSITION_T;$opb(B)=B^H$iftransB=RSB_TRANSPOSITION_C;Parameterstypecode A valid type code for the given (numerical array) input pointer (see
matrix_type_symbols_section).
transA Transposition parameter for $A$ (see matrix_transposition_flags_section).
alphap Optional pointer (if NULL, will default to 1) to a numerical value (of the same type as
matrix).
mtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
transB Transposition parameter for $B$ (see matrix_transposition_flags_section).
betap Optional pointer (if NULL, will default to 1) to a numerical value.
mtxBp Valid rsb_mtx_t pointer to matrix $B$ representation.
ldC Leading dimension of Cp array.
nrC,ncC The number of rows and columns for the dense matrix $C$.
rowmajorCRSB_BOOL_TRUE if the dense matrix $C$ is considered stored as row major, or RSB_BOOL_FALSE
if as column major.
Cp Array representing the dense matrix $C$.
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Warning
Parameters alphap,betap,transA,transB are not yet taken in consideration. The following defaults are
valid: $alpha=1.0$ and $beta=1.0$, and transA=transB=RSB_TRANSPOSITION_N.
Example snip:
const rsb_nnz_idx_t ldC = 4, nrC = 3, ncC = 3;
const rsb_bool_t rowmajorC = RSB_BOOL_TRUE;
RSB_DEFAULT_TYPE Cp[ /*ldC*nrC*/ ] = {
0, 0, 0, -99,
0, 0, 0, -99,
0, 0, 0, -99
};
const rsb_trans_t transA = RSB_TRANSPOSITION_N;
const rsb_trans_t transB = RSB_TRANSPOSITION_N;
RSB_DEFAULT_TYPE *alphap = NULL;
RSB_DEFAULT_TYPE *betap = NULL;
errval = rsb_spmsp_to_dense(typecode, transA, alphap, mtxAp,
transB, betap, mtxAp , ldC, nrC, ncC, rowmajorC, Cp);
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_spmsp_to_dense!\n");
goto err;
}
Seealsorsb_spmsp_to_dense, rsb_sppsp, rsb_spmsp, rsb_mtx_add_to_densersb_err_trsb_spmv(rsb_trans_ttransA,constvoid*alphap,conststructrsb_mtx_t*mtxAp,constvoid*Xp,rsb_coo_idx_tincX,constvoid*betap,void*Yp,rsb_coo_idx_tincY)
Multiplies a sparse matrix $opa(A)$ by a vector $X$, updating vector $Y$.
Computes $Y <- beta Y + alpha * opa(A) * X $.
It is not allowed to supply same Xp and Yp (that is, Xp==Yp).
$opa( A )=A$ if transA=RSB_TRANSPOSITION_N;$opa(A)=A^T$iftransA=RSB_TRANSPOSITION_T;$opa(A)=A^H$iftransA=RSB_TRANSPOSITION_C;If--enable-rsb-num-threadshasbeenspecifiedatconfiguretime,theRSB_NUM_THREADSenvironmentvariablewilloverridethenumberofexecutingthreadsspecifiedbyOMP_NUM_THREADS.(SeealsoRSB_IO_WANT_EXECUTING_THREADS).ParameterstransA Transposition parameter for $A$ (see matrix_transposition_flags_section).
alphap Optional pointer (if NULL, will default to 1) to a numerical value (of the same type as
matrix).
mtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
Xp The input vector array.
incX Spacing of vector elements in each input vector array (>=1).
betap Optional pointer (if NULL, will default to 1) to a numerical value.
Yp The output array vector.
incY Spacing of vector elements in each output vector array (>=1).
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Example snip:
if((errval =
rsb_spmv(RSB_TRANSPOSITION_N,&one,mtxAp,B,1,&one,X,1))
!= RSB_ERR_NO_ERROR )
{
printf("Error performing a multiplication!\n");
goto err;
}
Note
Starting from version 1.3, librsb uses C++ kernels for rsb_spmv/rsb_spmm. Assuming you configured
--enable-debug-getenvs, you may set environment variable RSB_WANT_RSBPP=0 to turn use the old C
kernels.
Seealsorsb_spmv, rsb_spmm, rsb_spata, rsb_tune_spmmstructrsb_mtx_t*rsb_sppsp(rsb_type_ttypecode,rsb_trans_ttransA,constvoid*alphap,conststructrsb_mtx_t*mtxAp,rsb_trans_ttransB,constvoid*betap,conststructrsb_mtx_t*mtxBp,rsb_err_t*errvalp)
Computes the weighted sum of two sparse matrices, returning a new matrix: $C <- alpha* transA(A) + beta*
transB{B} $ Symmetry flags are ignored in this operation.
$opa( A )=A$ if transA=RSB_TRANSPOSITION_N;$opa(A)=A^T$iftransA=RSB_TRANSPOSITION_T;$opa(A)=A^H$iftransA=RSB_TRANSPOSITION_C;$opb(B)=B$iftransB=RSB_TRANSPOSITION_N;$opb(B)=B^T$iftransB=RSB_TRANSPOSITION_T;$opb(B)=B^H$iftransB=RSB_TRANSPOSITION_C;Parameterstypecode A valid type code for the given (numerical array) input pointer (see
matrix_type_symbols_section).
transA Transposition parameter for $A$ (see matrix_transposition_flags_section).
alphap Optional pointer (if NULL, will default to 1) to a numerical value (of the same type as
matrix).
mtxAp Valid rsb_mtx_t pointer to matrix $A$ representation.
transB Transposition parameter for $B$ (see matrix_transposition_flags_section).
betap Optional pointer (if NULL, will default to 1) to a numerical value.
mtxBp Valid rsb_mtx_t pointer to matrix $B$ representation.
errvalp An optional (can be NULL) pointer to rsb_err_t where the error status will be written to.
Returns
On success, a valid pointer (struct rsb_mtx_t*) to the newly allocated matrix structure; on error,
NULL.
Example snip:
const rsb_trans_t transA = RSB_TRANSPOSITION_N;
const rsb_trans_t transB = RSB_TRANSPOSITION_N;
RSB_DEFAULT_TYPE *alphap = NULL;
RSB_DEFAULT_TYPE *betap = NULL;
struct rsb_mtx_t * mtxCp = NULL;
mtxCp = rsb_sppsp(typecode, transA, alphap, mtxAp,
transB, betap, mtxAp, &errval);
if( !mtxCp )
{
printf("Error calling rsb_sppsp!\n");
goto err;
}
if(errval != RSB_ERR_NO_ERROR )
{
printf("Error calling rsb_sppsp!\n");
goto err;
}
Seealsorsb_spmsp_to_dense, rsb_sppsp, rsb_spmsp, rsb_mtx_add_to_denseWarning
This function has not been thoroughly tested.
This function is not optimized.
rsb_err_trsb_spsm(rsb_trans_ttransT,constvoid*alphap,conststructrsb_mtx_t*mtxTp,rsb_coo_idx_tnrhs,rsb_flags_torder,constvoid*betap,constvoid*Bp,rsb_nnz_idx_tldB,void*Cp,rsb_nnz_idx_tldC)
Computes $Y <- alpha * opt( T )^{-1} * B $, with upper or lower triangular $T$.
$opt( T )=T$ if transT=RSB_TRANSPOSITION_N;$opt(T)=T^T$iftransT=RSB_TRANSPOSITION_T;$opt(T)=T^H$iftransT=RSB_TRANSPOSITION_C;ParameterstransT Transposition parameter for $T$ (see matrix_transposition_flags_section).
alphap Optional pointer (if NULL, will default to 1) to a numerical value (of the same type as
matrix).
mtxTp Valid rsb_mtx_t pointer to matrix $T$ representation. The matrix must be triangular; that is,
it must have been allocated with either RSB_FLAG_LOWER_TRIANGULAR or RSB_FLAG_UPPER_TRIANGULAR flags.
nrhs The number of right hand side vectors (cannot be <1).
order A flag among RSB_FLAG_WANT_COLUMN_MAJOR_ORDER and RSB_FLAG_WANT_ROW_MAJOR_ORDER. For contiguous
vector arrays, you probably want RSB_FLAG_WANT_COLUMN_MAJOR_ORDER.
betap Optional pointer (if NULL, will default to 1) to a numerical value.
Bp The input vector array.
ldB Leading dimension of Bp array.
Cp The output vector array.
ldC Leading dimension of Cp array.
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Seealsorsb_spsm, rsb_spsv, rsb_tune_spsmrsb_err_trsb_spsv(rsb_trans_ttransT,constvoid*alphap,conststructrsb_mtx_t*mtxTp,constvoid*Xp,rsb_coo_idx_tincX,void*Yp,rsb_coo_idx_tincY)
Computes $Y <- alpha * opt( T )^{-1} * X $, with upper or lower triangular $T$. It is allowed to supply
same Xp and Yp (that is, Xp==Yp).
$opt( T )=T$ if transT=RSB_TRANSPOSITION_N;$opt(T)=T^T$iftransT=RSB_TRANSPOSITION_T;$opt(T)=T^H$iftransT=RSB_TRANSPOSITION_C;ParameterstransT Transposition parameter for $T$ (see matrix_transposition_flags_section).
alphap Optional pointer (if NULL, will default to 1) to a numerical value (of the same type as
matrix).
mtxTp Valid rsb_mtx_t pointer to matrix $T$ representation. The matrix must be triangular; that is,
it must have been allocated with either RSB_FLAG_LOWER_TRIANGULAR or RSB_FLAG_UPPER_TRIANGULAR flags.
Xp The input vector array.
incX Spacing of vector elements in each input vector array (>=1).
Yp The output array vector.
incY Spacing of vector elements in each output vector array (>=1).
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error. If --enable-zero-division-checks-on-solve was
specified at configure time, attempts to solve a triangular matrix with zeroes on a diagonal will
fail.
Example backsolving a triangular system:
if((errval = rsb_spsv(RSB_TRANSPOSITION_N,&one,mtxAp,X,1,X,1))
!= RSB_ERR_NO_ERROR )
{
printf("Error performing triangular solve!\n");
goto err;
}
Seealsorsb_spsm, rsb_spsv, rsb_tune_spsmrsb_err_trsb_strerror_r(rsb_err_terrval,rsb_char_t*buf,size_tbuflen)
Writes a textual description of an error code in the specified string buffer. No more than buflen
characters will be written (comprehensive of the terminating NUL character). No action will be performed
on RSB_ERR_NO_ERROR.Noticetoothaterrorflagscannotbeaddedinthewayflagsare(e.g.(RSB_ERR_GENERIC_ERROR|RSB_ERR_BADARGS)evaluatestoRSB_ERR_GENERIC_ERROR).Parameterserrval A valid error flag value (see rsb_err_t).
buf A valid string buffer pointer where to write to.
buflen The string buffer length.
ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Examples:
char errbuf[256];
rsb_strerror_r(errval,&errbuf[0],sizeof(errbuf));
printf("Failed setting the"
" RSB_IO_WANT_EXTRA_VERBOSE_INTERFACE"
" library option (reason string:\n%s).\n",errbuf);
or
rsb_err_t errval = RSB_ERR_INTERNAL_ERROR;
// ...
if(errval != RSB_ERR_NO_ERROR)
{
char errbuf[256];
rsb_strerror_r(errval,&errbuf[0],sizeof(errbuf));
// error handling ...
Seealsorsb_perror, rsb_strerror_rrsb_time_trsb_time(void)
Returns the current time in seconds. This function is meant to be used for computing wall clock time
intervals (e.g.: for benchmarking purposes). The user should not rely on this function for absolute time
computations.
Returns
A value for the current time, in seconds.
Seealsorsb_time, rsb_coo_sortrsb_err_trsb_tune_spmm(structrsb_mtx_t**mtxOpp,rsb_real_t*sfp,rsb_int_t*tnp,rsb_int_tmaxr,rsb_time_tmaxt,rsb_trans_ttransA,constvoid*alphap,conststructrsb_mtx_t*mtxAp,rsb_coo_idx_tnrhs,rsb_flags_torder,constvoid*Bp,rsb_nnz_idx_tldB,constvoid*betap,void*Cp,rsb_nnz_idx_tldC)
An auto-tuner: optimizes either the matrix instance, the thread count or both for the rsb_spmm operation.
The tuner works by evaluating different instances and working threads variants. The instance leading to
faster operation time will be retained and given back to the user in *mtxOpp. If nrhs==1 and
order==RSB_FLAG_WANT_COLUMN_MAJOR_ORDER,unitarystridevectorsareassumed.Incaseoferror,theoriginalinputmatrixshallbeunaffected.ItispossibletospecifytheleadingdimensionsofBp,Cpimplicitly,withldB=0andldC=0:inthiscase,theirvalueswillbecomputedinternallyandifBp!=NULL,Cp!=NULL,theywillbeassumedofbeingsufficientlysized.Valuesofnrhs<1willbetreatedas1.Bp,CpcanbeNULL:temporaryvectorswillbeallocated,used,anddeallocatedwithinthetuner.IfmtxOpp=NULLand*tnp!=NULLthebestthreadcountwillbeprobedforthematrixgiveninmtxAp.Pleasenotethatifthreads-onlytuningisrequestedandmatrixhastoofewleaves(seeRSB_MIF_LEAVES_COUNT__TO__RSB_BLK_INDEX_T),tuningwillnotwork.IfmtxAp==NULL,thenthe*mtxOppinstancewillbeused;howeverinthiscase,ifabetterinstanceisfound,theoriginalwillbedestroyedaswithrsb_mtx_free().ThecasemtxAp!=NULL&&*mtxOpp!=NULLisillegalandwillcauseerrorcodeRSB_ERR_BADARGStobereturned.ParametersmtxOpp Optimal matrix structure pointer will be assigned to *mtxOpp (it may occur that *mtxOpp==mtxAp
on output). If mtxOpp is NULL then no data structure optimization will be attempted; rather, only
optimal threads search will occur (tnp must be not NULL then).
sfp Achieved speedup factor will be written to *sfp (unless sfp==NULL).
tnp If tnp==NULL on input, the current thread count will be utilized. Otherwise, if *tnp>0, then *tnp
will be used as first suggestion in optimal thread count searching. If tnp!=NULL ,on output *tnp will
be set to contain the optimal number of threads. Then, the user is expected to set this number of
threads using e.g.: RSB_REINIT_SINGLE_VALUE_SET(RSB_IO_WANT_EXECUTING_THREADS,tnp,errval).Pleasenotethatthiswillaffectthewholelibraryoperation,notonlythismatrix.maxrOptimizerroundsmaxcount.If<1,willbetreatedas1;if0willbedecidedautomatically.MaxisRSB_CONST_MAX_TUNING_ROUNDS.maxtMaximumtime(inseconds)peroptimizationround(doesnottakeinaccountconversiontime).Ifmaxt<0.0isprovided,-ceil(maxt)willbeinterpretedasnumberofiterationstocheckforeachoperationtimesample.Ifmaxt==0.0isprovided,adefaultchoicewillbemadeinstead.transATranspositionparameterfor$A$(seematrix_transposition_flags_section).alphapOptionalpointer(ifNULL,willdefaultto1)toanumericalvalue(ofthesametypeasmatrix).mtxApValidrsb_mtx_tpointertomatrix$A$representation.nrhsThenumberofrighthandsidevectors(cannotbe<1).orderAflagamongRSB_FLAG_WANT_COLUMN_MAJOR_ORDERandRSB_FLAG_WANT_ROW_MAJOR_ORDER.Forcontiguousvectorarrays,youprobablywantRSB_FLAG_WANT_COLUMN_MAJOR_ORDER.BpTheinputvectorarray.IfNULL,atemporary,internallyallocatedcopywillbeused.ldBLeadingdimensionofBparray.betapOptionalpointer(ifNULL,willdefaultto1)toanumericalvalue.CpTheoutputvectorarray.IfNULL,atemporary,internallyallocatedcopywillbeused.ldCLeadingdimensionofCparray.ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
Examples:
// obtain best thread count for mtxAp:
errval = rsb_tune_spmm(NULL ,&sf,&tn ,maxr,maxt,transA,&alpha,mtxAp,nrhs,order,Bp,ldB,&beta,Cp,ldC);
// obtain best thread count for mtxAp; Bp and Cp will be allocated by the tuner:
errval = rsb_tune_spmm(NULL ,&sf,&tn ,maxr,maxt,transA,&alpha,mtxAp,nrhs,order,NULL,0,&beta,NULL,0);
// obtain best clone of mtxAp (for current thread count):
assert(mtxOp == NULL && mtxAp != NULL);
errval = rsb_tune_spmm(&mtxOp,&sf,NULL,maxr,maxt,transA,&alpha,mtxAp,nrhs,order,Bp,ldB,&beta,Cp,ldC);
// obtain best clone of mtxAp and best thread count:
assert(mtxOp == NULL && mtxAp != NULL);
errval = rsb_tune_spmm(&mtxOp,&sf,&tn ,maxr,maxt,transA,&alpha,mtxAp,nrhs,order,Bp,ldB,&beta,Cp,ldC);
// replace mtxAp with best clone (if any):
errval = rsb_tune_spmm(&mtxAp,&sf,NULL,maxr,maxt,transA,&alpha,NULL ,nrhs,order,Bp,ldB,&beta,Cp,ldC);
// replace mtxAp with best clone (if any) and obtain best thread count:
errval = rsb_tune_spmm(&mtxAp,&sf,&tn ,maxr,maxt,transA,&alpha,NULL ,nrhs,order,Bp,ldB,&beta,Cp,ldC);
// illegal call:
assert(mtxOp != NULL && mtxAp != NULL);
errval = rsb_tune_spmm(&mtxOp,&sf,&tn ,maxr,maxt,transA,&alpha,mtxAp,nrhs,order,Bp,ldB,&beta,Cp,ldC);
Warning
This function is still experimental. In case of error, although the matrix shall be unaffected, the
library status may be affected (e.g.: execution thread count, default matrix subdivision).
Todo
Autotuning functionality is still object of much research. Need support for lightweight, threads-only
optimization.
Sample matrix sparse block structure before tuning
Sample matrix sparse block structure after tuning
Seealsorsb_spmv, rsb_spmm, rsb_spata, rsb_tune_spmmrsb_err_trsb_tune_spsm(structrsb_mtx_t**mtxOpp,rsb_real_t*sfp,rsb_int_t*tnp,rsb_int_tmaxr,rsb_time_tmaxt,rsb_trans_ttransA,constvoid*alphap,conststructrsb_mtx_t*mtxAp,rsb_coo_idx_tnrhs,rsb_flags_torder,constvoid*Bp,rsb_nnz_idx_tldB,constvoid*betap,void*Cp,rsb_nnz_idx_tldC)
An auto-tuner: optimizes either the matrix instance, the thread count or both for the rsb_spsm operation.
The tuner works by evaluating different instances and working threads variants. The instance leading to
faster operation time will be retained and given back to the user in *mtxOpp. If nrhs==1 and
order==RSB_FLAG_WANT_COLUMN_MAJOR_ORDER,unitarystridevectorsareassumed.Incaseoferror,theoriginalinputmatrixshallbeunaffected.ItispossibletospecifytheleadingdimensionsofBp,Cpimplicitly,withldB=0andldC=0:inthiscase,theirvalueswillbecomputedinternallyandifBp!=NULL,Cp!=NULL,theywillbeassumedofbeingsufficientlysized.Valuesofnrhs<1willbetreatedas1.Bp,CpcanbeNULL:temporaryvectorswillbeallocated,used,anddeallocatedwithinthetuner.IfmtxOpp=NULLand*tnp!=NULLthebestthreadcountwillbeprobedforthematrixgiveninmtxAp.Pleasenotethatifthreads-onlytuningisrequestedandmatrixhastoofewleaves(seeRSB_MIF_LEAVES_COUNT__TO__RSB_BLK_INDEX_T),tuningwillnotwork.IfmtxAp==NULL,thenthe*mtxOppinstancewillbeused;howeverinthiscase,ifabetterinstanceisfound,theoriginalwillbedestroyedaswithrsb_mtx_free().ThecasemtxAp!=NULL&&*mtxOpp!=NULLisillegalandwillcauseerrorcodeRSB_ERR_BADARGStobereturned.ParametersmtxOpp Optimal matrix structure pointer will be assigned to *mtxOpp (it may occur that *mtxOpp==mtxAp
on output). If mtxOpp is NULL then no data structure optimization will be attempted; rather, only
optimal threads search will occur (tnp must be not NULL then).
sfp Achieved speedup factor will be written to *sfp (unless sfp==NULL).
tnp If tnp==NULL on input, the current thread count will be utilized. Otherwise, if *tnp>0, then *tnp
will be used as first suggestion in optimal thread count searching. If tnp!=NULL ,on output *tnp will
be set to contain the optimal number of threads. Then, the user is expected to set this number of
threads using e.g.: RSB_REINIT_SINGLE_VALUE_SET(RSB_IO_WANT_EXECUTING_THREADS,tnp,errval).Pleasenotethatthiswillaffectthewholelibraryoperation,notonlythismatrix.maxrOptimizerroundsmaxcount.If<1,willbetreatedas1;if0willbedecidedautomatically.MaxisRSB_CONST_MAX_TUNING_ROUNDS.maxtMaximumtime(inseconds)peroptimizationround(doesnottakeinaccountconversiontime).Ifmaxt<0.0isprovided,-ceil(maxt)willbeinterpretedasnumberofiterationstocheckforeachoperationtimesample.Ifmaxt==0.0isprovided,adefaultchoicewillbemadeinstead.transATranspositionparameterfor$A$(seematrix_transposition_flags_section).alphapOptionalpointer(ifNULL,willdefaultto1)toanumericalvalue(ofthesametypeasmatrix).mtxApValidrsb_mtx_tpointertomatrix$A$representation.nrhsThenumberofrighthandsidevectors(cannotbe<1).orderAflagamongRSB_FLAG_WANT_COLUMN_MAJOR_ORDERandRSB_FLAG_WANT_ROW_MAJOR_ORDER.Forcontiguousvectorarrays,youprobablywantRSB_FLAG_WANT_COLUMN_MAJOR_ORDER.BpTheinputvectorarray.IfNULL,atemporary,internallyallocatedcopywillbeused.ldBLeadingdimensionofBparray.betapOptionalpointer(ifNULL,willdefaultto1)toanumericalvalue.CpTheoutputvectorarray.IfNULL,atemporary,internallyallocatedcopywillbeused.ldCLeadingdimensionofCparray.ReturnsRSB_ERR_NO_ERROR on correct operation, an error code otherwise. You can use rsb_strerror_r() or
rsb_perror() to get more information about the error.
If --enable-zero-division-checks-on-solve was specified at configure time, attempts to solve a triangular
matrix with zeroes on a diagonal will fail.
Warning
This function is still experimental. In case of error, although the matrix shall be unaffected, the
library status may be affected (e.g.: execution thread count, default matrix subdivision).
Todo
Autotuning functionality is still object of much research. Need support for lightweight, threads-only
optimization.
Sample matrix sparse block structure before tuning
Sample matrix sparse block structure after tuning
Seealsorsb_spsm, rsb_spsv, rsb_tune_spsmrsb_tune_spmm
Install Now
PNG Icons
Emojis
