matrix.h

Initialization

Matrix slap_MatrixFromArray(int rows, int cols, sfloat *data)

Wraps existing data in a Matrix class.

This is the most common way to “create” a matrix. Typical usage will look something like this:

// Stack-allocated memory
sfloat data_stack[24];
Matrix A = slap_MatrixFromArray(6, 4, data_stack);

// Heap-allocated memory
sfloat *data_heap = (sfloat*)malloc(24 * sizeof(sfloat));
Matrix B = slap_MatrixFromArray(6, 4, data_heap);
free(data_heap);

Parameters:

rows – Number of rows in the matrix
cols – Number of columns in the matrix
data – Data for the matrix. Must not be NULL, and should have at least rows * cols elements.

Returns:

A new matrix

static inline Matrix slap_NullMatrix(void)

Create a “Null” matrix.

Useful for default initialization of the matrix where the data it wraps hasn’t been specified or allocated yet. Can check if a matrix is in this state using slap_IsNull().

Example

Matrix A = slap_NullMatrix();

Boolean Checks

static inline bool slap_IsTransposed(Matrix mat)

Check if matrix is transposed.

Matrices are transposed by setting a flag that flips the indexing operations. You can have two Matrix instances that point to the same data, where one is transposed and the other is not. You can use this method to check whether a matrix is transposed.

Dimensions

static inline uint16_t slap_MinDim(Matrix mat)

Returns the smallest dimension.

Parameters:: mat – [in] Any matrix
Returns:: Smaller of the number of rows and columns

static inline int slap_NumRows(Matrix mat)

Get the number of rows.

Parameters:: mat – [in] Any matrix
Returns:: Number of rows

static inline int slap_NumCols(Matrix mat)

Get the number of columns.

Parameters:: mat – [in] Any matrix
Returns:: Number of columns

static inline int slap_NumElements(const Matrix mat)

Get the number of elements in a matrix, i.e. m * n.

Parameters:: mat – Any matrix
Returns:: Number of elements in the matrix

static inline int slap_Stride(const Matrix mat)

Get the column-stride stride of the matrix.

This is the distance in memory between adjacent elements of the same row. For a “Dense” slap matrix where all elements are contiguous in memory, the stride is equal to the number of rows.

Indexing

static inline int slap_Cart2Index(const Matrix mat, int row, int col)

Get the linear index for a given row and column in the matrix.

Converts a cartesian index of row and column into a linear index for accessing an element of the underlying data.

Supports both strided and dense matrices.

Parameters:

mat – Matrix with nonzero size and initialized data
row – Row index
col – Column index

Returns:

Linear index corresponding to row and col. Returns -1 for a bad input.

void slap_Linear2Cart(Matrix mat, int k, int *row, int *col)

Converts a linear index to a Cartesian index.

This is moderately expensive, since it relies on modulus and division operations.

Passing null pointers to row and col results in undefined behavior, since this method does not check that these are valid.

Parameters:

mat – [in] Any matrix
k – [in] Linear index, from 0 to slap_NumElements()
row – [out] Destination for row index
col – [out] Destination for column index

static inline int slap_Linear2Index(const Matrix mat, int k)

Converts a linear index to the index into the underlying array.

If the matrix is Dense (stored contiguously in memory, see slap_IsDense()), the output is the same as the input. This method is most helpful for strided matrices.

Note that for strided arrays, this method is fairly expensive since it converts the linear index into a Cartesian index, and then to the array index.

Parameters:

mat – A dense or strided matrix
k – The linear index, ranging from 0 to slap_NumElements()

Returns:

The index into mat.data corresponding the kth element of mat

static inline bool slap_CheckInbounds(Matrix mat, int row, int col)

Check if the row and column index is in the bounds of the matrix.

Parameters:

mat – Matrix to be indexed
row – Row index
col – Column index

Returns:

true if the row and column index is in bounds for the matrix

static inline sfloat *slap_GetElement(Matrix mat, int row, int col)

Get a pointer to matrix element given row, column indices.

Note that this method does NOT perform any bounds checking so can be used unsafely! Passing an index that is out of bounds is undefined behavior.

Example

The following gets a pointer to the 1st element in the 2nd column, and then modifies it.

sfloat *x = slap_GetElement(A, 0, 1);
*x = 10;

To get the data directly, just de-reference the pointer at the call site: The following reads the data in the 2nd element of the 1st column.

sfloat y = *slap_GetElement(A, 1, 0);

Parameters:

mat – Matrix of nonzero size
row – Row index
col – Column index

Returns:

A pointer to the element of the matrix. NULL for invalid input.

static inline const sfloat *slap_GetElementConst(const Matrix mat, int row, int col)

Get a const pointer to matrix element given row, column indices.

Example

The following gets a pointer to the 1st element in the 2nd column.

const sfloat *x = slap_GetElementConst(A, 0, 1);

To get the data directly, just de-reference the pointer at the call site: The following reads the data in the 2nd element of the 1st column.

sfloat y = *slap_GetElementConst(A, 1, 0);

Parameters:

mat – Matrix of nonzero size
row – Row index
col – Column index

Returns:

A pointer to the element of the matrix. NULL for invalid input.

static inline void slap_SetElement(Matrix mat, int row, int col, sfloat val)

Set an matrix element to a given value.

This is a low-level function with no error checking. As such, it should be used carefully, as it can easily result in undefined behavior.

The user should make sure the indices are within bounds and that the data pointer is valid.

Example

Set the 1st element of the 2nd column to 10.1;

slap_SetElement(A, 0, 1, 10.1);

Parameters:

mat – Matrix with nonzero size and initialized data
row – Row index
col – Column index
val – Value to which the element should be set

Transformations

Matrix slap_Flatten(Matrix mat)

Flatten a 2D matrix to a column vector.

Changes the row and column data so that the matrix is now a column vector. The underlying data is unchanged.