Robot Control Library

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 prefilled 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 dimbydim. 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 alreadyallocated 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...  
#define RC_MATRIX_INITIALIZER 
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.
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.
A  Pointer to user's matrix struct  
[in]  rows  number of rows 
[in]  cols  number of columns 
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.
A  Pointer to user's matrix struct 
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 prefilled with zeros using calloc. Any existing memory allocated for A is freed if necessary to avoid memory leaks.
A  Pointer to user's matrix struct  
[in]  rows  number of rows 
[in]  cols  number of columns 
int rc_matrix_identity  (  rc_matrix_t *  A, 
int  dim  
) 
Resizes A to be a square identity matrix with dimensions dimbydim.
Any existing memory allocated for A is freed if necessary to avoid memory leaks before new memory is allocated for the specified dimension.
A  Pointer to user's matrix struct  
[in]  dim  The dimension of one side of square matrix 
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.
A  Pointer to user's matrix struct  
[in]  rows  number of rows 
[in]  cols  number of columns 
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 offdiagonal entries are set to 0. The original contents of A are freed to avoid memory leaks.
A  Pointer to user's matrix struct  
[in]  v  vector of diagonal entries 
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.
[in]  A  Matrix to be duplicated 
[out]  B  new matrix 
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.
[in]  A  Matrix to print 
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.
[in]  A  Matrix to print 
int rc_matrix_zero_out  (  rc_matrix_t *  A  ) 
Sets all values of an alreadyallocated matrix to 0.
A  pointer to matrix to be zero'd out 
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.
A  Matrix to be modified  
[in]  s  scalar to multiply by 
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.
[in]  A  first input 
[in]  B  second input 
[out]  C  result 
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.
[in]  A  left matrix in the multiplication 
B  right matrix in the multiplication and holder of the result. 
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.
A  left matrix in the multiplication and holder of result  
[in]  B  right matrix in the multiplication 
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.
[in]  A  First matrix 
[in]  B  second matrix 
[out]  C  result 
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.
A  First matrix for addition and holder of the result  
[in]  B  Second matrix for addition 
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.
A  First matrix for subtraction and holder of the result  
[in]  B  Second matrix for subtraction 
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.
[in]  A  input matrix struct 
[out]  T  resulting transpose 
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.
A  Pointer to matrix to be transposed 
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.
[in]  A  input matrix 
[in]  v  input vector 
[out]  c  output vector 
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.
[in]  v  input vector 
[in]  A  input matrix 
[out]  c  output vector 
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.
[in]  v1  Column vector v1 
[in]  v2  Row vector v2 
A  Output matrix 
double rc_matrix_determinant  (  rc_matrix_t  A  ) 
Calculates the determinant of square matrix A.
[in]  A  input matrix 
int rc_matrix_symmetrize  (  rc_matrix_t *  P  ) 
Symmetrizes a square matrix.
P_sym = (P+P^T)/2
P  pointer to matrix to symmetrize 