la.h File Reference

A simple linear algebra library header. More...

#include <stddef.h>
#include <assert.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>

Include dependency graph for la.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	la_matrix
	Structure representing a matrix. More...

Macros
#define	la_matrix_element(matrix, row, col)    (matrix).data[(row) * (matrix).stride + (col)]
	Macro to access elements of the matrix.
#define	la_matrix_print(matrix)    la_matrix_fprint((matrix), #matrix, 6, 3, stdout)
	Print the contents of a matrix to standard output with a default precision.

Typedefs
typedef struct la_matrix	la_matrix
	Structure representing a matrix.

Functions
void	la_matrix_add (la_matrix a, la_matrix b, la_matrix result)
	Add two matrices element-wise and store the result in a third matrix.
la_matrix	la_matrix_alloc (size_t rows, size_t cols)
	Allocate memory for a matrix.
void	la_matrix_apply_function (la_matrix dest, la_matrix src, double(*f)(double))
	Apply a function to each element of the source matrix and store the result in the destination matrix.
void	la_matrix_copy (la_matrix dest, la_matrix src)
	Copy the contents of one matrix to another matrix.
void	la_matrix_fill (la_matrix matrix, double value)
	Fill a matrix with a specific value.
void	la_matrix_fprint (la_matrix matrix, char *name, int precision, int digits_before_dot, FILE *fp)
	Print the contents of a matrix to a file with a specified precision.
void	la_matrix_fprint_simul (la_matrix *matrices, char **names, size_t n, int precision, int digits_before_dot, FILE *fp)
	Print the contents of multiple matrices to a file with a specified precision.
void	la_matrix_free (la_matrix matrix)
	Free memory for a matrix.
void	la_matrix_get_max_index (la_matrix src, size_t *x, size_t *y)
	Get the indices of the maximum element in the matrix.
void	la_matrix_get_min_index (la_matrix src, size_t *x, size_t *y)
	Get the indices of the minimum element in the matrix.
void	la_matrix_multiply (la_matrix a, la_matrix b, la_matrix result)
	Multiply two matrices and store the result in a third matrix.
void	la_matrix_multiply_by_const (la_matrix src, const double x)
	Multiply all elements of the matrix by a constant.
void	la_matrix_rand (la_matrix matrix, double minvalue, double maxvalue)
	Fill a matrix with random values within a specified range.
void	la_matrix_subtract (la_matrix a, la_matrix b, la_matrix result)
	Subtract two matrices element-wise and store the result in a third matrix.
double	la_matrix_sum (la_matrix src)
	Calculate the sum of all elements in the matrix.
void	la_matrix_sum_rows (la_matrix dest, la_matrix src)
	Calculate the sum of elements in each row of the source matrix and store the result in the destination matrix.
void	la_matrix_T_copy (la_matrix dest, la_matrix src)
	Copy the transpose of the source matrix to the destination matrix.
la_matrix	la_submatrix (la_matrix src, size_t row_start, size_t col_start, size_t new_rows, size_t new_cols)
	Extract a submatrix from a given matrix.

Detailed Description

A simple linear algebra library header.

This file contains the declarations of functions and structures used for basic linear algebra operations such as matrix and vector operations. The implementations of these functions are included in the compiled library lib/libla.so.

Definition in file la.h.

Macro Definition Documentation

la_matrix_element

#define la_matrix_element	(		matrix,
			row,
			col )    (matrix).data[(row) * (matrix).stride + (col)]

Macro to access elements of the matrix.

Example usage:

#include "la.h"
 
int main() {
    la_matrix matrix = la_matrix_alloc(3, 3);
    la_matrix_fill(matrix, 5.0);
 
    // Access element at row 1, column 2
    double value = la_matrix_element(matrix, 1, 2);
    printf("Element at (1, 2): %f\n", value); // Output should be 5.0
 
    la_matrix_free(matrix);
    return 0;
}

Parameters

matrix	The matrix.
row	The row index.
col	The column index.

Returns

The element at the specified row and column.

Definition at line 53 of file la.h.

#define la_matrix_element(matrix, row, col) \
  (matrix).data[(row) * (matrix).stride + (col)]

la_matrix_print

#define la_matrix_print

(

matrix

)

la_matrix_fprint((matrix), #matrix, 6, 3, stdout)

Print the contents of a matrix to standard output with a default precision.

Example usage:

#include "la.h"
 
int main() {
    la_matrix matrix = la_matrix_alloc(3, 3);
    la_matrix_fill(matrix, 2.718);
 
    // Print the matrix to standard output
    la_matrix_print(matrix);
 
    la_matrix_free(matrix);
    return 0;
}

Parameters

matrix

The matrix to print.

Definition at line 475 of file la.h.

#define la_matrix_print(matrix) \
  la_matrix_fprint((matrix), #matrix, 6, 3, stdout)

Typedef Documentation

la_matrix

typedef struct la_matrix la_matrix

Structure representing a matrix.

Function Documentation

la_matrix_add()

void la_matrix_add	(	la_matrix	a,
		la_matrix	b,
		la_matrix	result )

Add two matrices element-wise and store the result in a third matrix.

The operation performed can be mathematically represented as:

\[ C_{i,j} = A_{i,j} + B_{i,j} \]

for all valid indices \( i \) and \( j \) where \( 0 \leq i < \text{rows} \) and \( 0 \leq j < \text{cols} \).

Example usage:

#include "la.h"
 
int main() {
    la_matrix a = la_matrix_alloc(2, 2);
    la_matrix_fill(a, 2.0);
    la_matrix b = la_matrix_alloc(2, 2);
    la_matrix_fill(b, 3.0);
 
    la_matrix result = la_matrix_alloc(2, 2);
    la_matrix_add(a, b, result);
 
    // Print the result to verify
    la_matrix_print(result);
 
    la_matrix_free(a);
    la_matrix_free(b);
    la_matrix_free(result);
    return 0;
}

Parameters

a	The first matrix.
b	The second matrix.
result	The matrix to store the result.

la_matrix_alloc()

la_matrix la_matrix_alloc	(	size_t	rows,
		size_t	cols )

Allocate memory for a matrix.

Example usage:

#include "la.h"
 
int main() {
    // Allocate a 4x4 matrix
    la_matrix matrix = la_matrix_alloc(4, 4);
 
    // Use the matrix...
 
    // Free the allocated matrix
    la_matrix_free(matrix);
    return 0;
}

Parameters

rows	Number of rows in the matrix.
cols	Number of columns in the matrix.

Returns

A matrix with allocated memory.

la_matrix_apply_function()

void la_matrix_apply_function	(	la_matrix	dest,
		la_matrix	src,
		double(*)(double)	f )

Apply a function to each element of the source matrix and store the result in the destination matrix.

This function applies a given function \( f \) to each element of the source matrix \( \text{src} \) and stores the result in the corresponding element of the destination matrix \( \text{dest} \). The function \( f \) is a pointer to a function that takes a double as input and returns a double as output.

The operation performed can be mathematically represented as:

\[ \text{dest}_{i,j} = f\left(\text{src}_{i,j}\right) \]

for all valid indices \( i \) and \( j \) where \( 0 \leq i < \text{rows} \) and \( 0 \leq j < \text{cols} \).

Example usage:

#include "la.h"
 
double calc_function_square(double x) { return x * x; }
 
int main()
{
  la_matrix src = la_matrix_alloc(3, 3);
  la_matrix_rand(src, 1.0, 2.0);
  la_matrix dest = la_matrix_alloc(3, 3);
  la_matrix_apply_function(dest, src, calc_function_square);
  la_matrix_print(dest);
  return 0;
}

Results:

┌[dest]                                 ┐
│   +3.386291    +1.944304    +3.179443 │
│   +3.234387    +3.654396    +1.434129 │
│   +1.782820    +3.126636    +1.632708 │
└                                [/dest]┘

Parameters

dest	The destination matrix where the results will be stored.
src	The source matrix whose elements will be processed.
f	Pointer to the function which should be applied to each element.

la_matrix_copy()

void la_matrix_copy	(	la_matrix	dest,
		la_matrix	src )

Copy the contents of one matrix to another matrix.

The operation performed can be mathematically represented as:

\[ \text{dest}_{i,j} = \text{src}_{i,j} \]

for all valid indices \( i \) and \( j \) where \( 0 \leq i < \text{rows} \) and \( 0 \leq j < \text{cols} \).

This function performs a straightforward element-wise copy from the source matrix to the destination matrix. The destination matrix must have the same dimensions as the source matrix.

Example usage:

#include "la.h"
 
int main()
{
  // Allocate and initialize source matrix
  la_matrix src = la_matrix_alloc(3, 3);
  la_matrix_fill(src, 5.0);
 
  // Allocate destination matrix
  la_matrix dest = la_matrix_alloc(3, 3);
 
  // Copy contents of src to dest
  la_matrix_copy(dest, src);
 
  // Print the destination matrix to verify the copy
  la_matrix_print(dest);
 
  // Free allocated matrices
  la_matrix_free(src);
  la_matrix_free(dest);
 
  return 0;
}

Expected output:

┌[dest]                                 ┐
│   +5.000000    +5.000000    +5.000000 │
│   +5.000000    +5.000000    +5.000000 │
│   +5.000000    +5.000000    +5.000000 │
└                                [/dest]┘

Parameters

src	The source matrix.
dest	The destination matrix.

la_matrix_fill()

void la_matrix_fill	(	la_matrix	matrix,
		double	value )

Fill a matrix with a specific value.

The operation performed can be mathematically represented as:

\[ C_{i,j} = \text{value} \]

for all valid indices \( i \) and \( j \) where \( 0 \leq i < \text{rows} \) and \( 0 \leq j < \text{cols} \).

Example usage:

#include "la.h"
 
int main() {
    la_matrix matrix = la_matrix_alloc(2, 3);
    la_matrix_fill(matrix, 3.14);
 
    // Print the matrix to verify
    la_matrix_print(matrix);
 
    la_matrix_free(matrix);
    return 0;
}

Parameters

matrix	The matrix to fill.
value	The value to fill the matrix with.

la_matrix_fprint()

void la_matrix_fprint	(	la_matrix	matrix,
		char *	name,
		int	precision,
		int	digits_before_dot,
		FILE *	fp )

Print the contents of a matrix to a file with a specified precision.

Example usage:

#include "la.h"
 
int main() {
    la_matrix matrix = la_matrix_alloc(3, 3);
    la_matrix_rand(matrix, 0.0, 1.0);
 
    // Open a file to print the matrix
    FILE* fp = fopen("matrix.txt", "w");
    la_matrix_fprint(matrix, "matrix", 4, 2, fp);
    fclose(fp);
 
    la_matrix_free(matrix);
    return 0;
}

Parameters

matrix	The matrix to print.
name	The name of the matrix (used for display purposes).
precision	The number of decimal places to display.
digits_before_dot	The number of digits before the decimal dot. If it is set to 0, then scientific notation is used.
fp	The file pointer to print to.

la_matrix_fprint_simul()

void la_matrix_fprint_simul	(	la_matrix *	matrices,
		char **	names,
		size_t	n,
		int	precision,
		int	digits_before_dot,
		FILE *	fp )

Print the contents of multiple matrices to a file with a specified precision.

Example usage:

#include "la.h"
 
int main() {
    la_matrix matrices[2];
    matrices[0] = la_matrix_alloc(2, 2);
    matrices[1] = la_matrix_alloc(2, 2);
    la_matrix_fill(matrices[0], 1.0);
    la_matrix_fill(matrices[1], 2.0);
 
    char* names[2] = { "matrix1", "matrix2" };
 
    la_matrix_fprint_simul(matrices, names, 2, 4, 2, stdout);
 
    la_matrix_free(matrices[0]);
    la_matrix_free(matrices[1]);
    return 0;
}

Parameters

matrices	Array of matrices to print.
names	Array of names corresponding to the matrices.
n	Number of matrices.
precision	The number of decimal places to display.
digits_before_dot	The number of digits before the decimal dot. If it is set to 0, then scientific notation is used.
fp	The file pointer to print to.

la_matrix_free()

void la_matrix_free

(

la_matrix

matrix

)

Free memory for a matrix.

Example usage:

#include "la.h"
 
int main() {
    la_matrix matrix = la_matrix_alloc(3, 3);
 
    // Use the matrix...
 
    // Free the allocated matrix
    la_matrix_free(matrix);
    return 0;
}

Parameters

matrix

A matrix with allocated memory.

la_matrix_get_max_index()

void la_matrix_get_max_index	(	la_matrix	src,
		size_t *	x,
		size_t *	y )

Get the indices of the maximum element in the matrix.

This function finds the indices of the maximum element in the given matrix and stores them in the provided pointers.

Example usage:

la_matrix matrix = la_matrix_alloc(3, 3);
la_matrix_fill(matrix, 1.0);
la_matrix_element(matrix, 1, 1) = 5.0;
size_t x, y;
la_matrix_get_max_index(matrix, &x, &y);
printf("Max element at (%zu, %zu)\n", x, y);

Parameters

src	The source matrix.
x	Pointer to store the row index of the maximum element.
y	Pointer to store the column index of the maximum element.

la_matrix_get_min_index()

void la_matrix_get_min_index	(	la_matrix	src,
		size_t *	x,
		size_t *	y )

Get the indices of the minimum element in the matrix.

This function finds the indices of the minimum element in the given matrix and stores them in the provided pointers.

Example usage:

la_matrix matrix = la_matrix_alloc(3, 3);
la_matrix_fill(matrix, 5.0);
la_matrix_element(matrix, 1, 1) = 1.0;
size_t x, y;
la_matrix_get_min_index(matrix, &x, &y);
printf("Min element at (%zu, %zu)\n", x, y);

Parameters

src	The source matrix.
x	Pointer to store the row index of the minimum element.
y	Pointer to store the column index of the minimum element.

la_matrix_multiply()

void la_matrix_multiply	(	la_matrix	a,
		la_matrix	b,
		la_matrix	result )

Multiply two matrices and store the result in a third matrix.

This function multiplies two matrices \( A \) and \( B \) and stores the result in matrix \( C \). The matrices must be compatible for multiplication, meaning the number of columns in \( A \) must equal the number of rows in \( B \). The result matrix \( C \) must have dimensions equal to the number of rows in \( A \) and the number of columns in \( B \).

The matrix multiplication is performed as follows:

\[ C_{i,j} = \sum_{k=1}^{n} A_{i,k} \cdot B_{k,j} \]

where \( A \) is an \( m \times n \) matrix, \( B \) is an \( n \times p \) matrix, and \( C \) is an \( m \times p \) matrix. Here, \( i \) ranges from 1 to \( m \) and \( j \) ranges from 1 to \( p \).

Example usage:

#include "la.h"
 
int main() {
    la_matrix A = la_matrix_alloc(2, 3);  // 2x3 matrix
    la_matrix_fill(A, 1.0);
    la_matrix B = la_matrix_alloc(3, 2);  // 3x2 matrix
    la_matrix_fill(B, 2.0);
 
    la_matrix C = la_matrix_alloc(2, 2);  // Resultant 2x2 matrix
    la_matrix_multiply(A, B, C);
 
    // Print the result to verify
    la_matrix_print(C);
 
    la_matrix_free(A);
    la_matrix_free(B);
    la_matrix_free(C);
    return 0;
}

Parameters

a	The first matrix.
b	The second matrix.
result	The matrix to store the result.

la_matrix_multiply_by_const()

void la_matrix_multiply_by_const	(	la_matrix	src,
		const double	x )

Multiply all elements of the matrix by a constant.

This function multiplies each element of the given matrix by a specified constant.

The operation performed can be mathematically represented as:

\[ \text{src}_{i,j} = \text{src}_{i,j} \times x \]

for all valid indices \( i \) and \( j \) where \( 0 \leq i < \text{rows} \) and \( 0 \leq j < \text{cols} \).

Example usage:

la_matrix matrix = la_matrix_alloc(3, 3);
la_matrix_fill(matrix, 1.0);
la_matrix_multiply_by_const(matrix, 2.0);
la_matrix_print(matrix);

Parameters

src	The matrix whose elements will be multiplied.
x	The constant value to multiply each element by.

la_matrix_rand()

void la_matrix_rand	(	la_matrix	matrix,
		double	minvalue,
		double	maxvalue )

Fill a matrix with random values within a specified range.

The operation performed can be mathematically represented as:

\[ C_{i,j} = R\]

where \( R \) is a random number such as \( \text{minvalue} \leq R \leq \text{maxvalue}\) for all valid indices \( i \) and \( j \) where \( 0 \leq i < \text{rows} \) and \( 0 \leq j < \text{cols} \).

Example usage:

#include "la.h"
 
int main() {
    la_matrix matrix = la_matrix_alloc(3, 3);
    la_matrix_rand(matrix, 0.0, 1.0);
 
    // Print the matrix to verify
    la_matrix_print(matrix);
 
    la_matrix_free(matrix);
    return 0;
}

Parameters

matrix	The matrix to fill.
minvalue	The minimum value for the random range.
maxvalue	The maximum value for the random range.

la_matrix_subtract()

void la_matrix_subtract	(	la_matrix	a,
		la_matrix	b,
		la_matrix	result )

Subtract two matrices element-wise and store the result in a third matrix.

The operation performed can be mathematically represented as:

\[ C_{i,j} = A_{i,j} - B_{i,j} \]

for all valid indices \( i \) and \( j \) where \( 0 \leq i < \text{rows} \) and \( 0 \leq j < \text{cols} \).

Example usage:

#include "la.h"
 
int main() {
    la_matrix a = la_matrix_alloc(2, 2);
    la_matrix_fill(a, 5.0);
    la_matrix b = la_matrix_alloc(2, 2);
    la_matrix_fill(b, 3.0);
 
    la_matrix result = la_matrix_alloc(2, 2);
    la_matrix_subtract(a, b, result);
 
    // Print the result to verify
    la_matrix_print(result);
 
    la_matrix_free(a);
    la_matrix_free(b);
    la_matrix_free(result);
    return 0;
}

Parameters

a	The first matrix.
b	The second matrix.
result	The matrix to store the result.

la_matrix_sum()

double la_matrix_sum

(

la_matrix

src

)

Calculate the sum of all elements in the matrix.

This function computes the sum of all the elements in the given matrix.

The operation performed can be mathematically represented as:

\[ \text{sum} = \sum_{i=0}^{\text{rows}-1} \sum_{j=0}^{\text{cols}-1} \text{src}_{i,j} \]

where \( \text{src} \) is the source matrix.

Example usage:

la_matrix matrix = la_matrix_alloc(3, 3);
la_matrix_fill(matrix, 1.0);
double sum = la_matrix_sum(matrix);
printf("Sum of all elements: %f\n", sum);

Parameters

src	The source matrix.

Returns

The sum of all elements in the matrix.

la_matrix_sum_rows()

void la_matrix_sum_rows	(	la_matrix	dest,
		la_matrix	src )

Calculate the sum of elements in each row of the source matrix and store the result in the destination matrix.

This function computes the sum of elements in each row of the given source matrix and stores the results in the corresponding row of the destination matrix.

The operation performed can be mathematically represented as:

\[ \text{dest}_{i,0} = \sum_{j=0}^{\text{cols}-1} \text{src}_{i,j} \]

for all valid indices \( i \) where \( 0 \leq i < \text{rows} \).

Example usage:

la_matrix src = la_matrix_alloc(3, 3);
la_matrix_fill(src, 1.0);
la_matrix dest = la_matrix_alloc(3, 1);
la_matrix_sum_rows(dest, src);
la_matrix_print(dest);

Parameters

dest	The destination matrix where the row sums will be stored.
src	The source matrix whose row elements will be summed.

la_matrix_T_copy()

void la_matrix_T_copy	(	la_matrix	dest,
		la_matrix	src )

Copy the transpose of the source matrix to the destination matrix.

The operation performed can be mathematically represented as:

\[ \text{dest}_{i,j} = \text{src}_{j,i} \]

for all valid indices \( i \) and \( j \) where \( 0 \leq i < \text{dest.rows} \) and \( 0 \leq j < \text{dest.cols} \).

This function effectively transposes the source matrix and copies the result to the destination matrix. The destination matrix must have dimensions equal to the transpose of the source matrix.

Example usage:

la_matrix src = la_matrix_alloc(2, 3);
la_matrix_fill(src, 1.0);
la_matrix dest = la_matrix_alloc(3, 2);
la_matrix_T_copy(dest, src);
la_matrix_print(dest);

Parameters

src	The source matrix.
dest	The destination matrix where the transposed elements will be stored.

la_submatrix()

la_matrix la_submatrix	(	la_matrix	src,
		size_t	row_start,
		size_t	col_start,
		size_t	new_rows,
		size_t	new_cols )

Extract a submatrix from a given matrix.

This function extracts a submatrix from the source matrix starting at the specified row and column indices, and with the specified number of rows and columns. The extracted submatrix shares the data with the source matrix, meaning it does not allocate new memory for the data, and any changes to the submatrix will affect the source matrix.

The operation can be mathematically represented as:

\[ \text{submatrix}_{i,j} = \text{src}_{i+\text{row_start},j+\text{col_start}} \]

for all valid indices \( i \) and \( j \) where \( 0 \leq i < \text{new_rows} \) and \( 0 \leq j < \text{new_cols} \).

Example usage:

#include "la.h"
 
int main()
{
  // Allocate and initialize source matrix
  la_matrix src = la_matrix_alloc(4, 4);
  la_matrix_fill(src, 1.0);
 
  // Extract a 2x2 submatrix starting from (1, 1)
  la_matrix submat = la_submatrix(src, 1, 1, 2, 2);
 
  // Print the submatrix to verify the extraction
  la_matrix_print(submat);
 
  // Free allocated matrices
  la_matrix_free(src);
 
  return 0;
}

Expected output:

┌[submat]                 ┐
│   +1.000000   +1.000000 │
│   +1.000000   +1.000000 │
└                [/submat]┘

Parameters

src	The source matrix.
row_start	The starting row index for the submatrix.
col_start	The starting column index for the submatrix.
new_rows	The number of rows in the submatrix.
new_cols	The number of columns in the submatrix.

Returns

The extracted submatrix.

Note

Do not use la_matrix_free on matrices created by la_submatrix, since the data is not reallocated but rather directly referenced.