A high-performance general-purpose compute library

- Main Page
- Tutorials
- Release Notes
- Examples

Functions
sparse
ArrayFire Functions | ArrayFire Functions by Category » Linear Algebra » Sparse functions

Create a sparse array More...

## Functions
AFAPI array | sparse (const dim_t nRows, const dim_t nCols, const array values, const array rowIdx, const array colIdx, const af::storage stype=AF_STORAGE_CSR)
| This function converts af::array of values, row indices and column indices into a sparse array.
AFAPI array | sparse (const dim_t nRows, const dim_t nCols, const dim_t nNZ, const void *const values, const int *const rowIdx, const int *const colIdx, const dtype type=f32, const af::storage stype=AF_STORAGE_CSR, const af::source src=afHost)
| This function converts host or device arrays of values, row indices and column indices into a sparse array on the device.
AFAPI array | sparse (const array dense, const af::storage stype=AF_STORAGE_CSR)
| This function converts a dense af::array into a sparse array.
AFAPI af_err | af_create_sparse_array (af_array *out, const dim_t nRows, const dim_t nCols, const af_array values, const af_array rowIdx, const af_array colIdx, const af_storage stype)
| This function converts af::array of values, row indices and column indices into a sparse array.
AFAPI af_err | af_create_sparse_array_from_ptr (af_array *out, const dim_t nRows, const dim_t nCols, const dim_t nNZ, const void *const values, const int *const rowIdx, const int *const colIdx, const af_dtype type, const af_storage stype, const af_source src)
| This function converts host or device arrays of values, row indices and column indices into a sparse array on the device.
AFAPI af_err | af_create_sparse_array_from_dense (af_array *out, const af_array dense, const af_storage stype)
| This function converts a dense af_array into a sparse array.

## Detailed Description

Create a sparse array

The sparse creation function has 3 different types of inputs it can accept.

1. Independent af::array for values, row indices and column indices.
2. Independent host or device native arrays for values, row indices and column indices.
3. A dense af::array.

## Function Documentation

## ◆ af_create_sparse_array()

AFAPI af_err af_create_sparse_array | ( | af_array * | out,
|  | const dim_t | nRows,
|  | const dim_t | nCols,
|  | const af_array | values,
|  | const af_array | rowIdx,
|  | const af_array | colIdx,
|  | const af_storage | stype )

This function converts af::array of values, row indices and column indices into a sparse array.

Note
  This function only create references of these arrays into the sparse data structure and does not do deep copies.

Parameters

  [out] | out | af::array for the sparse array
  [in] | nRows | is the number of rows in the dense matrix
  [in] | nCols | is the number of columns in the dense matrix
  [in] | values | is the af_array containing the non-zero elements of the matrix
  [in] | rowIdx | is the row indices for the sparse array
  [in] | colIdx | is the column indices for the sparse array
  [in] | stype | is the storage format of the sparse array

Returns
  AF_SUCCESS if the execution completes properly

## ◆ af_create_sparse_array_from_dense()

AFAPI af_err af_create_sparse_array_from_dense | ( | af_array * | out,
|  | const af_array | dense,
|  | const af_storage | stype )

This function converts a dense af_array into a sparse array.

Parameters

  [out] | out | af_array for the sparse array with the given storage type
  [in] | dense | is the source dense matrix
  [in] | stype | is the storage format of the sparse array

Returns
  AF_SUCCESS if the execution completes properly

## ◆ af_create_sparse_array_from_ptr()

AFAPI af_err af_create_sparse_array_from_ptr | ( | af_array * | out,
|  | const dim_t | nRows,
|  | const dim_t | nCols,
|  | const dim_t | nNZ,
|  | const void *const | values,
|  | const int *const | rowIdx,
|  | const int *const | colIdx,
|  | const af_dtype | type,
|  | const af_storage | stype,
|  | const af_source | src )

This function converts host or device arrays of values, row indices and column indices into a sparse array on the device.

Note
  The rules for deep copy/shallow copy/reference are the same as for creating a regular af::array.

Parameters

  [out] | out | af::array for the sparse array
  [in] | nRows | is the number of rows in the dense matrix
  [in] | nCols | is the number of columns in the dense matrix
  [in] | nNZ | is the number of non zero elements in the dense matrix
  [in] | values | is the host array containing the non-zero elements of the matrix
  [in] | rowIdx | is the row indices for the sparse array
  [in] | colIdx | is the column indices for the sparse array
  [in] | type | is the data type for the matrix
  [in] | stype | is the storage format of the sparse array
  [in] | src | is afHost if inputs are host arrays and afDevice if the arrays are device arrays.

Returns
  AF_SUCCESS if the execution completes properly

## ◆ sparse() [1/3]

AFAPI array sparse | ( | const array | dense,
|  | const af::storage | stype = AF_STORAGE_CSR )

This function converts a dense af::array into a sparse array.

Parameters

  [in] | dense | is the source dense matrix
  [in] | stype | is the storage format of the sparse array

Returns
  af::array for the sparse array with the given storage type

// dense
// 0 0 0 0
// 5 8 0 0
// 0 0 3 0
// 0 6 0 0
// Convert dense af::array to its sparse (CSR) representation.
array sparse = af::sparse(dense, AF_STORAGE_CSR);
// sparse
// values: [ 5.0, 8.0, 3.0, 6.0 ]
// row_ptr: [ 0, 0, 2, 3, 4 ]
// col_idx: [ 0, 1, 2, 1 ]

## ◆ sparse() [2/3]

AFAPI array sparse | ( | const dim_t | nRows,
|  | const dim_t | nCols,
|  | const array | values,
|  | const array | rowIdx,
|  | const array | colIdx,
|  | const af::storage | stype = AF_STORAGE_CSR )

This function converts af::array of values, row indices and column indices into a sparse array.

Note
  This function only create references of these arrays into the sparse data structure and does not do deep copies.

Parameters

  [in] | nRows | is the number of rows in the dense matrix
  [in] | nCols | is the number of columns in the dense matrix
  [in] | values | is the af::array containing the non-zero elements of the matrix
  [in] | rowIdx | is the row indices for the sparse array
  [in] | colIdx | is the column indices for the sparse array
  [in] | stype | is the storage format of the sparse array

Returns
  af::array for the sparse array

float v[] = {5, 8, 3, 6};
int r[] = {0, 0, 2, 3, 4};
int c[] = {0, 1, 2, 1};
const int M = 4, N = 4, nnz = 4;
array vals = array(dim4(nnz), v);
array row_ptr = array(dim4(M + 1), r);
array col_idx = array(dim4(nnz), c);
// Create sparse array (CSR) from af::arrays containing values,
// row pointers, and column indices.
array sparse = af::sparse(M, N, vals, row_ptr, col_idx, AF_STORAGE_CSR);
// sparse
// values: [ 5.0, 8.0, 3.0, 6.0 ]
// row_ptr: [ 0, 0, 2, 3, 4 ]
// col_idx: [ 0, 1, 2, 1 ]

## ◆ sparse() [3/3]

AFAPI array sparse | ( | const dim_t | nRows,
|  | const dim_t | nCols,
|  | const dim_t | nNZ,
|  | const void *const | values,
|  | const int *const | rowIdx,
|  | const int *const | colIdx,
|  | const dtype | type = f32,
|  | const af::storage | stype = AF_STORAGE_CSR,
|  | const af::source | src = afHost )

This function converts host or device arrays of values, row indices and column indices into a sparse array on the device.

Note
  The rules for deep copy/shallow copy/reference are the same as for creating a regular af::array.

Parameters

  [in] | nRows | is the number of rows in the dense matrix
  [in] | nCols | is the number of columns in the dense matrix
  [in] | nNZ | is the number of non zero elements in the dense matrix
  [in] | values | is the host array containing the non-zero elements of the matrix
  [in] | rowIdx | is the row indices for the sparse array
  [in] | colIdx | is the column indices for the sparse array
  [in] | type | is the data type for the matrix
  [in] | stype | is the storage format of the sparse array
  [in] | src | is afHost if inputs are host arrays and afDevice if the arrays are device arrays.

Returns
  af::array for the sparse array

float vals[] = {5, 8, 3, 6};
int row_ptr[] = {0, 0, 2, 3, 4};
int col_idx[] = {0, 1, 2, 1};
const int M = 4, N = 4, nnz = 4;
// Create sparse array (CSR) from host pointers to values, row
// pointers, and column indices.
array sparse = af::sparse(M, N, nnz, vals, row_ptr, col_idx, f32,
AF_STORAGE_CSR, afHost);
// sparse
// values: [ 5.0, 8.0, 3.0, 6.0 ]
// row_ptr: [ 0, 0, 2, 3, 4 ]
// col_idx: [ 0, 1, 2, 1 ]