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
-
Routines
| 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__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__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: Retrieve the column vector for a coordinate matrix structure. Syntax:
unsigned int *
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: Retrieve the row vector for a coordinate matrix structure. Syntax:
unsigned int *
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:
unsigned int *a_row;
a_row = WnMatrix__Coo__getRowVector( p_coo_matrix );
|
|
|
Name: WnMatrix__Coo__getValueVector()Description: Retrieve 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: Output the coordinate matrix to an XML file. Syntax:
void
WnMatrix__Coo_writeToXmlFile(
WnMatrix__Coo *self, const char *s_output_xml_file
);
Input:
For valid input, outputs the data for the coordinate matrix in XML format in the designated file. 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":
WnMatrix__Coo__writeToXmlFile( p_my_coo_matrix, "coo.xml" );
|
|
|
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: Retrieve the column number vector for a matrix in a compressed sparse row matrix structure. Syntax:
unsigned int *
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: Retrieve the row pointer vector for a matrix stored in compressed sparse row matrix format. Syntax:
unsigned int *
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: Retrieve 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: Output the compressed sparse row matrix to an XML file. Syntax:
void
WnMatrix__Csr_writeToXmlFile(
WnMatrix__Csr *self, const char *s_output_xml_file
);
Input:
For valid input, outputs the data for the csr matrix in XML format in the designated file. 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":
WnMatrix__Csr__writeToXmlFile( p_my_csr_matrix, "csr.xml" );
|
|
|
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:
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: Retrieve the element pointer vector for a matrix stored in Yale sparse matrix format. Syntax:
unsigned int *
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: Retrieve 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: Output the yale sparse matrix to an XML file. Syntax:
void
WnMatrix__Yale_writeToXmlFile(
WnMatrix__Yale *self, const char *s_output_xml_file
);
Input:
For valid input, outputs the data for the yale matrix in XML format in the designated file. 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":
WnMatrix__Yale__writeToXmlFile( p_my_yale_matrix, "yale.xml" );
|
|
|
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__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 witht 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,
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__getCoo()Description: Converts a WnMatrix into Coordinate matrix format. 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__getCooMatrix( 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: Converts a WnMatrix into Compressed Sparse Row format. 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, 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__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_vector *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:
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__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: Retrieve 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: Get 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: Get the size of a gsl vector. Syntax:
size_t
WnMatrix__get_gsl_vector_size(
gsl_vector *self
);
Input:
For valid input, returns the size (an unsigned int) 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__gsl_vector_size(
p_my_vector
)
);
|
|
|
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__is_valid_input_xml()Description: Validate 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: Validate 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(
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__new_from_xml()Description: Create 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: Create 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__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__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 solution vector. It is the caller's responsibility to free the output vector with gsl_vector_free when done witht 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__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: Output the vector to an XML file. Syntax:
void
WnMatrix__write_gsl_vector_to_xml_file(
gsl_vector *self,
const char *s_output_xml_file
);
Input:
For valid input, outputs the data for the vector in XML format in the designated file. 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":
WnMatrix__write_gsl_vector_to_xml_file(
p_my_vector, "vector.xml"
);
|
|
|
