Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions projects/rocsparse/docs/how-to/using-rocsparse.rst
Original file line number Diff line number Diff line change
Expand Up @@ -349,6 +349,8 @@ Function name yes no
:cpp:func:`rocsparse_v2_spmv_buffer_size()` x
:cpp:func:`rocsparse_spgeam_buffer_size()` x
:cpp:func:`rocsparse_spgeam()` x
:cpp:func:`rocsparse_spsort_buffer_size()` x
:cpp:func:`rocsparse_spsort()` x
:cpp:func:`rocsparse_sptrsv_buffer_size()` x
:cpp:func:`rocsparse_sptrsm_buffer_size()` x
:cpp:func:`rocsparse_spilu0_buffer_size()` x
Expand Down
10 changes: 10 additions & 0 deletions projects/rocsparse/docs/reference/api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,12 @@ Auxiliary functions
+-----------------------------------------------------+
|:cpp:func:`rocsparse_spgeam_get_output` |
+-----------------------------------------------------+
|:cpp:func:`rocsparse_create_spsort_descr` |
+-----------------------------------------------------+
|:cpp:func:`rocsparse_destroy_spsort_descr` |
+-----------------------------------------------------+
|:cpp:func:`rocsparse_spsort_set_input` |
+-----------------------------------------------------+
|:cpp:func:`rocsparse_create_spmv_descr` |
+-----------------------------------------------------+
|:cpp:func:`rocsparse_destroy_spmv_descr` |
Expand Down Expand Up @@ -664,6 +670,10 @@ documentation for details about the supported data types and compute types.
+-----------------------------------------------------+
|:cpp:func:`rocsparse_spgeam()` |
+-----------------------------------------------------+
|:cpp:func:`rocsparse_spsort_buffer_size()` |
+-----------------------------------------------------+
|:cpp:func:`rocsparse_spsort()` |
+-----------------------------------------------------+
|:cpp:func:`rocsparse_spmat_scale()` |
+-----------------------------------------------------+
|:cpp:func:`rocsparse_sddmm_buffer_size()` |
Expand Down
15 changes: 15 additions & 0 deletions projects/rocsparse/docs/reference/auxiliary.rst
Original file line number Diff line number Diff line change
Expand Up @@ -352,6 +352,21 @@ rocsparse_spgeam_set_input

.. doxygenfunction:: rocsparse_spgeam_set_input

rocsparse_create_spsort_descr
-----------------------------

.. doxygenfunction:: rocsparse_create_spsort_descr

rocsparse_destroy_spsort_descr
------------------------------

.. doxygenfunction:: rocsparse_destroy_spsort_descr

rocsparse_spsort_set_input
--------------------------

.. doxygenfunction:: rocsparse_spsort_set_input

Comment thread
jsandham marked this conversation as resolved.
Resolved
rocsparse_spgeam_get_output
---------------------------

Expand Down
15 changes: 15 additions & 0 deletions projects/rocsparse/docs/reference/enumerations.rst
Original file line number Diff line number Diff line change
Expand Up @@ -322,6 +322,21 @@ rocsparse_spgeam_output

.. doxygenenum:: rocsparse_spgeam_output

rocsparse_spsort_alg
--------------------

.. doxygenenum:: rocsparse_spsort_alg

rocsparse_spsort_input
----------------------

.. doxygenenum:: rocsparse_spsort_input

rocsparse_spsort_stage
----------------------

.. doxygenenum:: rocsparse_spsort_stage

rocsparse_sparse_to_dense_alg
-----------------------------

Expand Down
10 changes: 10 additions & 0 deletions projects/rocsparse/docs/reference/generic.rst
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,16 @@ rocsparse_spgeam()

.. doxygenfunction:: rocsparse_spgeam

rocsparse_spsort_buffer_size()
------------------------------

.. doxygenfunction:: rocsparse_spsort_buffer_size

rocsparse_spsort()
------------------

.. doxygenfunction:: rocsparse_spsort

rocsparse_spmat_scale()
-----------------------

Expand Down
5 changes: 5 additions & 0 deletions projects/rocsparse/docs/reference/types.rst
Original file line number Diff line number Diff line change
Expand Up @@ -139,4 +139,9 @@ rocsparse_spgeam_descr
----------------------

.. doxygentypedef:: rocsparse_spgeam_descr

rocsparse_spsort_descr
----------------------

.. doxygentypedef:: rocsparse_spsort_descr

Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
/*! \file */
/* ************************************************************************
* Copyright (C) 2026 Advanced Micro Devices, Inc. All rights Reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the Software), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*
* ************************************************************************ */

#ifndef ROCSPARSE_SPSORT_H
#define ROCSPARSE_SPSORT_H

#include "../../rocsparse-types.h"
#include "rocsparse/rocsparse-export.h"

#ifdef __cplusplus
extern "C" {
#endif

/*! \ingroup generic_module
* \details
* \p rocsparse_spsort_buffer_size returns the size of the required buffer to execute the given stage of the SpSort operation.
Comment thread
jsandham marked this conversation as resolved.
Resolved
* @param[in]
* handle handle to the rocSPARSE library context queue.
* @param[in]
* descr SpSort descriptor.
* @param[in]
* mat_A sparse matrix \f$A\f$ descriptor, the matrix to sort.
* @param[in]
* mat_B sparse matrix \f$B\f$ descriptor, the sorted output matrix. \p mat_B can be the same
* descriptor as \p mat_A to sort in place.
* @param[in]
* stage SpSort stage for the SpSort computation.
* @param[out]
* buffer_size number of bytes of the temporary storage buffer.
* @param[out]
* error error descriptor created if the returned status is not \ref rocsparse_status_success. A null pointer can be passed if an error descriptor is not required.
*
* \retval rocsparse_status_success the operation completed successfully.
* \retval rocsparse_status_invalid_handle the library context was not initialized.
* \retval rocsparse_status_invalid_pointer \p descr, \p mat_A, \p mat_B, or \p buffer_size pointer is invalid.
* \retval rocsparse_status_invalid_size \p mat_A and \p mat_B do not have the same dimensions or number of non-zeros, or the batch strides make the batches overlap.
* \retval rocsparse_status_invalid_value \p mat_A and \p mat_B do not have the same format, index types, data type, index base or batch count, or the direction is not supported for the format of \p mat_A.
* \retval rocsparse_status_not_implemented \p mat_A is not in COO, CSR or CSC format.
*/
ROCSPARSE_EXPORT
rocsparse_status rocsparse_spsort_buffer_size(rocsparse_handle handle,
rocsparse_spsort_descr descr,
rocsparse_const_spmat_descr mat_A,
Comment thread
jsandham marked this conversation as resolved.
Resolved
rocsparse_spmat_descr mat_B,
rocsparse_spsort_stage stage,
size_t* buffer_size,
Comment thread
jsandham marked this conversation as resolved.
Resolved
rocsparse_error* error);
Comment thread
jsandham marked this conversation as resolved.
Resolved

/*! \ingroup generic_module
* \brief Sparse matrix sorting.
*
* \details
* \p rocsparse_spsort sorts the sparse matrix \f$A\f$ and writes the result to the sparse matrix
* \f$B\f$. \f$A\f$ is left unchanged. \f$B\f$ must be created with the same format, dimensions,
* number of non-zeros, index types, data type and index base as \f$A\f$. If the same descriptor
* is passed for \p mat_A and \p mat_B, the matrix is sorted in place. Otherwise, the arrays of
* \f$B\f$ must not overlap the arrays of \f$A\f$.
*
* The supported formats are \ref rocsparse_format_coo, \ref rocsparse_format_csr and
* \ref rocsparse_format_csc. The direction set with \ref rocsparse_spsort_input_direction
* selects the sort order:
* - COO: \ref rocsparse_direction_row sorts the entries by row and then by column, and
* \ref rocsparse_direction_column sorts them by column and then by row.
* - CSR: only the column indices within each row are sorted, so the direction must be
Comment thread
jsandham marked this conversation as resolved.
Resolved
* \ref rocsparse_direction_row. The row pointer of \f$B\f$ is a copy of the row pointer of \f$A\f$.
* - CSC: only the row indices within each column are sorted, so the direction must be
* \ref rocsparse_direction_column. The column pointer of \f$B\f$ is a copy of the column pointer of \f$A\f$.
*
* Batched matrices are supported. They are set up with \ref rocsparse_coo_set_strided_batch,
Comment thread
jsandham marked this conversation as resolved.
Resolved
* \ref rocsparse_csr_set_strided_batch or \ref rocsparse_csc_set_strided_batch. Each batch is
* sorted independently. \f$A\f$ and \f$B\f$ must have the same batch count, and the strides of
* \f$A\f$ and \f$B\f$ may differ. Batches must not overlap:
* - The COO batch stride, and the CSR/CSC columns/values batch stride, must be at least the
Comment thread
jsandham marked this conversation as resolved.
Resolved
* number of non-zeros.
* - The CSR/CSC offsets batch stride must be zero, meaning all batches share one pointer
Comment thread
jsandham marked this conversation as resolved.
Resolved
* array, or at least the size of the pointer array. The offsets batch stride of \f$B\f$
* can only be zero if the offsets batch stride of \f$A\f$ is zero.
*
* \note
Comment thread
jsandham marked this conversation as resolved.
Resolved
* This routine does not support execution in a hipGraph context.
*
* @param[in]
* handle handle to the rocSPARSE library context queue.
* @param[in]
* descr SpSort descriptor.
* @param[in]
* mat_A sparse matrix \f$A\f$ descriptor, the matrix to sort.
* @param[inout]
* mat_B sparse matrix \f$B\f$ descriptor, the sorted output matrix. \p mat_B can be the same
* descriptor as \p mat_A to sort in place.
* @param[in]
* stage SpSort stage for the SpSort computation.
* @param[in]
* buffer_size number of bytes of the temporary storage buffer. \p buffer_size is
* determined by calling \ref rocsparse_spsort_buffer_size.
* @param[in]
* temp_buffer temporary storage buffer allocated by the user.
Comment thread
jsandham marked this conversation as resolved.
Resolved
* @param[out]
* error error descriptor created if the returned status is not \ref rocsparse_status_success. A null pointer can be passed if an error descriptor is not required.
Comment thread
jsandham marked this conversation as resolved.
Resolved
*
* \retval rocsparse_status_success the operation completed successfully.
* \retval rocsparse_status_invalid_handle the library context was not initialized.
* \retval rocsparse_status_invalid_pointer \p descr, \p mat_A, \p mat_B, or \p temp_buffer pointer is invalid.
* \retval rocsparse_status_invalid_size \p mat_A and \p mat_B do not have the same dimensions or number of non-zeros, or the batch strides make the batches overlap.
* \retval rocsparse_status_invalid_value \p mat_A and \p mat_B do not have the same format, index types, data type, index base or batch count, or the direction is not supported for the format of \p mat_A.
* \retval rocsparse_status_not_implemented \p mat_A is not in COO, CSR or CSC format.
*/
ROCSPARSE_EXPORT
rocsparse_status rocsparse_spsort(rocsparse_handle handle,
rocsparse_spsort_descr descr,
rocsparse_const_spmat_descr mat_A,
rocsparse_spmat_descr mat_B,
rocsparse_spsort_stage stage,
size_t buffer_size,
void* temp_buffer,
rocsparse_error* error);

#ifdef __cplusplus
}
#endif

#endif /* ROCSPARSE_SPSORT_H */
Original file line number Diff line number Diff line change
Expand Up @@ -58,5 +58,6 @@
#include "generic/rocsparse_sptrsv.h"
#include "generic/rocsparse_spvv.h"
#include "generic/rocsparse_v2_spmv.h"
#include "generic/rocsparse_spsort.h"

#endif // ROCSPARSE_GENERIC_H
59 changes: 59 additions & 0 deletions projects/rocsparse/library/include/rocsparse-auxiliary.h
Original file line number Diff line number Diff line change
Expand Up @@ -1485,6 +1485,65 @@ rocsparse_status rocsparse_create_extract_descr(rocsparse_extract_descr* desc
ROCSPARSE_EXPORT
rocsparse_status rocsparse_destroy_extract_descr(rocsparse_extract_descr descr);

/*! \ingroup aux_module
* \brief Sparse matrix SpSort routine descriptor creation.
*
* \details
* \p rocsparse_create_spsort_descr creates the descriptor of the \ref rocsparse_spsort_buffer_size and
* \ref rocsparse_spsort routines.
*
* @param[out]
* descr pointer to the descriptor of the SpSort routine.
*
* \retval rocsparse_status_success the operation completed successfully.
* \retval rocsparse_status_invalid_pointer \p descr pointer is invalid.
*/
ROCSPARSE_EXPORT
rocsparse_status rocsparse_create_spsort_descr(rocsparse_spsort_descr* descr);
Comment thread
jsandham marked this conversation as resolved.
Resolved
Comment thread
jsandham marked this conversation as resolved.
Resolved

/*! \ingroup aux_module
* \brief Destroy a sparse matrix SpSort descriptor.
*
* \details
* \p rocsparse_destroy_spsort_descr destroys the descriptor of the \ref rocsparse_spsort_buffer_size and
* \ref rocsparse_spsort routines.
*
* @param[in]
* descr descriptor of the SpSort routine.
* \retval rocsparse_status_success the operation completed successfully.
*/
ROCSPARSE_EXPORT
rocsparse_status rocsparse_destroy_spsort_descr(rocsparse_spsort_descr descr);
Comment thread
jsandham marked this conversation as resolved.
Resolved
Comment thread
jsandham marked this conversation as resolved.
Resolved

/*! \ingroup aux_module
* \brief Set the requested \ref rocsparse_spsort_input data in the SpSort descriptor.
*
* @param[in]
* handle the pointer to the handle to the rocSPARSE library context.
* @param[inout]
* descr the pointer to the SpSort descriptor.
* @param[in]
* input one of the values from \ref rocsparse_spsort_input.
* @param[in]
* data input data.
* @param[in]
* data_size_in_bytes input data size.
* @param[out]
* p_error error descriptor created if the returned status is not \ref rocsparse_status_success. A null pointer can be passed if an error descriptor is not required.
*
* \retval rocsparse_status_success the operation completed successfully.
* \retval rocsparse_status_invalid_pointer if \p descr or \p data is invalid.
* \retval rocsparse_status_invalid_value if \p input is invalid.
* \retval rocsparse_status_invalid_size if \p data_size_in_bytes is invalid.
*/
ROCSPARSE_EXPORT
rocsparse_status rocsparse_spsort_set_input(rocsparse_handle handle,
rocsparse_spsort_descr descr,
rocsparse_spsort_input input,
const void* data,
size_t data_size_in_bytes,
rocsparse_error* p_error);

/*! \ingroup aux_module
* \brief Sparse matrix SpGEAM routine descriptor creation.
*
Expand Down
45 changes: 45 additions & 0 deletions projects/rocsparse/library/include/rocsparse-types.h
Original file line number Diff line number Diff line change
Expand Up @@ -294,6 +294,14 @@ typedef struct _rocsparse_spilu0_descr* rocsparse_spilu0_descr;
*/
typedef struct _rocsparse_spildlt0_descr* rocsparse_spildlt0_descr;

/*! \ingroup types_module
* \brief \p rocsparse_spsort_descr is a structure holding the rocSPARSE spsort
* descriptor data. It must be initialized using
* the rocsparse_create_spsort_descr() routine. It should be destroyed at the
* end using rocsparse_destroy_spsort_descr().
*/
typedef struct _rocsparse_spsort_descr* rocsparse_spsort_descr;

#ifdef __cplusplus
extern "C" {
#endif
Expand Down Expand Up @@ -1386,6 +1394,43 @@ typedef enum rocsparse_spgeam_alg_
rocsparse_spgeam_alg_default = 0 /**< Default SpGEAM algorithm for the given format. */
} rocsparse_spgeam_alg;

/*! \ingroup types_module
* \brief List of SpSort algorithms.
*
* \details
* This is a list of supported \ref rocsparse_spsort_alg types that are used to sort a sparse
* matrix.
*/
typedef enum rocsparse_spsort_alg_
{
rocsparse_spsort_alg_default = 0, /**< Default SpSort algorithm for the given format. */
Comment thread
jsandham marked this conversation as resolved.
Resolved
} rocsparse_spsort_alg;

/*! \ingroup types_module
* \brief List of inputs to the SpSort descriptor.
*
* \details
* This is a list of possible inputs to the SpSort descriptor.
*/
typedef enum rocsparse_spsort_input_
{
rocsparse_spsort_input_alg, /**< Select algorithm for input on a SpSort descriptor. */
rocsparse_spsort_input_direction, /**< Select sorting direction for input on a SpSort descriptor. */
Comment thread
jsandham marked this conversation as resolved.
Resolved
} rocsparse_spsort_input;

/*! \ingroup types_module
* \brief List of SpSort stages.
*
* \details
* This is a list of possible stages during SpSort computation. The stages must be executed
* in the order \ref rocsparse_spsort_stage_analysis, then \ref rocsparse_spsort_stage_compute.
*/
typedef enum rocsparse_spsort_stage_
{
rocsparse_spsort_stage_analysis, /**< Analysis of the data. */
rocsparse_spsort_stage_compute /**< Performs the actual SpSort computation. */
} rocsparse_spsort_stage;

/*! \ingroup types_module
* \brief List of gpsv algorithms.
*
Expand Down
Loading