BeBOP Optimized Sparse Kernel Interface Library  1.0.1h
Functions
module.c File Reference

Compressed sparse row (CSR) module. More...

#include <math.h>
#include <string.h>
#include <oski/config.h>
#include <oski/common.h>
#include <oski/matrix.h>
#include <oski/CSR/module.h>

Functions

const char * oski_GetShortDesc (void)
 Method: Returns a short string description of the module.
const char * oski_GetLongDesc (void)
 Method: Returns a "long" string description of the module.
void oski_InitModule (void)
 Method: Initialize the module.
void oski_CloseModule (void)
 Method: Shutdown the module.
static int CopyPointers (oski_matCSR_t *A, oski_copymode_t mode, oski_index_t *ptr, oski_index_t *ind, oski_value_t *val, oski_index_t m, oski_index_t index_base)
 Copy raw CSR representation to a concrete CSR matrix type representation.
static oski_index_t CountDiagElems (const oski_index_t *ptr, const oski_index_t *ind, oski_index_t m, oski_index_t b)
 Returns the number of explicitly stored diagonal elements.
static void SetCommonProps (oski_matcommon_t *out_props, const oski_index_t *ptr, const oski_index_t *ind, oski_index_t m, oski_index_t n, const oski_inmatpropset_t *props)
 Translate asserted properties of the input matrix into common properties of the output matrix.
static void SetMatTypeProps (oski_matCSR_t *A_csr, const oski_matcommon_t *out_props, const oski_inmatpropset_t *props)
 Set CSR properties based on common properties and asserted input matrix properties.
oski_matCSR_toski_WrapCSR (oski_matcommon_t *out_props, oski_index_t *Aptr, oski_index_t *Aind, oski_value_t *Aval, oski_index_t num_rows, oski_index_t num_cols, oski_inmatpropset_t *props, oski_copymode_t mode)
 This routine wraps a oski_matCSR_t data structure around an existing, pre-assembled raw CSR 3-array representation.
void oski_DestroyMatRepr (void *mat)
 Frees the given oski_matCSR_t object.
void * oski_CreateMatReprFromCSR (const oski_matCSR_t *mat, const oski_matcommon_t *props,...)
 Method: Instantiate from an existing CSR representation.
oski_matCSR_toski_ConvertMatReprToCSR (const void *mat, const oski_matcommon_t *props)
 Method: Convert to CSR format.
void * oski_CopyMatRepr (const void *mat, const oski_matcommon_t *props)
 Method: Duplicate a matrix representation.
double oski_StreamMatRepr (const void *mat, const oski_matcommon_t *props)
 Stream through a matrix.
void oski_ChangeIndexBase (oski_matCSR_t *A, const oski_matcommon_t *props, const oski_index_t new_base)
 Change the index base of a matrix.
double oski_CalcMatRepr1Norm (const void *mat, const oski_matcommon_t *props)
 Method: Compute the 1-norm.
oski_index_t oski_CountZeroRowsCSR (const oski_matCSR_t *A, const oski_matcommon_t *props)
 Returns the number of rows in a given CSR matrix that contain no structural non-zeros.

Detailed Description

Compressed sparse row (CSR) module.


Function Documentation

static int CopyPointers ( oski_matCSR_t A,
oski_copymode_t  mode,
oski_index_t *  ptr,
oski_index_t *  ind,
oski_value_t *  val,
oski_index_t  m,
oski_index_t  index_base 
) [static]

Copy raw CSR representation to a concrete CSR matrix type representation.

Parameters:
[out]AConcrete CSR object.
[in]modeCopy mode.
[in]mNumber of rows in the raw representation.
[in]ptrRow pointers of the raw representation.
[in]indColumn indices of the raw representation.
[in]valNon-zero values of the raw representation.
[in]index_baseBase index for interpreting the values in ptr and ind.
Returns:
1 if successful, 0 otherwise.
Precondition:
All pointers are non-NULL.
The raw representation is valid.
m is valid (non-negative).

References COPY_INPUTMAT, oski_matCSR_t::ind, oski_matCSR_t::is_shared, oski_CopyMem, oski_Free, oski_Malloc, oski_matCSR_t::ptr, SHARE_INPUTMAT, and oski_matCSR_t::val.

Referenced by oski_CreateMatReprFromCSR(), and oski_WrapCSR().

double oski_CalcMatRepr1Norm ( const void *  mat,
const oski_matcommon_t props 
)

Method: Compute the 1-norm.

Parameters:
[in]matMatrix type-specific representation.
[in]propsAdditional global properties of mat.
Returns:
The 1-norm, or -1 on error.
See also:
oski_CalcMat1Norm, oski_CalcMatRepr1Norm_funcpt
Todo:
Fix the symmetric case; this is only an estimate.

References _IM, _RE, oski_matCSR_t::base_index, oski_matcommon_t::is_herm, oski_matCSR_t::is_lower, oski_matcommon_t::is_symm, oski_matCSR_t::is_upper, oski_matcommon_t::num_rows, oski_matcommon_t::pattern, oski_matCSR_t::ptr, oski_matCSR_t::stored, oski_matCSR_t::val, and VAL_ASSIGN.

double oski_StreamMatRepr ( const void *  mat,
const oski_matcommon_t props 
)

Stream through a matrix.

This routine streams through the matrix data structure, performs some dummy computations, and returns the results. We use this routine to help estimate the cost of a matrix-vector multiply operation on a given matrix without actually having to perform matrix-vector multiply.

References _IM, _RE, oski_matCSR_t::base_index, oski_matCSR_t::ind, oski_matcommon_t::num_rows, oski_matCSR_t::ptr, and oski_matCSR_t::val.

oski_matCSR_t* oski_WrapCSR ( oski_matcommon_t out_props,
oski_index_t *  Aptr,
oski_index_t *  Aind,
oski_value_t *  Aval,
oski_index_t  num_rows,
oski_index_t  num_cols,
oski_inmatpropset_t props,
oski_copymode_t  mode 
)

This routine wraps a oski_matCSR_t data structure around an existing, pre-assembled raw CSR 3-array representation.

Create a new CSR-specific wrapper around a raw CSR array representation.

If any of the asserted properties can be strengthened, then the parameter props (below) is changed accordingly. See oski_CheckCSR() for details.

Parameters:
[out]out_propsMatrix type-independent properties, derived from the input properties props.
[in]AptrRow pointers.
[in]AindColumn indices.
[in]AvalNon-zero values.
[in,out]propsSemantic properties of the matrix represented by
[in]num_rowsNumber of rows.
[in]num_colsNumber of columns. Aptr, Aind, and Aval.
[in]modeSpecify the copy mode for the returned representation.
Precondition:
All pointer arguments are non-NULL
num_rows, num_cols are non-negative
mode is a legal value.
See also:
oski_wrapCSR_funcpt
Returns:
A matrix type-specific representation of the input matrix, or NULL on error.
Todo:
The output properties data structure actually defines a more general property about the diagonal, namely, that it is all ones. However, the available input matrix properties only allow the user to specify whether or not there is an implicit unit diagonal. Thus, it is possible that the user could create an input matrix with an explicit unit diagonal, but this condition is not checked when wrapping the data structure. It might be desirable to do this to make optimized triangular solve for the unit diagonal case more efficient.
Todo:
Similarly, the oski_matCSR_t data structure has "is_upper" and "is_lower" flags, which could be set even if the user asserts that the matrix has a "general" pattern.

Basic steps:

  1. Check asserted properties.
  2. Create a CSR handle.
  3. Copy buffers (deep or shallow copy, depending on mode)
  4. Set common properties.
  5. Set matrix-specific properties.
  6. Return.

References CopyPointers(), oski_matCSR_t::has_sorted_indices, oski_inmatpropset_t::index_base, oski_matCSR_t::is_shared, oski_matcommon_t::num_rows, oski_Malloc, oski_PrintDebugMessage(), SetCommonProps(), and SetMatTypeProps().

static void SetCommonProps ( oski_matcommon_t out_props,
const oski_index_t *  ptr,
const oski_index_t *  ind,
oski_index_t  m,
oski_index_t  n,
const oski_inmatpropset_t props 
) [static]

Translate asserted properties of the input matrix into common properties of the output matrix.

Parameters:
[out]out_propsOutput matrix common properties.
[in]ptrRow pointers.
[in]indColumn indices.
[in]mNumber of logical rows.
[in]nNumber of logical columns.
[in]propsAsserted input matrix properties.
Precondition:
All input matrix properties are valid and pointers are non-NULL.
Postcondition:
Sets all fields of out_props.

References CountDiagElems(), oski_matcommon_t::has_unit_diag, oski_inmatpropset_t::has_unit_diag_implicit, oski_inmatpropset_t::index_base, oski_matcommon_t::is_herm, oski_matcommon_t::is_symm, oski_matcommon_t::is_tri_lower, oski_matcommon_t::is_tri_upper, MAT_GENERAL, MAT_HERM_FULL, MAT_HERM_LOWER, MAT_HERM_UPPER, MAT_SYMM_FULL, MAT_SYMM_LOWER, MAT_SYMM_UPPER, MAT_TRI_LOWER, MAT_TRI_UPPER, oski_matcommon_t::num_cols, oski_matcommon_t::num_nonzeros, oski_matcommon_t::num_rows, OSKI_MIN, oski_matcommon_t::pattern, and oski_inmatpropset_t::pattern.

Referenced by oski_WrapCSR().

static void SetMatTypeProps ( oski_matCSR_t A_csr,
const oski_matcommon_t out_props,
const oski_inmatpropset_t props 
) [static]

Set CSR properties based on common properties and asserted input matrix properties.

Parameters:
[in,out]A_csrA CSR representation whose properties have not yet been initialized.
[in]out_propsCommon properties of the final output matrix which A_csr will represent.
[in]propsAsserted properties of the final output matrix which A_csr will represent.

This implementation does not set A_csr->is_shared, which is instead set in CopyPointers().

See also:
CopyPointers()

References oski_matCSR_t::base_index, oski_inmatpropset_t::has_sorted_indices, oski_matCSR_t::has_sorted_indices, oski_inmatpropset_t::has_unit_diag_implicit, oski_matCSR_t::has_unit_diag_implicit, oski_inmatpropset_t::index_base, oski_matCSR_t::is_lower, oski_matCSR_t::is_upper, MAT_GENERAL, MAT_HERM_FULL, MAT_HERM_LOWER, MAT_HERM_UPPER, MAT_SYMM_FULL, MAT_SYMM_LOWER, MAT_SYMM_UPPER, MAT_TRI_LOWER, MAT_TRI_UPPER, oski_inmatpropset_t::pattern, and oski_matCSR_t::stored.

Referenced by oski_WrapCSR().