μLAPack

Micro Linear Algebra Package

Pronounced: mu la pack

A small linear algebra package to compute various matrix/vector operations. The library is optimized to work on microcontrollers and embedded environments, but can be used anywhere C can be compiled.

Features

All μLAPack functions are "safe" in that the matrix/vector operations are checked for initialization and mathematic dimensional legality before an operation takes place. The library contains various operations and manipulations that can be configured to your needs. The library can be configured to run safely in even the most constrained environments where memory allocation is a concern.

Included Functionality

μLAPack contains functionality to assist in your matrix math needs for feedback control, statistical analysis, data processing, filtering, estimation, basic algebraic computation, and machine learning.

Library Specific Functions

Initialize a matrix/vector object - ulapack_initialize
Print a matrix/vector to an output file stream - ulapack_print
Free dynamically allocated matrix/vector memory - ulapack_destroy
Safely edit a matrix/vector element - ulapack_edit_entry
Safely modify a matrix/vector element - ulapack_get_entry
Query an object to see if it is a vector - ulapack_is_vector
Copy the contents of a matrix or vector - ulapack_copy
Copy data from an array to a matrix column - ulapack_array_col_copy
Copy data from an array to a matrix row - ulapack_array_row_copy

Basic Matrix/Vector Operations

Get the size of a matrix or vector - ulapack_size
Check if two matrices or vectors are equal in value - ulapack_is_equal

Arithmetic

Sum the elements of a matrix or vector - ulapack_sum
Add two matrices or vectors - ulapack_add
Subtract two matrices or vectors - ulapack_subtract
Take the trace of a matrix - ulapack_trace
Take the product of two matrices or vectors - ulapack_product
Take the inner product of two vectors - ulapack_dot
Take the norm of a vector or Frobenius norm of a matrix - ulapack_norm
Find the determinant of a Matrix - ulapack_det
Scale a matrix or vector by a scalar - ulapack_scale

Manipulations

Put a vector on the diagonal of a matrix - ulapack_diag
Set a square matrix to the identity matrix - ulapack_eye
Safely set the entirety of matrix/vector to a single value - ulapack_set
Take the transpose of a matrix or vector - ulapack_transpose
Take the inverse of a matrix - ulapack_inverse
Take the pseudo inverse of a matrix - ulapack_pinverse

Advanced Operations

Decompose a matrix into LU triangular matrices - ulapack_lu
Create a Vandermonde matrix from a vector - ulapack_vandermonde
Compute the least squares of a matrix/system - ulapack_least_squares
Fit an nth degree polynomial - ulapack_polyfit
Decompose a matrix via Singular Value Decomposition (SVD) - ulapack_svd
Compute a score matrix via Principle Component Analysis (PCA) - ulapack_pca

Options

Compile time options can be set in either the file ulapack_options.h or in a build/make system. The user of μLAPack can make the following considerations while using the library.

Static Memory Allocation

The user of this library has the option of only using static memory allocation. This option is most suitable in embedded environments that can not dynamically allocate memory because of safety concerns with calls to alloc and because of time critical requirements. The macro ULAPACK_USE_STATIC_ALLOC must be #defined at compile time in order to use the static memory allocation feature. The static allocation technique relies on using overhead memory in the static matrix memory allocation. Due to this technique, the maximum possible row and column dimensions of any matrix object must be explicitly defined at compile time via the macros: ULAPACK_MAX_MATRIX_N_ROWS and ULAPACK_MAX_MATRIX_N_COLS. Any matrix initialized after compile time can not exceed the dimensions defined by the macros, and an error will be returned upon initialization if this is attempted.

Dynamic Memory Allocation

Define ULAPACK_USE_DYNAMIC_ALLOC to specify using dynamic memory allocation for all objects.

Choose Your Entry Container Type

The user of this library has the option of setting the matrix/vector element data type to a desired type via the ULAPACK_MATRIX_ENTRY_TYPE #define. It is recommended that a primitive floating point type is used. ULAPACK_MATRIX_ENTRY_TYPE is set to double by default, and is typedefed to MatrixEntry_t in the source code. MINIMUM_THRESHOLD_TOLERANCE defines the threshold floating point limit for a 0.

Clear Upon Initialization

All new matrix/vector objects made can be initialized to zeros if ULAPACK_INITIALIZE_MEMORY is defined at compile time.

Matrix Inversion Options

Define ULAPACK_INVERSE_VIA_LU to use LU decomposition for matrix inversions.

Allocator/Freer Options

If dynamic memory allocation is used, the memory allocator and freer can be configured via the macros ULAPACK_ALLOC and ULAPACK_FREE.

Unit Tests

μLAPack was developed using test-driven practices. The unit tests and Makefile for building and running the unit tests are in the test/ directory. To test static memory allocation run make ulapack_test_static. To unit test the dynamically allocated methods, run make ulapack_test_dynamic. To run both tests, use make. valgrind ./ulapack_test_dynamic returns no memory leaks while using dynamic memory allocation.

Error Codes

The following error codes can be returned from the library functions. See the in-file documentation for the function to check its return codes of type MatrixError_t.

ulapack_error - general error code
ulapack_oom - out of memory error code
ulapack_invalid_argument - bad argument given to function
ulapack_uninit_obj - uninitialized object passed into function
ulapack_success - general success code

Usage

Include The Library

#include "ulapack.h"

Statically Allocated Matrix

An example of setting up and using μLAPack with static memory allocation turned on.

File: ulapack_options.h

#define ULAPACK_USE_STATIC_ALLOC // switch on static allocation
#define ULAPACK_MAX_MATRIX_N_ROWS (10u) // set maximum matrix rows possible to 10
#define ULAPACK_MAX_MATRIX_N_COLS (10u) // set maximum matrix cols possible to 10

File: another_c_file.c

#include "ulapack.h"

...

Matrix_t A; // declare a matrix object with name A
ulapack_initialize_matrix(&A, 3u, 3u); // initialize the matrix with size 3X3
ulapack_eye(&A); // set the matrix A equal to the 3X3 identity matrix
ulapack_scale(&A, 3, &A); // scale the matrix A by 3

ulapack_print(&A, stdout);

Output:

[ 3 0 0 ]
[ 0 3 0 ]
[ 0 0 3 ]

Dynamically Allocated Matrix

An example of setting up and using μLAPack with static memory allocation turned on.

File: ulapack_options.h

#define ULAPACK_USE_DYNAMIC_ALLOC // switch on dynamic allocation

File: a_c_file.c

#include "ulapack.h"

...

Matrix_t *A; // declare a matrix object pointer with name A
ulapack_initialize_matrix(&A, 3u, 3u); // initialize the matrix with size 3X3
ulapack_eye(A); // set the matrix A equal to the 3X3 identity matrix
ulapack_scale(A, 3, A); // scale the matrix A by 3

ulapack_print(A, stdout);

Output:

[ 3 0 0 ]
[ 0 3 0 ]
[ 0 0 3 ]

Examples

Navigate to the examples/ directory for code samples using μLAPack.

An example of using μLAPack for Principle Component Analysis (PCA).

#include "ulapack.h"

int main(void) {

    const double Adata[10][8] = {{0.4170, 0.4192, 0.8007, 0.0983, 0.9889, 0.0194, 0.1023, 0.9034},
                                {0.7203, 0.6852, 0.9683, 0.4211, 0.7482, 0.6788, 0.4141, 0.1375},
                                {0.0001, 0.2045, 0.3134, 0.9579, 0.2804, 0.2116, 0.6944, 0.1393},
                                {0.3023, 0.8781, 0.6923, 0.5332, 0.7893, 0.2655, 0.4142, 0.8074},
                                {0.1468, 0.0274, 0.8764, 0.6919, 0.1032, 0.4916, 0.0500, 0.3977},
                                {0.0923, 0.6705, 0.8946, 0.3155, 0.4479, 0.0534, 0.5359, 0.1654},
                                {0.1863, 0.4173, 0.0850, 0.6865, 0.9086, 0.5741, 0.6638, 0.9275},
                                {0.3456, 0.5587, 0.0391, 0.8346, 0.2936, 0.1467, 0.5149, 0.3478},
                                {0.3968, 0.1404, 0.1698, 0.0183, 0.2878, 0.5893, 0.9446, 0.7508},
                                {0.5388, 0.1981, 0.8781, 0.7501, 0.1300, 0.6998, 0.5866, 0.7260}};

    Matrix_t A;
    Matrix_t T;

    ulapack_init(&A, 10, 8);
    ulapack_init(&T, 10, 10);

    /*
     * Copy data points into vector objects.
     */
    for (uint64_t row_itor = 0; row_itor < 10; row_itor++) {
        for (uint64_t col_itor = 0; col_itor < 8; col_itor++) {
            ulapack_edit_entry(&A, 
            row_itor, col_itor, 
            Adata[row_itor][col_itor]);
        }
    }

    ulapack_pca(&A, &T);
}

An example using μLAPack for polynomial regression.

#include "ulapack.h"

int main(void) {
    /*
     * Fit 10 data points.
     */
    const uint64_t data_points = 10;

    /*
     * Fit to the 2nd degree.
     */
    const uint64_t fit_degree = 2;

    const double xdata[] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
    /*
     * x^2 + noise
     */
    const double ydata[] = {0.679196, 3.215585, 
                            8.635037, 16.117271, 
                            25.174340, 35.784344, 
                            48.847389, 64.033688, 
                            81.458282, 101.281631};

    /*
     * Declare vector objects for data points.
     */
    Matrix_t x;
    Matrix_t y;

    /*
     * Declare vector object for coefficients.
     */
    Matrix_t p;

    /*
     * Initialize vector objects.
     */
    ulapack_init(&x, data_points, 1);
    ulapack_init(&y, data_points, 1);

    ulapack_init(&p, fit_degree + 1, 1);

    /*
     * Copy data points into vector objects.
     */
    for (uint64_t row_itor = 0; row_itor < data_points; row_itor++) {
        ulapack_edit_entry(&x, 
            row_itor, 0, 
            xdata[row_itor]);

        ulapack_edit_entry(&y, 
            row_itor, 0, 
            ydata[row_itor]);
    }

    /*
     * Run the regression.
     */
    ulapack_polyfit(&x, &y, fit_degree, &p);
}

Requirements

The libc math.h library is required for a square root operation in the ulapack_norm and ulapack_svd functions. To avoid the use of additional cmath library calls, the math.h pow() function was rewritten as a private function.

Licensing & Support

μLAPack and any derivative works of μLAPack (and embedded_lapack) are free to use for personal and/or educational use without profit and for development purposes in your project(s) to verify if μLAPack is right for you.

For commercial use (with redistribution rights): Fill out the licensing inquiry form, and I will promptly reply with a response and proposed license agreement.

Refer to the LICENSE document for licensing details.

Legacy

μLAPack is a fork of my now deprecated embedded_lapack library. μLAPack includes definitions for both static and dynamic memory allocation, safer type definitions, more explicit and safer error code status, Doxygen, more functionality, and more compiler support when compared to embedded_lapack.

TODO

find occurrences and indices of a value in a matrix/vector - ulapack_find
take the pseudo inverse of a matrix via SVD (good for poorly conditioned matrix inversions)
grab a sub-matrix from a matrix/vector (similar to the : operator in MATLAB) - ulapack_copy_submatrix
take the cross product of two vector - ulapack_cross
write an element square root function to avoid any math libc calls
make a skew symmetric matrix - ulapack_skew
make a Kalman extension package μKalman with:
- model propagation
- Kalman gain matrix calculations using μLAPack

Have a suggestion for a new feature/function? File an issue in this repository with your requests.

sargisyonan / ulapack Goto Github PK

ulapack's Introduction