rocsparse_extract Interface Reference

rocsparse_extract Interface Reference#

HIPFORT API Reference: hipfort_rocsparse::rocsparse_extract Interface Reference

Sparse matrix extraction. More...

Public Member Functions
integer(kind(rocsparse_status_success)) function	rocsparse_extract_ (handle, descr, source, target, stage, buffer_size_in_bytes, buffer)

Detailed Description

Sparse matrix extraction.

rocsparse_extract performs the extraction of the lower or upper part of a sparse matrix into a new matrix.

rocsparse_extract requires multiple steps to complete. First, create the source and target sparse matrix descriptors. For example, in the case of CSR matrix format, this might look like:

// Build Source
rocsparse_spmat_descr source;
rocsparse_create_csr_descr(&source,
                           M,
                           N,
                           nnz,
                           dsource_row_ptr,
                           dsource_col_ind,
                           dsource_val,
                           rocsparse_indextype_i32,
                           rocsparse_indextype_i32,
                           rocsparse_index_base_zero,
                           rocsparse_datatype_f32_r);
 
// Build target
void * dtarget_row_ptr;
hipMalloc(&dtarget_row_ptr, sizeof(int32_t) * (M + 1));
rocsparse_spmat_descr target;
rocsparse_create_csr_descr(&target,
                           M,
                           N,
                           0,
                           dtarget_row_ptr,
                           nullptr,
                           nullptr,
                           rocsparse_indextype_i32,
                           rocsparse_indextype_i32,
                           rocsparse_index_base_zero,
                           rocsparse_datatype_f32_r);

Next, create the extraction descriptor and call rocsparse_extract_buffer_size with the stage rocsparse_extract_stage_analysis to determine the amount of temporary storage required. Allocate this temporary storage buffer and pass it to rocsparse_extract with the stage rocsparse_extract_stage_analysis.

// Create descriptor
rocsparse_extract_descr descr;
rocsparse_create_extract_descr(&descr,
                               source,
                               target,
                               rocsparse_extract_alg_default);
 
// Analysis phase
size_t buffer_size;
rocsparse_extract_buffer_size(handle,
                              descr,
                              source,
                              target,
                              rocsparse_extract_stage_analysis,
                              &buffer_size);
void* dbuffer = nullptr;
hipMalloc(&dbuffer, buffer_size);
rocsparse_extract(handle,
                  descr,
                  source,
                  target,
                  rocsparse_extract_stage_analysis,
                  buffer_size,
                  dbuffer);
hipFree(dbuffer);

Then calls rocsparse_extract_nnz to determine the number of non-zeros that will exist in the target matrix. After this is determined, allocate the column indices and values arrays of the target sparse matrix:

int64_t target_nnz;
rocsparse_extract_nnz(handle, descr, &target_nnz);
 
void* dtarget_col_ind,
void* dtarget_val;
hipMalloc(&dtarget_col_ind, sizeof(int32_t) * target_nnz);
hipMalloc(&dtarget_val, sizeof(float) * target_nnz);
rocsparse_csr_set_pointers(target, dtarget_row_ptr, dtarget_col_ind, dtarget_val);

Finally, call rocsparse_extract_buffer_size with the stage rocsparse_extract_stage_compute to determine the size of the temporary user-allocated storage needed for the computation of the column indices and values in the sparse target. Allocate this buffer and complete the conversion by calling rocsparse_extract using the rocsparse_extract_stage_compute stage:

// Calculation phase
rocsparse_extract_buffer_size(handle,
                              descr,
                              source,
                              target,
                              rocsparse_extract_stage_compute,
                              &buffer_size);
hipMalloc(&dbuffer, buffer_size);
rocsparse_extract(handle,
                  descr,
                  source,
                  target,
                  rocsparse_extract_stage_compute,
                  buffer_size,
                  dbuffer);
hipFree(dbuffer);

The target row pointer, column indices, and values arrays will now be filled with the upper or lower part of the source matrix.

The source and the target matrices must have the same format (see rocsparse_format ) and the same storage mode (see rocsparse_storage_mode ). The attributes of the target matrix, the fill mode rocsparse_fill_mode, and the diagonal type rocsparse_diag_type are used to parameterize the algorithm. These can be set on the target matrix using rocsparse_spmat_set_attribute. See the full example below.

Note: This routine is asynchronous with respect to the host. This routine supports execution in a hipGraph context.; Supported formats are rocsparse_format_csr and rocsparse_format_csc.; This routine does not support batched computation.

Parameters

[in]	handle	- handle to the rocSPARSE library context queue.
[in]	descr	- descriptor of the extract algorithm.
[in]	source	- sparse matrix descriptor.
[in]	target	- sparse matrix descriptor.
[in]	stage	- stage of the extract computation.
[in]	buffer_size_in_bytes	- size in bytes of the `buffer`.
[in]	buffer	- temporary storage buffer allocated by the user.

Return values

rocsparse_status_success	the operation completed successfully.
rocsparse_status_invalid_handle	the library context was not initialized.
rocsparse_status_invalid_value	if `stage` is invalid.
rocsparse_status_invalid_pointer	`descr`, `source`, `target`, or `buffer` pointer is invalid.

Example: This example extracts the lower part of CSR matrix into a CSR matrix.

Member Function/Subroutine Documentation