| Structures |
|---|
Name: WnMatrix__LineDescription: WnMatrix__Line is a structure for storing and managing row or column data in a WnMatrix. |
Name: WnMatrixDescription: WnMatrix is a structure for storing and managing sparse matrix data. It provides functionality for easily adding and removing elements. |
Name: WnMatrix__ArrowDescription: WnMatrix__Arrow is a structure for storing and managing sparse matrix data in arrow matrix format, that is, a matrix with non-zero entries in a central band and in the last several columns and last several rows. |
Name: WnMatrix__CooDescription: WnMatrix__Coo is a structure for storing and managing sparse matrix data in coordinate matrix format. |
Name: WnMatrix__CsrDescription: WnMatrix__Csr is a structure for storing and managing sparse matrix data in compressed sparse row matrix format. |
Name: WnMatrix__YaleDescription: WnMatrix__Yale is a structure for storing and managing sparse matrix data in Yale sparse matrix format. |
| Routines |
|---|
Name: WnMatrix__Arrow__free()Description: Frees the memory allocated for a WnMatrix__Arrow structure. Syntax:
void
WnMatrix__Arrow__free( WnMatrix__Arrow *self );
Input:
WnMatrix__Arrow__free( p_arrow );
|
Name: WnMatrix__Arrow__getBandWidth()Description: Returns the central band width for a WnMatrix__Arrow matrix. Syntax:
size_t
WnMatrix__Arrow__getBandWidth( WnMatrix__Arrow *self );
Input:
On successful return, the width of the central band is returned. If the input is invalid, error handling is invoked. Example: Get the band width of WnMatrix__Arrow *p_arrow:
i_band_width =
WnMatrix__Arrow__getBandWidth( p_arrow );
|
Name: WnMatrix__Arrow__getNumberOfRows()Description: Returns the number of rows in a WnMatrix__Arrow matrix. Syntax:
size_t
WnMatrix__Arrow__getNumberOfRows( WnMatrix__Arrow *self );
Input:
On successful return, the number of rows is returned. If the input is invalid, error handling is invoked. Example: Get the number of rows in WnMatrix__Arrow *p_arrow:
i_number_rows =
WnMatrix__Arrow__getNumberOfRows( p_arrow );
|
Name: WnMatrix__Arrow__getWingWidth()Description: Returns the width of the wings for a WnMatrix__Arrow matrix. Syntax:
size_t
WnMatrix__Arrow__getWingWidth( WnMatrix__Arrow *self );
Input:
On successful return, the width of the arrow wings is returned. If the input is invalid, error handling is invoked. Example: Get the arrow width of WnMatrix__Arrow *p_arrow:
i_wing_width =
WnMatrix__Arrow__getWingWidth( p_arrow );
|
Name: WnMatrix__Arrow__getWnMatrix()Description: Gets a WnMatrix from an arrow matrix. Syntax:
WnMatrix *
WnMatrix__Arrow__getWnMatrix(
WnMatrix__Arrow *self
);
Input:
Routine returns the input arrow matrix as a WnMatrix. If any input is invalid, error handling is invoked. Example: Get the WnMatrix form of the WnMatrix__Arrow matrix *p_arrow:
p_matrix = WnMatrix__Arrow__getWnMatrix( p_arrow );
|
Name: WnMatrix__Arrow__solve()Description: Uses internal wn_matrix routines to solve the matrix equation Ax = b for x given A and b by Gaussian elimination. Syntax:
gsl_vector *
WnMatrix__Arrow__solve(
WnMatrix__Arrow *self,
gsl_vector *p_input_vector
);
Input:
Routine returns a pointer to a new gsl_vector structure containing solution vector. The rhs vector and the input matrix return as modified by the row operations. It is the caller's responsibility to free the output vector with gsl_vector_free when done with it. If any input is invalid, or if the number of rows of the matrix does not equal the rhs vector length, error handling is invoked. Example: Solve the matrix equation for the input arrow matrix WnMatrix__Arrow * p_arrow and right-hand-side vector p_in, return the result as p_out, convert the modified arrow matrix to a WnMatrix and output as an ascii file (for diagnostic purposes):
p_out =
WnMatrix__Arrow__solve(
p_arrow, p_in
);
p_modified_arrow =
WnMatrix__Arrow__getWnMatrix( p_arrow );
WnMatrix__writeMatrixToAsciiFile(
p_modified_arrow,
"modified_arrow.txt",
0.
);
|
Name: WnMatrix__Coo__free()Description: Frees the memory allocated for a WnMatrix__Coo structure. Syntax:
void
WnMatrix__Coo__free( WnMatrix__Coo *self );
Input:
WnMatrix__Coo__free( p_coo_matrix );
|
Name: WnMatrix__Coo__getColumnVector()Description: Retrieves the column vector for a coordinate matrix structure. Syntax:
size_t *
WnMatrix__Coo__getColumnVector(
WnMatrix__Coo *self
);
Input:
Routine returns the column vector for the coordinate matrix, that is, an array containing the column numbers of the non-zero elements of the matrix. The user does not allocate memory for the returned array. The memory for the array is freed with WnMatrix__Coo_free(). If the input is invalid, error handling is invoked. Example: Retrieve the column vector of the matrix stored in coordinate format in p_coo_matrix:
a_column = WnMatrix__Coo__getColumnVector( p_coo_matrix );
|
Name: WnMatrix__Coo__getRowVector()Description: Retrieves the row vector for a coordinate matrix structure. Syntax:
size_t *
WnMatrix__Coo__getRowVector(
WnMatrix__Coo *self
);
Input:
Routine returns the row vector for the coordinate matrix, that is, the array of row numbers of the non-zone elements. The user does not allocate memory for the returned array. The array memory is freed with WnMatrix__Coo__free(). If the input is invalid, error handling is invoked. Example: Retrieve the row vector of the matrix stored in coordinate format in p_coo_matrix:
size_t *a_row;
a_row = WnMatrix__Coo__getRowVector( p_coo_matrix );
|
Name: WnMatrix__Coo__getValueVector()Description: Retrieves the value vector for a coordinate matrix structure. Syntax:
double *
WnMatrix__Coo__getValueVector(
WnMatrix__Coo *self
);
Input:
Routine returns the value vector for the coordinate matrix. The user does not allocate memory for the array. If the input is invalid, error handling is invoked. Example: Retrieve the value vector of the matrix stored in coordinate format in p_coo_matrix:
a_value = WnMatrix__Coo__getValueVector( p_coo_matrix );
|
Name: WnMatrix__Coo__writeToXmlFile()Description: Outputs the coordinate matrix to an XML file. Syntax:
void
WnMatrix__Coo_writeToXmlFile(
WnMatrix__Coo *self,
const char *s_output_xml_file,
const char *s_format
);
Input:
For valid input, outputs the data for the coordinate matrix in XML format in the designated file for the designated format code. If the input is not valid, or if the XML output routines fail, error handling is invoked. Example: Write the coordinate matrix data in p_my_coo_matrix to the file "coo.xml" using the default format:
WnMatrix__Coo__writeToXmlFile(
p_my_coo_matrix,
"coo.xml",
NULL
);
|
Name: WnMatrix__Csr__free()Description: Frees the memory allocated for a WnMatrix__Csr structure. Syntax:
void WnMatrix__Csr__free( WnMatrix *self );
Input:
WnMatrix__Csr__free( p_csr_matrix );
|
Name: WnMatrix__Csr__getColumnVector()Description: Retrieves the column number vector for a matrix in a compressed sparse row matrix structure. Syntax:
size_t *
WnMatrix__Csr__getColumnVector(
WnMatrix__Csr *self
);
Input:
Routine returns the column number vector of the matrix, that is, the array containing the column numbers of the non-zero elements in the matrix. The user does not allocate memory for the returned array, and the array's memory is freed when the user calls WnMatrix__Csr__free(). If the input is invalid, error handling is invoked. Example: Retrieve the column number vector of the matrix stored in compressed sparse row format in p_csr_matrix:
a_col = WnMatrix__Csr__getColumnVector( p_csr_matrix );
|
Name: WnMatrix__Csr__getRowPointerVector()Description: Retrieves the row pointer vector for a matrix stored in compressed sparse row matrix format. Syntax:
size_t *
WnMatrix__Csr__getRowPointerVector(
WnMatrix__Csr *self
);
Input:
Routine returns the row pointer array for a compressed sparse row matrix. The row pointer array gives the element number of the first non-zero element of the given row. The returned array has N + 1 elements, where N is the number of rows in the matrix. The user does not allocate memory for the array, and the memory for the array is freed when the user frees the Csr matrix with WnMatrix__Csr__free(). If the input is invalid, error handling is invoked. Example: Retrieve the row pointer array of the matrix stored in compressed sparse row format in p_csr_matrix:
a_rowptr = WnMatrix__Csr__getRowPointerVector( p_csr_matrix );
|
Name: WnMatrix__Csr__getValueVector()Description: Retrieves the value vector of a matrix in a compressed sparse row matrix structure. Syntax:
double *
WnMatrix__Csr__getValue(
WnMatrix__Csr *self
);
Input:
Routine returns the value vector of the element stored in the compressed sparse row format. This array contains the value of the non-zero matrix elements. The user does not allocate memory for the returned array, and the memory is freed when the user calls WnMatrix__Csr__free(). If the input is invalid, error handling is invoked. Example: Retrieve the value vector of the matrix stored in compressed sparse row format in p_csr_matrix:
a_value = WnMatrix__Csr__getValue( p_csr_matrix );
|
Name: WnMatrix__Csr__writeToXmlFile()Description: Outputs the compressed sparse row matrix to an XML file. Syntax:
void
WnMatrix__Csr_writeToXmlFile(
WnMatrix__Csr *self,
const char *s_output_xml_file,
const char *s_format
);
Input:
For valid input, outputs the data for the csr matrix in XML format in the designated file with the designated format code for the matrix element value. If the input is not valid, or if the XML output routines fail, error handling is invoked. Example: Write the compressed sparse row matrix data in p_my_csr_matrix to the file "csr.xml" using exponential format with fifteen decimal place precision:
WnMatrix__Csr__writeToXmlFile(
p_my_csr_matrix,
"csr.xml",
"%.15e"
);
|
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: Gets 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:
size_t 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_values[i] );
}
WnMatrix__Line__free( p_row );
|
Name: WnMatrix__Line__getNonZeroIndices()Description: Gets 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:
size_t *
WnMatrix__Line__getNonZeroIndices(
WnMatrix__Line *self
);
Input:
size_t 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: Gets the number of non-zero elements in a row or column in a WnMatrix structure. Syntax:
size_t
WnMatrix__Line__getNumberOfElements(
WnMatrix__Line *self
);
Input:
p_row = WnMatrix__getRow( p_my_matrix, 3 );
printf(
"%d\n",
WnMatrix__getNumberOfElements( p_row )
);
WnMatrix__Line__free( p_row );
|
Name: WnMatrix__Yale__free()Description: Frees the memory allocated for a WnMatrix__Yale structure. Syntax:
void WnMatrix__Yale__free( WnMatrix__Yale *self );
Input:
WnMatrix__Yale__free( p_yale_matrix );
|
Name: WnMatrix__Yale__getPointerVector()Description: Retrieves the element pointer vector for a matrix stored in Yale sparse matrix format. Syntax:
size_t *
WnMatrix__Yale__getPointerVector(
WnMatrix__Yale *self
);
Input:
Routine returns the element pointer array for a Yale sparse matrix. The returned array has N + M + 1 elements, where N is the number of rows and M is the number of non-zero matrix elements. For a matrix with N rows, the first N elements of the array point to the index of the same array that contain the first non-zero element of the given row. The user does not allocate memory for the array, and the memory for the array is freed when the user frees the Yale matrix with WnMatrix__Yale__free(). If the input is invalid, error handling is invoked. Example: Retrieve the element pointer array of the matrix stored in Yale sparse format in p_yale_matrix:
a_ptr = WnMatrix__Yale__getPointerVector( p_yale_matrix );
|
Name: WnMatrix__Yale__getValueVector()Description: Retrieves the value vector for a matrix stored in Yale sparse matrix format. Syntax:
double *
WnMatrix__Yale__getValueVector(
WnMatrix__Yale *self
);
Input:
Routine returns the value array for a Yale sparse matrix. The returned array has N + M + 1 elements, where N is the number of rows and M is the number of non-zero matrix elements. For a matrix with N rows, the first N elements of the array contain the diagonal matrix elements. The elements for index >= N + 2, where N = number of rows, contain the off-diagonal elements ordered by rows and, within each row, ordered by column. The user does not allocate memory for the array, and the memory for the array is freed when the user frees the Yale matrix with WnMatrix__Yale__free(). If the input is invalid, error handling is invoked. Example: Retrieve the value array of the matrix stored in Yale sparse format in p_yale_matrix:
a_val = WnMatrix__Yale__getValueVector( p_yale_matrix );
|
Name: WnMatrix__Yale__writeToXmlFile()Description: Outputs the Yale sparse matrix to an XML file. Syntax:
void
WnMatrix__Yale_writeToXmlFile(
WnMatrix__Yale *self,
const char *s_output_xml_file,
const char *s_format
);
Input:
For valid input, outputs the data for the yale matrix in XML format in the designated file with the designated format code for the matrix element value. If the input is not valid, or if the XML output routines fail, error handling is invoked. Example: Write the yale matrix data in p_my_yale_matrix to the file "yale.xml" using float format with ten decimal place precision for output of the matrix element values:
WnMatrix__Yale__writeToXmlFile(
p_my_yale_matrix,
"yale.xml",
"%.10f"
);
|
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, size_t i_row,
size_t 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:
size_t i_row = 1;
size_t 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__computeMatrixTimesMatrix()Description: Computes the matrix M from the equation M = A . B, given matrix A and matrix B. Syntax:
WnMatrix *
WnMatrix__computeMatrixTimesMatrix(
WnMatrix *self,
WnMatrix *p_input_matrix
);
Input:
Routine returns a pointer to a new WnMatrix structure that is the product of the two input matrices. It is the caller's responsibility to free the output matrix with WnMatrix__free() when done with it. If the number of columns in the first matrix does not equal the number of rows in the second, or if any input is invalid, error handling is invoked. Example: Multiply the vector p_matrix2 by the WnMatrix * p_matrix and return the result as p_out:
p_out =
WnMatrix__computeMatrixTimesMatrix(
p_matrix, p_matrix2
);
|
Name: WnMatrix__computeMatrixTimesVector()Description: Computes the vector y from the equation y = Ax, given matrix A and vector x. Syntax:
gsl_vector *
WnMatrix__computeMatrixTimesVector(
WnMatrix *self,
gsl_vector *p_input_vector
);
Input:
Routine returns a pointer to a new gsl_vector structure containing the product of the matrix and input vector. It is the caller's responsibility to free the output vector with gsl_vector_free when done with it. If the number of columns in the input matrix does not equal the length of the input vector, or if any input is invalid, error handling is invoked. Example: Multiply the vector p_in by the WnMatrix * p_matrix and return the result as p_out:
p_out =
WnMatrix__computeMatrixTimesVector(
p_matrix, p_in
);
|
Name: WnMatrix__computeTransposeMatrixTimesVector()Description: Computes the matrix equation Y = A(transpose)x given A and x. Syntax:
gsl_vector *
WnMatrix__computeTransposeMatrixTimesVector(
WnMatrix *self,
gsl_vector *p_input_vector
);
Input:
Routine returns a pointer to a new gsl_vector structure containing the product of the transpose of the matrix and input vector. It is the caller's responsibility to free the output vector with gsl_vector_free when done with it. If the number of rows in the input matrix (that is, the number of columns in the transpose matrix) does not equal the length of the input vector, or if any input is invalid, error handling is invoked. Example: Multiply the vector p_in by the transpose of WnMatrix * p_matrix and return the result as p_out:
p_out =
WnMatrix__computeTransposeMatrixTimesVector(
p_matrix, p_in
);
|
Name: WnMatrix__extractMatrix()Description: Extracts a smaller WnMatrix from a larger one. Syntax:
WnMatrix *
WnMatrix__extractMatrix(
WnMatrix *self,
size_t i_row,
size_t i_col,
size_t i_row_offset,
size_t 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__getArrow()Description: Returns an arrow matrix, that is, one in which the matrix is stored in arrow format (a central band with wings along the far right side and bottom). Syntax:
WnMatrix__Arrow *
WnMatrix__getArrow(
WnMatrix *self,
size_t i_wing_width
);
Input:
Routine returns a pointer to a new WnMatrix__Arrow structure. It is the caller's responsibility to free the arrow matrix with WnMatrix__Arrow__free() when done with it. If the number of columns in the input matrix does not equal the length of the input vector, or if any input is invalid, error handling is invoked. Example: Get the arrow matrix form of the WnMatrix *p_my_matrix with arrow wing width of 3:
p_arrow = WnMatrix__getArrow( p_my_matrix, 3L );
|
Name: WnMatrix__getColumn()Description: Gets a column from a WnMatrix structure. Syntax:
WnMatrix__Line *
WnMatrix__getRow(
WnMatrix *self, size_t i_col
);
Input:
WnMatrix__Line *p_col;
p_col = WnMatrix__getColumn( p_my_matrix, 3 );
|
Name: WnMatrix__getCoo()Description: Retrieves the coordinate matrix format of a matrix. Syntax:
WnMatrix__Coo *WnMatrix__getCoo( WnMatrix *self );
Input:
Routine returns a pointer to a new WnMatrix__Coo structure that contains the matrix in coordinate format. If the input is invalid or if the memory for the coordinate matrix cannot be allocated, error handling is invoked. Example: Store the elements of WnMatrix * p_matrix in Coordinate format in WnMatrix__Coo * p_coo_matrix:
p_coo_matrix = WnMatrix__getCoo( p_matrix );
|
Name: WnMatrix__getCopy()Description: Returns a copy of the matrix. Syntax:
WnMatrix * WnMatrix__getCopy( WnMatrix *self );
Input:
For valid input, routine returns a new WnMatrix * that contains a copy of the matrix. Routine does not free the input matrix. The caller must free the memory for this new matrix with WnMatrix__free. If the input matrix is invalid, the behavior is undefined, although this error may be caught by the error handler. Example: Retrieve a copy of the WnMatrix *p_matrix and store it in WnMatrix *p_copy:
p_copy = WnMatrix__getCopy( p_matrix );
|
Name: WnMatrix__getCsr()Description: Retrieves the Compressed Sparse Row format of a matrix. Syntax:
WnMatrix__Csr * WnMatrix__getCsr( WnMatrix *self );
Input:
Routine returns a pointer to a new WnMatrix__Csr structure that contains the matrix in compressed sparse row format. If the input is invalid or if the memory for the compressed sparse row matrix cannot be allocated, error handling is invoked. Example: Store the elements of WnMatrix * p_matrix in Compressed Sparse Row format in the structure pointed to by p_csr_matrix:
p_csr_matrix = WnMatrix__getCsr( p_matrix );
|
Name: WnMatrix__getDiagonalElements()Description: Returns a gsl_vector containing the diagonal elements. Syntax:
gsl_vector *
WnMatrix__getDiagonalElements(
WnMatrix *self
);
Input:
On successful return, the routine returns a new gsl_vector 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 vector. Example: Print the diagonal elements of WnMatrix *p_matrix:
gsl_vector *p_diagonals;
p_diagonals = WnMatrix__getDiagonalElements( p_matrix );
for(
i = 1;
i <= WnMatrix__get_gsl_vector_size( p_diagonals );
i++
)
{
printf(
"row = %d diag element = %e\n",
i,
gsl_vector_get( p_diagonals, i - 1 );
);
}
gsl_vector_free( p_diagonals );
|
Name: WnMatrix__getElement()Description: Retrieves the value of the specified matrix element. Syntax:
double WnMatrix__getElement(
WnMatrix *self, size_t i_row, size_t 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__getGslMatrix()Description: Stores the matrix in gsl_matrix format. Syntax:
gsl_matrix *
WnMatrix__getGslMatrix( WnMatrix *self );
Input:
For valid input, routine returns a new gsl_matrix that contains the elements of WnMatrix *self. Routine does not free the input matrix. The user must free the memory for the gsl_matrix matrix. Example: Store p_matrix in dense format in gsl_matrix p_mat:
gsl_matrix *p_mat;
p_mat = WnMatrix__getGslMatrix( p_matrix );
... (do something with the matrix)
gsl_matrix_free( p_mat );
|
Name: WnMatrix__getNumberOfColumns()Description: Returns the number of columns in the matrix. Syntax:
size_t WnMatrix__getNumberOfColumns( WnMatrix *self );
Input:
Routine returns the number of columns in self. Example: Retrieve the number of columns from WnMatrix *p_matrix and store it in l_columns:
size_t i_columns;
i_columns = WnMatrix__getNumberOfColumns( p_matrix );
|
Name: WnMatrix__getNumberOfElements()Description: Returns the number of non-zero elements in the matrix. Syntax:
size_t WnMatrix__getNumberOfElements( WnMatrix *self );
Input:
Routine returns the number of elements in self. Example: Retrieve the number of elements in WnMatrix *p_matrix and store it in i_elements:
size_t i_elements;
i_elements = WnMatrix__getNumberOfElements( p_matrix );
|
Name: WnMatrix__getNumberOfRows()Description: Returns the number of rows in the matrix. Syntax:
size_t WnMatrix__getNumberOfRows( WnMatrix *self );
Input:
Routine returns the number of rows in self. Example: Retrieve the number of rows from WnMatrix *p_matrix and stores it in l_rows:
size_t i_rows;
i_rows = WnMatrix__getNumberOfRows( p_matrix );
|
Name: WnMatrix__getRow()Description: Gets a row from a WnMatrix structure. Syntax:
WnMatrix__Line *
WnMatrix__getRow(
WnMatrix *self, size_t 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__getTranspose()Description: Returns the transpose of the matrix. Syntax:
WnMatrix * WnMatrix__getTranspose( WnMatrix *self );
Input:
For valid input, routine returns a new WnMatrix * that contains the transpose of the matrix. Routine does not free the input matrix. The caller must free the memory for this new matrix with WnMatrix__free. If the input matrix is invalid, the behavior is undefined, although this error may be caught by the error handler. Example: Retrieve the tranpose of the WnMatrix *p_matrix and store it in WnMatrix *p_transpose_matrix:
p_tranpose_matrix = WnMatrix__getTranspose( p_matrix );
|
Name: WnMatrix__getYale()Description: Retrieves the Yale sparse form of the matrix. Syntax:
WnMatrix__Yale *
WnMatrix__getYaleSparseMatrix(
WnMatrix *self
);
Input:
Routine returns a pointer to a new WnMatrix__Yale structure that contains the matrix in Yale sparse matrix format. If the input is invalid or if the memory for the Yale sparse matrix cannot be allocated, error handling is invoked. Example: Store the WnMatrix *p_matrix in Yale Sparse format in WnMatrix__Yale *p_yale:
p_yale = WnMatrix__getYale( p_matrix );
|
Name: WnMatrix__get_gsl_vector_array()Description: Gets the data array of a gsl vector. Syntax:
double *
WnMatrix__get_gsl_vector_array(
gsl_vector *self
);
Input:
For valid input, returns a pointer to a double array containing the data for the vector. The caller does not need to free this array; it is freed when the user frees the original gsl_vector. If the input is not valid, error handling is invoked. Example: Get the double array containing the data for the gsl_vector *p_my_vector:
a_data = WnMatrix__get_gsl_vector_array( p_my_vector );
|
Name: WnMatrix__get_gsl_vector_size()Description: Gets the size of a gsl vector. Syntax:
size_t
WnMatrix__get_gsl_vector_size(
gsl_vector *self
);
Input:
For valid input, returns the size of the vector. If the input is not valid, error handling is invoked. Example: Print the size of the gsl_vector p_my_vector:
printf(
"The size of the vector is %d\n",
WnMatrix__get_gsl_vector_size(
p_my_vector
)
);
|
Name: WnMatrix__insertColumn()Description: Inserts a column into a matrix. Syntax:
void
WnMatrix__insertColumn(
WnMatrix *self,
size_t i_column,
gsl_vector *p_column
);
Input:
On successful return, the column has been inserted. The number of columns in the matrix is one more than upon input. If any input is invalid, error handling is invoked. Example: Insert vector p_vector into matrix p_matrix at column 3:
WnMatrix__insertColumn( p_matrix, 3L, p_vector );
|
Name: WnMatrix__insertMatrix()Description: Inserts a smaller WnMatrix into a larger one. Syntax:
void
WnMatrix__insertMatrix(
WnMatrix *self, WnMatrix *p_inserted_matrix,
size_t i_row, size_t 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__insertRow()Description: Inserts a row into a matrix. Syntax:
void
WnMatrix__insertRow(
WnMatrix *self,
size_t i_row,
gsl_vector *p_row
);
Input:
On successful return, the row has been inserted. The number of rows in the matrix is one more than upon input. If any input is invalid, error handling is invoked. Example: Insert vector p_vector into matrix p_matrix at row 3:
WnMatrix__insertRow( p_matrix, 3L, p_vector );
|
Name: WnMatrix__is_valid_input_xml()Description: Validates an input wn_matrix XML file. Syntax:
int
WnMatrix__is_valid_input_xml(
const char *s_input_xml_file
);
Input:
For valid input, routine returns 1 (true) if the XML file is valid or 0 (false) if it is not. If the file is not valid, the routine also prints out the error message. If there is a problem with the schema, or the routine cannot find the schema over the web, or if the XML parser routines fail, error handling is invoked. Example: Validate the input XML file input.xml:
if( WnMatrix__is_valid_input_xml( "input.xml" ) ) {
printf( "Valid input XML!\n" );
}
|
Name: WnMatrix__is_valid_vector_input_xml()Description: Validates an input wn_matrix vector XML file. Syntax:
int
WnMatrix__is_valid_vector_input_xml(
const char *s_input_xml_file
);
Input:
For valid input, routine returns 1 (true) if the XML file is valid or 0 (false) if it is not. If the file is not valid, the routine also prints out the error message. If there is a problem with the schema, or the routine cannot find the schema over the web, or if the XML parser routines fail, error handling is invoked. Example: Validate the input XML file input.xml:
if( WnMatrix__is_valid_vector_input_xml( "input.xml" ) ) {
printf( "Valid input XML vector!\n" );
}
|
Name: WnMatrix__new()Description: Initializes a WnMatrix structure. Syntax:
WnMatrix *WnMatrix__new(
size_t i_rows,
size_t 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__new_from_xml()Description: Creates a new matrix from data in an xml file. Syntax:
WnMatrix *
WnMatrix__new_from_xml
const char *s_input_xml_file, const char *s_xpath_expression
);
Input:
For valid input, routine returns a pointer to a WnMatrix structure with the input data. If the input is not valid, or if the XML parser routines fail, error handling is invoked. Examples: Create a WnMatrix structure from data in the file input.xml:
p_my_matrix = WnMatrix__new_from_xml( "input.xml", NULL );
Create a WnMatrix structure from data
in the file input.xml such that only non-negative values are
included:
p_my_matrix = WnMatrix__new_from_xml( "input.xml", "[value >= 0]" );
|
Name: WnMatrix__new_gsl_vector_from_xml()Description: Creates a new vector from data in an xml file. Syntax:
gsl_vector *
WnMatrix__new_gsl_vector_from_xml
const char *s_input_xml_file, const char *s_xpath_expression
);
Input:
For valid input, routine returns a pointer to a new gsl_vector structure with the input data. If the input is not valid, or if the XML parser routines fail, error handling is invoked. Examples: Create a new gsl_vector structure from data in the file input.xml:
p_my_vector =
WnMatrix__new_gsl_vector_from_xml( "input.xml", NULL );
Create a new gsl_vector structure
from data in the file input.xml such that only non-negative values
are included:
p_my_vector =
WnMatrix__new_gsl_vector_from_xml( "input.xml", "[. >= 0]" );
|
Name: WnMatrix__removeColumn()Description: Removes a column from a matrix. Syntax:
void
WnMatrix__removeColumn(
WnMatrix *self,
size_t i_column
);
Input:
On successful return, the column has been removed. The number of columns in the matrix is one less than upon input. If any input is invalid, error handling is invoked. Example: Remove column 3 from matrix p_matrix:
WnMatrix__removeColumn( p_matrix, 3L );
|
Name: WnMatrix__removeElement()Description: Removes the specified matrix element from the matrix. Syntax:
int
WnMatrix__removeElement(
WnMatrix *self, size_t i_row, size_t i_col
);
Input:
WnMatrix__removeElement( p_matrix, 1, 2 );
|
Name: WnMatrix__removeRow()Description: Removes a row from a matrix. Syntax:
void
WnMatrix__removeRow(
WnMatrix *self,
size_t i_row
);
Input:
On successful return, the row has been removed. The number of rows in the matrix is one less than upon input. If any input is invalid, error handling is invoked. Example: Remove row 3 from matrix p_matrix:
WnMatrix__removeRow( p_matrix, 3L );
|
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__solve()Description: Uses the gsl LU decomposition routines to solve the matrix equation Ax = b for x given A and b. Syntax:
gsl_vector *
WnMatrix__solve
WnMatrix *self,
gsl_vector *p_input_vector
);
Input:
Routine returns a pointer to a new gsl_vector structure containing the solution vector. It is the caller's responsibility to free the output vector with gsl_vector_free when done with it. If the number of columns in the input matrix does not equal the length of the input vector, or if any input is invalid, error handling is invoked. Example: Solve the matrix equation for input matrix WnMatrix * p_matrix and right-hand-side vector p_in and return the result as p_out:
p_out =
WnMatrix__solve(
p_matrix, p_in
);
|
Name: WnMatrix__updateElement()Description: Updates an element in a WnMatrix structure. If an element already exists at that (row,col), it is replaced by the new value. Syntax:
int
WnMatrix__updateElement(
WnMatrix *self,
size_t i_row,
size_t i_col,
double d_val
);
Input:
Routine returns 0 if the value at i_row and i_col has been successful updated to the input value and -1 if not. If the input matrix pointer or the row or column is invalid, error handling is invoked. Example: Update the value at row 1, column 2 of WnMatrix * p_matrix to 3.5:
WnMatrix__updateElement( p_matrix, 1L, 2L, 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");
}
|
Name: WnMatrix__write_gsl_vector_to_xml_file()Description: Outputs the vector to an XML file. Syntax:
void
WnMatrix__write_gsl_vector_to_xml_file(
gsl_vector *self,
const char *s_output_xml_file,
const char *s_format
);
Input:
For valid input, outputs the data for the vector in XML format in the designated file with the designated format for the vector component value. If the input is not valid, or if the XML output routines fail, error handling is invoked. Example: Write the vector data in p_my_vector to the file "vector.xml" using the default format:
WnMatrix__write_gsl_vector_to_xml_file(
p_my_vector, "vector.xml", NULL
);
|