Warning: This is no longer the latest available version of this module. Please see the releases page for the most recent version. The Webnucleo group strongly recommends the use of the latest version of any of its online modules.
Documentation from the file
Table of Contents
-
Structures
-
Routines
| Structures |
|---|
Name: WnMatrix__LineDescription: WnMatrix__Line is a structure for storing and managing row or column data in a WnMatrix. The content of the struct WnMatrix__Line is not made public by the API. |
|
|
Name: WnMatrixDescription: WnMatrix is a structure for storing and managing sparse matrix data. It provides functionality for easily adding and removing elements. The content of the struct WnMatrix is not made public by the API. |
|
|
| Routines |
|---|
Name: WnMatrix__Line__free()Description: Frees the memory allocated for a WnMatrix__Line structure. Syntax:
void WnMatrix__Line__free( WnMatrix__Line *self );
Input:
WnMatrix__Line__free( p_row );
|
|
|
Name: WnMatrix__Line__getNonZeroElements()Description: Routine to get an array containing the values of the non-zero elements in a row or of the non-zero elements in a column in a WnMatrix__Line structure. Syntax:
double *WnMatrix__Line__getNonZeroElements(
WnMatrix__Line *self
);
Input:
unsigned int i, *a_indices;
double *a_values;
WnMatrix__Line *p_row;
p_row = WnMatrix__getRow( p_my_matrix, 5 );
a_indices = WnMatrix__Line__getNonZeroIndices( p_row );
a_values = WnMatrix__Line__getNonZeroElements( p_row );
for(
i = 0;
i < WnMatrix__Line__getNumberOfElements( p_row );
i++
) {
printf( "%d %e\n", a_indices[i], a_elements[i] );
}
WnMatrix__Line__free( p_row );
|
|
|
Name: WnMatrix__Line__getNonZeroIndices()Description: Routine to get an array containing the column numbers of the non-zero elements in a row or the row numbers of the non-zero elements in a column in a WnMatrix__Line structure. Syntax:
unsigned int *WnMatrix__Line__getNonZeroIndices(
WnMatrix__Line *self
);
Input:
unsigned int i, *a_indices;
WnMatrix__Line *p_row;
p_row = WnMatrix__getRow( p_my_matrix, 5 );
a_indices = WnMatrix__Line__getNonZeroIndices( p_row );
for(
i = 0;
i < WnMatrix__Line__getNumberOfElements( p_row );
i++
) {
printf( "%d\n", a_indices[i] );
}
WnMatrix__Line__free( p_row );
|
|
|
Name: WnMatrix__Line__getNumberOfElements()Description: Routine to get the number of non-zero elements in a row or column in a WnMatrix structure. Syntax:
unsigned int WnMatrix__Line__getNumberOfElements(
WnMatrix__Line *self
);
Input:
printf(
"%d\n",
WnMatrix__getNumberOfElements(
WnMatrix__getRow( p_my_matrix, 3 )
)
);
|
|
|
Name: WnMatrix__addValueToDiagonals()Description: Adds a value to the diagonal elements of the matrix. Syntax:
void WnMatrix__addValueToDiagonals( WnMatrix *self, double d_val );
Input:
WnMatrix__addValueToDiagonals( p_matrix, 0.5 );
|
|
|
Name: WnMatrix__assignElement()Description: Assigns an element to a WnMatrix structure. If an element already exists at that (row,col), the new value is added to the existing value. Syntax:
void WnMatrix__assignElement(
WnMatrix *self, unsigned int i_row,
unsigned int i_col, double d_val
);
Input:
If a value did not previously exist at i_row and i_col in *self, the value there is now d_val. Otherwise, the value there is now the sum of the previous value and d_val. If the input matrix pointer or the row or column is invalid, error handling is invoked. Example: Assign the value 3.5 to row 1, column 2 of the matrix stored in WnMatrix * p_matrix:
unsigned int i_row = 1;
unsigned int i_col = 2;
double d_val = 3.5;
WnMatrix__assignElement( p_matrix, i_row, i_col, d_val );
|
|
|
Name: WnMatrix__clear()Description: Zeroes all the entries in a WnMatrix structure. Syntax:
void WnMatrix__clear( WnMatrix *self );
Input:
WnMatrix__clear( p_matrix );
|
|
|
Name: WnMatrix__extractMatrix()Description: Extracts a smaller WnMatrix from a larger one. Syntax:
WnMatrix *WnMatrix__extractMatrix( WnMatrix *self,
unsigned int i_row,
unsigned int i_col,
unsigned int i_row_offset,
unsigned int i_col_offset );
Input:
Routine returns a pointer to the new extracted matrix if the routine was successful. Routine does not free the input matrix, and the caller must free the memory for both the input matrix and the extracted matrix after use (with WnMatrix__free). If the input matrix is invalid, error handling is invoked. If the matrix to be extracted does not fully lie within the parent matrix or if sufficient memory could not be allocated, error handling is invoked. Example: Extract a 2x2 matrix from self beginning at row 3, column 5:
WnMatrix *p_extracted_matrix;
p_extracted_matrix =
WnMatrix__extractMatrix( self, 3, 5, 2, 2 );
|
|
|
Name: WnMatrix__free()Description: Frees the memory allocated for a WnMatrix structure. Syntax:
void WnMatrix__free( WnMatrix *self );
Input:
WnMatrix__free( p_matrix );
|
|
|
Name: WnMatrix__getColumn()Description: Routine to get a column from a WnMatrix structure. Syntax:
WnMatrix__Line *WnMatrix__getRow(
WnMatrix *self, unsigned int i_col
);
Input:
WnMatrix__Line *p_col;
p_col = WnMatrix__getColumn( p_my_matrix, 3 );
|
|
|
Name: WnMatrix__getCsrMatrix()Description: Converts a WnMatrix into Compressed Sparse Row format. Syntax:
void WnMatrix__getCsrMatrix(
WnMatrix *self, unsigned int a_rwptr[], unsigned int a_col[],
double a_val[]
);
Input:
a_rwptr = malloc(
( WnMatrix__getNumberOfRows( p_matrix ) + 1 ) * sizeof( unsigned int )
);
a_col = malloc(
( WnMatrix__getNumberOfElements( p_matrix ) ) * sizeof( unsigned int )
);
a_val = malloc(
( WnMatrix__getNumberOfElements( p_matrix ) ) * sizeof(double)
);
WnMatrix__getCsrMatrix( p_matrix, a_rwptr, a_col, a_val );
|
|
|
Name: WnMatrix__getDenseMatrix()Description: Stores the matrix in dense format in a doubly indexed array. Syntax:
double **WnMatrix__getDenseMatrix( WnMatrix *self );
Input:
Routine returns a new doubly-indexed array that contains the elements of WnMatrix *self stored in dense format. Routine does not free the input matrix. The user must free the memory for the dense matrix. Example: Store p_matrix in dense format in doubly indexed array a_mat:
double **a_mat;
a_mat = WnMatrix__getDenseMatrix( p_matrix );
... (do something with the matrix)
for( i = 0; i < WnMatrix__getNumberOfRows( p_matrix ); i++ ) {
free( a_mat[i] );
}
free( a_mat );
|
|
|
Name: WnMatrix__getDiagonalElements()Description: Stores the values of the diagonal elements in the double array passed into the function. Syntax:
double *WnMatrix__getDiagonalElements(
WnMatrix *self
);
Input:
On successful return, the routine returns a new double array of length equal to the number of rows in the matrix and containing the diagonal elements (including zeros) in order. The caller must free the memory for the returned array. Example: Stores the diagonal elements of WnMatrix *p_matrix in double[] a_diagonals :
double *a_diagonals;
a_diagonals = WnMatrix__getDiagonalElems( p_matrix );
|
|
|
Name: WnMatrix__getElement()Description: Retrieves the value of the specified matrix element. Syntax:
double WnMatrix__getElementi(
WnMatrix *self, unsigned int i_row, unsigned int i_col
);
Input:
Routine returns a double that is the value of the retrieved element. If the input matrix pointer or the row or column is invalid, error handling is invoked. Example: Retrieve the value val of the element at row 1, column 2 from the WnMatrix * p_my_matrix:
i_row = 1;
i_col = 2;
double val;
val = WnMatrix__getElement( p_my_matrix, i_row, i_col );
|
|
|
Name: WnMatrix__getMatrixTimesVector()Description: Computes the vector y from the equation y = Ax, given matrix A and vector x. Syntax:
void WnMatrix__getMatrixTimesVector(
WnMatrix *self, unsigned int i_vector_size, double a_vector_input[],
double a_vector_output[]
);
Input:
WnMatrix__getMatrixTimesVector( p_matrix, 100, a_in, a_out );
|
|
|
Name: WnMatrix__getNumberOfColumns()Description: Returns the number of columns in the matrix. Syntax:
unsigned int WnMatrix__getNumberOfColumns( WnMatrix *self );
Input:
Routine returns an unsigned int that contains the number of columns in *self. Example: Retrieve the number of columns from WnMatrix *p_matrix and store it in l_columns:
unsigned int i_columns;
i_columns = WnMatrix__getNumberOfColumns( p_matrix );
|
|
|
Name: WnMatrix__getNumberOfElements()Description: Returns the number of non-zero elements in the matrix. Syntax:
unsigned int WnMatrix__getNumberOfElements( WnMatrix *self );
Input:
Routine returns an unsigned int that contains the number of elements in *self. Example: Retrieve the number of elements in WnMatrix *p_matrix and store it in i_elements:
unsigned int i_elements;
i_elements = WnMatrix__getNumberOfElements( p_matrix );
|
|
|
Name: WnMatrix__getNumberOfRows()Description: Returns the number of rows in the matrix. Syntax:
unsigned int WnMatrix__getNumberOfRows( WnMatrix *self );
Input:
Routine returns an unsigned int that contains the number of rows in *self. Example: Retrieve the number of rows from WnMatrix *p_matrix and stores it in l_rows:
unsigned int i_rows;
i_rows = WnMatrix__getNumberOfRows( p_matrix );
|
|
|
Name: WnMatrix__getRow()Description: Routine to get a row from a WnMatrix structure. Syntax:
WnMatrix__Line *WnMatrix__getRow(
WnMatrix *self, unsigned int i_row
);
Input:
WnMatrix__Line *p_row;
p_row = WnMatrix__getRow( p_my_matrix, 5 );
|
|
|
Name: WnMatrix__getTransferMatrix()Description: Returns the F matrix ( Fij = aij/ajj, but no diagonal elements ). Syntax:
WnMatrix * WnMatrix__getTransferMatrix( WnMatrix *self );
Input:
For valid input, routine returns a new WnMatrix * that contains the transfer F matrix. Routine does not free the input matrix. Example: Retrieve the transfer matrix from WnMatrix *p_matrix and store it in WnMatrix *p_transfer_matrix:
p_transfer_matrix = WnMatrix__getTransferMatrix( p_matrix );
|
|
|
Name: WnMatrix__getTransposeMatrixTimesVector()Description: Computes the matrix equation Y = A(transpose)x given A and x. Syntax:
void WnMatrix__getTransposeMatrixTimesVector(
WnMatrix *self, unsigned int i_vector_size, double a_vector_input[],
double a_vector_output[]
);
Input:
WnMatrix__getTransposeMatrixTimesVector(
p_matrix, 100, a_in, a_out
);
|
|
|
Name: WnMatrix__getYaleSparseMatrix()Description: Stores the matrix in Yale Sparse format in the arrays passed into the function. Syntax:
void WnMatrix__getYaleSparseMatrix(
WnMatrix *self, int a_ija[], double a_sa[]
);
Input:
a_ija = malloc(
(
WnMatrix__getNumberOfElements(p_matrix) +
WnMatrix__getNumberOfRows(p_matrix) + 1
) * sizeof(int)
);
a_sa = malloc(
(
WnMatrix__getNumberOfElements(p_matrix) +
WnMatrix__getNumberOfRows(p_matrix) + 1
) * sizeof(double)
);
WnMatrix__getYaleSparseMatrix( matrix, a_ija, a_sa );
|
|
|
Name: WnMatrix__insertMatrix()Description: Inserts a smaller WnMatrix into a larger one. Syntax:
void WnMatrix__insertMatrix(
WnMatrix *self, WnMatrix *p_inserted_matrix,
unsigned int i_row, unsigned int i_col
);
Input:
Routine returns with the smaller matrix inserted into self. If a matrix element in the larger matrix already exists prior to insertion of the smaller matrix at a location where the smaller matrix will be added, the final element at that location will be the sum of the prior element and the element of the smaller matrix. If either matrix pointer is invalid, error handling is invoked. If the row or column of the insertion point is invalid, or if the inserted matrix would extend beyond the bounds of the final matrix, error handling is invoked. The routine does not free the inserted matrix.
WnMatrix__insertMatrix( self, p_inserted_matrix, 3, 5 );
|
|
|
Name: WnMatrix__new()Description: Initializes a WnMatrix structure. Syntax:
WnMatrix *WnMatrix__new(
unsigned int i_rows,
unsigned int i_columns
);
Input:
The routine returns a pointer to a struct WnMatrix containing the initialized matrix. The struct is initialized to contain the number of rows and columns specified by the input parameters. If the routine is unable to allocate memory for the structure, the routine returns NULL. Example: Initialize a matrix with 50 rows and 100 columns and return a reference p_matrix to it:
WnMatrix *p_matrix;
p_matrix = WnMatrix__new( 50, 100 );
|
|
|
Name: WnMatrix__removeElement()Description: Removes the specified matrix element from the matrix. Syntax:
int WnMatrix__removeElement(
WnMatrix *self, unsigned int i_row, unsigned int i_col
);
Input:
WnMatrix__removeElement( p_matrix, 1, 2 );
|
|
|
Name: WnMatrix__scaleMatrix()Description: Multiplies all the elements in the matrix by a scalar constant. Syntax:
void WnMatrix__scaleMatrix( WnMatrix *self, double d_val );
Input:
WnMatrix__scaleMatrix( p_matrix, 3.5 );
|
|
|
Name: WnMatrix__writeMatrixToAsciiFile()Description: Writes out the elements of a matrix stored in a WnMatrix structure larger than a cutoff value to a file. Syntax:
int WnMatrix__writeMatrixToAsciiFile(
WnMatrix *self, char * s_ascii_filename, double d_cutoff
);
Input:
If the routine is successful, it returns 1 itself and the matrix in coordinate form in the file with the name s_ascii_filename. If the routine is unsuccessful, it returns 0. Examples: Write out all matrix elements in p_matrix to the file my_matrix.dat:
if(
WnMatrix__writeMatrixToAsciiFile(
p_matrix, "my_matrix.dat", 0.
) == 1
){
printf("Successfully wrote matrix.\n");
}
Write out all matrix elements in p_matrix with absolute value
greater than 1.e-6 to the file my_matrix.dat:
if(
WnMatrix__writeMatrixToAsciiFile(
p_matrix, "my_matrix.dat", 1.e-6
)
){
printf("Successfully wrote matrix.\n");
}
|
|
|
