Description

functions for masic matrix manipulation

Data Structures
struct	rc_matrix_t
	Struct containing the state of a matrix and a pointer to dynamically allocated memory to hold its contents. More...

Macros
#define	RC_MATRIX_INITIALIZER

Typedefs
typedef struct rc_matrix_t	rc_matrix_t
	Struct containing the state of a matrix and a pointer to dynamically allocated memory to hold its contents. More...

Functions
rc_matrix_t	rc_matrix_empty (void)
	Returns an rc_matrix_t with no allocated memory and the initialized flag set to 0. More...

int	rc_matrix_alloc (rc_matrix_t *A, int rows, int cols)
	Allocates memory for matrix A to have size rows&cols. More...

int	rc_matrix_free (rc_matrix_t *A)
	Frees the memory allocated for a matrix A. More...

int	rc_matrix_zeros (rc_matrix_t *A, int rows, int cols)
	Resizes matrix A and allocates memory for a matrix with specified rows & columns. The new memory is pre-filled with zeros using calloc. Any existing memory allocated for A is freed if necessary to avoid memory leaks. More...

int	rc_matrix_identity (rc_matrix_t *A, int dim)
	Resizes A to be a square identity matrix with dimensions dim-by-dim. More...

int	rc_matrix_random (rc_matrix_t *A, int rows, int cols)
	Generates a matrix populated with random numbers between -1 and 1. More...

int	rc_matrix_diagonal (rc_matrix_t *A, rc_vector_t v)
	Generates a diagonal matrix with the elements of specified vector v. More...

int	rc_matrix_duplicate (rc_matrix_t A, rc_matrix_t *B)
	Duplicates the contents of matrix A and into matrix B. More...

int	rc_matrix_print (rc_matrix_t A)
	Prints the contents of matrix A to stdout in decimal notation with 4 decimal places. More...

int	rc_matrix_print_sci (rc_matrix_t A)
	Prints the contents of matrix A to stdout in scientific notation. More...

int	rc_matrix_zero_out (rc_matrix_t *A)
	Sets all values of an already-allocated matrix to 0. More...

int	rc_matrix_times_scalar (rc_matrix_t *A, double s)
	Multiplies every entry in A by scalar value s. More...

int	rc_matrix_multiply (rc_matrix_t A, rc_matrix_t B, rc_matrix_t *C)
	Multiplies A*B=C. More...

int	rc_matrix_left_multiply_inplace (rc_matrix_t A, rc_matrix_t *B)
	Multiplies A*B and puts the result back in the place of B. More...

int	rc_matrix_right_multiply_inplace (rc_matrix_t *A, rc_matrix_t B)
	Multiplies A*B and puts the result back in the place of A. More...

int	rc_matrix_add (rc_matrix_t A, rc_matrix_t B, rc_matrix_t *C)
	Adds matrices A+B and places the result in C. More...

int	rc_matrix_add_inplace (rc_matrix_t *A, rc_matrix_t B)
	Adds matrix A to B and places the result back in A. More...

int	rc_matrix_subtract_inplace (rc_matrix_t *A, rc_matrix_t B)
	Subtracts matrix B from A and leaves the result in A. More...

int	rc_matrix_transpose (rc_matrix_t A, rc_matrix_t *T)
	Transposes the contents of A and places the result in T. More...

int	rc_matrix_transpose_inplace (rc_matrix_t *A)
	Transposes matrix A in place. More...

int	rc_matrix_times_col_vec (rc_matrix_t A, rc_vector_t v, rc_vector_t *c)
	Multiplies matrix A times column vector v and places the result in column vector c. More...

int	rc_matrix_row_vec_times_matrix (rc_vector_t v, rc_matrix_t A, rc_vector_t *c)
	Multiplies row vector v times matrix A and places the result in row vector c. More...

int	rc_matrix_outer_product (rc_vector_t v1, rc_vector_t v2, rc_matrix_t *A)
	Computes v1 times v2 where v1 is a column vector and v2 is a row vector. More...

double	rc_matrix_determinant (rc_matrix_t A)
	Calculates the determinant of square matrix A. More...

int	rc_matrix_symmetrize (rc_matrix_t *P)
	Symmetrizes a square matrix. More...

Macro Definition Documentation

◆ RC_MATRIX_INITIALIZER

#define RC_MATRIX_INITIALIZER

Value:

{\
        .rows = 0,\
        .cols = 0,\
        .d = NULL,\
        .initialized = 0}

Examples:: rc_altitude.c, rc_benchmark_algebra.c, rc_test_algebra.c, rc_test_kalman.c, and rc_test_matrix.c.

Function Documentation

◆ rc_matrix_empty()

rc_matrix_t rc_matrix_empty ( void )

Returns an rc_matrix_t with no allocated memory and the initialized flag set to 0.

This is essential for initializing rc_matrix_t structs when they are declared since local variables declared in a function without global variable scope in C are not guaranteed to be zeroed out which can lead to bad memory pointers and segfaults if not handled carefully. We recommend initializing all matrices with this before using rc_matrix_alloc or any other function.

Returns: Returns an empty rc_matrix_t

◆ rc_matrix_alloc()

int rc_matrix_alloc	(	rc_matrix_t *	A,
		int	rows,
		int	cols
	)

Allocates memory for matrix A to have size rows&cols.

If A is initially the right size, nothing is done and the data in A is preserved. If A is uninitialized or of the wrong size then any existing memory is freed and new memory is allocated, helping to prevent accidental memory leaks. The contents of the new matrix is not guaranteed to be anything in particular as the memory is allocated with malloc. Will only be unsuccessful if rows&cols are invalid or there is insufficient memory available.

Parameters

	A	Pointer to user's matrix struct
[in]	rows	number of rows
[in]	cols	number of columns

Returns: 0 on success, -1 on failure.

Examples:: rc_benchmark_algebra.c.

◆ rc_matrix_free()

int rc_matrix_free ( rc_matrix_t * A )

Frees the memory allocated for a matrix A.

Also sets the dimensions and initialized flag to 0 to indicate to other functions that A no longer points to allocated memory and cannot be used until more memory is allocated such as with rc_matrix_alloc or rc_matrix_zeros. Will only fail and return -1 if it is passed a NULL pointer.

Parameters

A	Pointer to user's matrix struct

Returns: 0 on success, -1 on failure.

Examples:: rc_test_algebra.c, and rc_test_kalman.c.

◆ rc_matrix_zeros()

int rc_matrix_zeros	(	rc_matrix_t *	A,
		int	rows,
		int	cols
	)

Resizes matrix A and allocates memory for a matrix with specified rows & columns. The new memory is pre-filled with zeros using calloc. Any existing memory allocated for A is freed if necessary to avoid memory leaks.

Parameters

	A	Pointer to user's matrix struct
[in]	rows	number of rows
[in]	cols	number of columns

Returns: 0 on success, -1 on failure.

Examples:: rc_altitude.c, rc_test_kalman.c, and rc_test_matrix.c.

◆ rc_matrix_identity()

int rc_matrix_identity	(	rc_matrix_t *	A,
		int	dim
	)

Resizes A to be a square identity matrix with dimensions dim-by-dim.

Any existing memory allocated for A is freed if necessary to avoid memory leaks before new memory is allocated for the specified dimension.

Parameters

	A	Pointer to user's matrix struct
[in]	dim	The dimension of one side of square matrix

Returns: 0 on success, -1 on failure.

Examples:: rc_test_matrix.c.

◆ rc_matrix_random()

int rc_matrix_random	(	rc_matrix_t *	A,
		int	rows,
		int	cols
	)

Generates a matrix populated with random numbers between -1 and 1.

Resizes A to be a matrix with the specified number of rows and columns and populates the new memory with random numbers evenly distributed between -1.0 and 1.0. Any existing memory allocated for A is freed if necessary to avoid memory leaks.

Parameters

	A	Pointer to user's matrix struct
[in]	rows	number of rows
[in]	cols	number of columns

Returns: 0 on success, -1 on failure.

Examples:: rc_benchmark_algebra.c, rc_test_algebra.c, and rc_test_matrix.c.

◆ rc_matrix_diagonal()

int rc_matrix_diagonal	(	rc_matrix_t *	A,
		rc_vector_t	v
	)

Generates a diagonal matrix with the elements of specified vector v.

Resizes A to be a square matrix with the same number of rows and columns as vector v's length. The diagonal entries of A are then populated with the contents of v and the off-diagonal entries are set to 0. The original contents of A are freed to avoid memory leaks.

Parameters

	A	Pointer to user's matrix struct
[in]	v	vector of diagonal entries

Returns: 0 on success, -1 on failure.

Examples:: rc_test_matrix.c.

◆ rc_matrix_duplicate()

int rc_matrix_duplicate	(	rc_matrix_t	A,
		rc_matrix_t *	B
	)

Duplicates the contents of matrix A and into matrix B.

If B is already the right size then its contents are overwritten. If B is unallocated or is of the wrong size then the memory is freed and new memory is allocated to hold the duplicate of A.

Parameters

[in]	A	Matrix to be duplicated
[out]	B	new matrix

Returns: 0 on success, -1 on failure.

Examples:: rc_benchmark_algebra.c, and rc_test_matrix.c.

◆ rc_matrix_print()

int rc_matrix_print ( rc_matrix_t A )

Prints the contents of matrix A to stdout in decimal notation with 4 decimal places.

Not recommended for very large matrices as rows will typically linewrap if the terminal window is not wide enough.

Parameters

[in] A Matrix to print

Returns: 0 on success, -1 on failure.

Examples:: rc_test_algebra.c, and rc_test_matrix.c.

◆ rc_matrix_print_sci()

int rc_matrix_print_sci ( rc_matrix_t A )

Prints the contents of matrix A to stdout in scientific notation.

Prints 4 significant figures. Not recommended for very large matrices as rows will typically linewrap if the terminal window is not wide enough.

Parameters

[in] A Matrix to print

Returns: 0 on success, -1 on failure.

Examples:: rc_test_matrix.c.

◆ rc_matrix_zero_out()

int rc_matrix_zero_out ( rc_matrix_t * A )

Sets all values of an already-allocated matrix to 0.

Parameters

A	pointer to matrix to be zero'd out

Returns: 0 on success, -1 on failure.

◆ rc_matrix_times_scalar()

int rc_matrix_times_scalar	(	rc_matrix_t *	A,
		double	s
	)

Multiplies every entry in A by scalar value s.

It is not strictly necessary for A to be provided as a pointer since a copy of the struct A would also contain the correct pointer to the original matrix's allocated memory. However, in this library we use the convention of passing an rc_vector_t struct or rc_matrix_t struct as a pointer when its data is to be modified by the function, and as a normal argument when it is only to be read by the function.

Parameters

	A	Matrix to be modified
[in]	s	scalar to multiply by

Returns: Returns 0 on success or -1 on failure.

Examples:: rc_test_matrix.c.

◆ rc_matrix_multiply()

int rc_matrix_multiply	(	rc_matrix_t	A,
		rc_matrix_t	B,
		rc_matrix_t *	C
	)

Multiplies A*B=C.

C is resized and its original contents are freed if necessary to avoid memory leaks.

Parameters

[in]	A	first input
[in]	B	second input
[out]	C	result

Returns: Returns 0 on success or -1 on failure.

Examples:: rc_benchmark_algebra.c, rc_test_algebra.c, and rc_test_matrix.c.

◆ rc_matrix_left_multiply_inplace()

int rc_matrix_left_multiply_inplace	(	rc_matrix_t	A,
		rc_matrix_t *	B
	)

Multiplies A*B and puts the result back in the place of B.

B is resized and its original contents are freed if necessary to avoid memory leaks.

Parameters

[in]	A	left matrix in the multiplication
	B	right matrix in the multiplication and holder of the result.

Returns: Returns 0 on success or -1 on failure.

Examples:: rc_test_matrix.c.

◆ rc_matrix_right_multiply_inplace()

int rc_matrix_right_multiply_inplace	(	rc_matrix_t *	A,
		rc_matrix_t	B
	)

Multiplies A*B and puts the result back in the place of A.

A is resized and its original contents are freed if necessary to avoid memory leaks.

Parameters

	A	left matrix in the multiplication and holder of result
[in]	B	right matrix in the multiplication

Returns: Returns 0 on success or -1 on failure.

Examples:: rc_test_matrix.c.

◆ rc_matrix_add()

int rc_matrix_add	(	rc_matrix_t	A,
		rc_matrix_t	B,
		rc_matrix_t *	C
	)

Adds matrices A+B and places the result in C.

The original contents of C are safely freed if necessary to avoid memory leaks. Use rc_matrix_add_inplace if you do not need to keep the contents of one of these matrices after addition.

Parameters

[in]	A	First matrix
[in]	B	second matrix
[out]	C	result

Returns: Returns 0 on success or -1 on failure.

Examples:: rc_test_matrix.c.

◆ rc_matrix_add_inplace()

int rc_matrix_add_inplace	(	rc_matrix_t *	A,
		rc_matrix_t	B
	)

Adds matrix A to B and places the result back in A.

The original contents of A are lost. Use rc_matrix_add if you wish to keep the contents of both matrix A and B after addition.

Parameters

	A	First matrix for addition and holder of the result
[in]	B	Second matrix for addition

Returns: Returns 0 on success or -1 on failure.

Examples:: rc_test_matrix.c.

◆ rc_matrix_subtract_inplace()

int rc_matrix_subtract_inplace	(	rc_matrix_t *	A,
		rc_matrix_t	B
	)

Subtracts matrix B from A and leaves the result in A.

The original contents of A are lost.

Parameters

	A	First matrix for subtraction and holder of the result
[in]	B	Second matrix for subtraction

Returns: Returns 0 on success or -1 on failure.

◆ rc_matrix_transpose()

int rc_matrix_transpose	(	rc_matrix_t	A,
		rc_matrix_t *	T
	)

Transposes the contents of A and places the result in T.

Resizes matrix T to hold the transposed contents of A and leaves A untouched. Original contents of T are safely freed and lost. If the original contents of A are not needed after transposing then use rc_matrix_transpose_inplace instead.

Parameters

[in]	A	input matrix struct
[out]	T	resulting transpose

Returns: Returns 0 on success or -1 on failure.

Examples:: rc_test_matrix.c.

◆ rc_matrix_transpose_inplace()

int rc_matrix_transpose_inplace ( rc_matrix_t * A )

Transposes matrix A in place.

Use as an alternative to rc_matrix_transpose if you no longer have need for the original contents of matrix A.

Parameters

A	Pointer to matrix to be transposed

Returns: Returns 0 on success or -1 on failure.

Examples:: rc_test_matrix.c.

◆ rc_matrix_times_col_vec()

int rc_matrix_times_col_vec	(	rc_matrix_t	A,
		rc_vector_t	v,
		rc_vector_t *	c
	)

Multiplies matrix A times column vector v and places the result in column vector c.

Any existing data in c is freed if necessary and c is resized appropriately. Vectors v and c are interpreted as column vectors, but nowhere in their definitions are they actually specified as one or the other.

Parameters

[in]	A	input matrix
[in]	v	input vector
[out]	c	output vector

Returns: Returns 0 on success or -1 on failure.

Examples:: rc_test_matrix.c.

◆ rc_matrix_row_vec_times_matrix()

int rc_matrix_row_vec_times_matrix	(	rc_vector_t	v,
		rc_matrix_t	A,
		rc_vector_t *	c
	)

Multiplies row vector v times matrix A and places the result in row vector c.

Any existing data in c is freed if necessary and c is resized appropriately. Vectors v and c are interpreted as row vectors, but nowhere in their definitions are they actually specified as one or the other.

Parameters

[in]	v	input vector
[in]	A	input matrix
[out]	c	output vector

Returns: Returns 0 on success or -1 on failure.

Examples:: rc_test_matrix.c.

◆ rc_matrix_outer_product()

int rc_matrix_outer_product	(	rc_vector_t	v1,
		rc_vector_t	v2,
		rc_matrix_t *	A
	)

Computes v1 times v2 where v1 is a column vector and v2 is a row vector.

Parameters

[in]	v1	Column vector v1
[in]	v2	Row vector v2
	A	Output matrix

Returns: Returns 0 on success or -1 on failure.

Examples:: rc_test_matrix.c.

◆ rc_matrix_determinant()

double rc_matrix_determinant ( rc_matrix_t A )

Calculates the determinant of square matrix A.

Parameters

[in] A input matrix

Returns: Returns the determinant or prints error message and returns -1.0f of error.

Examples:: rc_benchmark_algebra.c, and rc_test_matrix.c.

◆ rc_matrix_symmetrize()

int rc_matrix_symmetrize ( rc_matrix_t * P )

Symmetrizes a square matrix.

P_sym = (P+P^T)/2

Parameters

P	pointer to matrix to symmetrize

Returns: 0 on success, -1 on failure

Description

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ RC_MATRIX_INITIALIZER

Function Documentation

◆ rc_matrix_empty()

◆ rc_matrix_alloc()

◆ rc_matrix_free()

◆ rc_matrix_zeros()

◆ rc_matrix_identity()

◆ rc_matrix_random()

◆ rc_matrix_diagonal()

◆ rc_matrix_duplicate()

◆ rc_matrix_print()

◆ rc_matrix_print_sci()

◆ rc_matrix_zero_out()

◆ rc_matrix_times_scalar()

◆ rc_matrix_multiply()

◆ rc_matrix_left_multiply_inplace()

◆ rc_matrix_right_multiply_inplace()

◆ rc_matrix_add()

◆ rc_matrix_add_inplace()

◆ rc_matrix_subtract_inplace()

◆ rc_matrix_transpose()

◆ rc_matrix_transpose_inplace()

◆ rc_matrix_times_col_vec()

◆ rc_matrix_row_vec_times_matrix()

◆ rc_matrix_outer_product()

◆ rc_matrix_determinant()

◆ rc_matrix_symmetrize()