| Structures |
|---|
Name: WnSparseSolve__MatDescription: WnSparseSolve__Mat is a structure for handling settings for SPARSKIT2 iterative solvers. |
Name: WnSparseSolve__ExpDescription: WnSparseSolve__Exp is a structure for handling settings for SPARSKIT2 matrix exponentiation. |
Name: WnSparseSolve__PhiDescription: WnSparseSolve__Phi is a structure for handling settings for SPARSKIT2 matrix exponentiation with an additional constant added vector. |
| User-Supplied Routines |
|---|
Name: WnSparseSolve__Mat__ConvergenceTester()Description: Optional user-supplied routine to test the convergence of a solution. Syntax:
int
WnSparseSolve__Mat__ConvergenceTester(
gsl_vector *p_change_vector,
gsl_vector *p_solution_vector,
void *p_user_data
);
Input:
User's routine must return a zero (0) if the solution does not satisfy the user-defined convergence criterion or one (1) if it does. |
Name: WnSparseSolve__Mat__PreconditionerSolver()Description: Optional user-supplied routine to compute the solution to the matrix equation Mx = b, where the inverse of M is an approximation to the inverse of the matrix for which the solution is required. Syntax:
gsl_vector *
WnSparseSolve__Mat__PreconditionerSolver(
gsl_vector *p_rhs_vector,
void *p_user_data
);
Input:
User's routine must return a new gsl_vector giving the solution to Mx = b, where the inverse of M is the approximate inverse matrix (M or its inverse is passed in through the user's data structure) and b is the right-hand-side vector. |
Name: WnSparseSolve__Mat__PreconditionerTransposeSolver()Description: Optional user-supplied routine to compute the solution to the matrix equation (transpose of M)x = b, where the inverse of M is an approximation to the inverse of the matrix for which the solution is required. Syntax:
gsl_vector *
WnSparseSolve__Mat__PreconditionerTransposeSolver(
gsl_vector *p_rhs_vector,
void *p_user_data
);
Input:
User's routine must return a new gsl_vector giving the solution to (transpose of M)x = b, where the inverse of M is the approximate inverse matrix (M or its inverse is passed in through the user's data structure) and b is the right-hand-side vector. |
| Routines |
|---|
Name: WnSparseSolve__Exp__clearDebug()Description: Clear the debug flag for a sparse matrix exponentiation solver. Syntax:
void
WnSparseSolve__Exp__clearDebug(
WnSparseSolve__Exp *self
);
Input:
Upon successful return, the debug flag has been cleared for the solver so that debugging information will no longer be printed to stdout during solution iterations. If the input is invalid, error handling is invoked. Example: Clear the debug flag for WnSparseSolve__Exp *p_my_exp_solver:
WnSparseSolve__Exp__clearDebug(
p_my_exp_solver
);
|
Name: WnSparseSolve__Exp__free()Description: Free the memory allocated for a WnSparseSolve__Exp structure. Syntax:
void
WnSparseSolve__Exp__free(
WnSparseSolve__Exp *self
);
Input:
Upon successful return, the solver has been freed. The solver pointer self is no longer available for use--it must be reallocated using WnSparseSolve__Exp__new(). Example: Free the memory for WnSparseSolve__Exp *p_my_exp_solver:
WnSparseSolve__Exp__free(
p_my_exp_solver
);
|
Name: WnSparseSolve__Exp__new()Description: Create a new sparse exponentiation solver. Syntax:
WnSparseSolve__Exp *
WnSparseSolve__Exp__new( );
Output:Upon successful return, a new solver has been created. The default values for the solver are that the maximum number of iterations allowed is 100, the tolerances are 1.e-8, the workspace has size 40, and debugging is turned off. These values can be updated by other API routines. Example: Create a new exponentiation solver:
p_my_exp_solver = WnSparseSolve__Exp__new();
|
Name: WnSparseSolve__Exp__setDebug()Description: Set the debug flag for a sparse matrix exponentiation solver. Syntax:
void
WnSparseSolve__Exp__setDebug(
WnSparseSolve__Exp *self
);
Input:
Upon successful return, the debug flag has been set for the solver so that debugging information will be printed to stdout during solution iterations. If the input is invalid, error handling is invoked. Example: Set the debug flag for WnSparseSolve__Exp *p_my_exp_solver:
WnSparseSolve__Exp__setDebug(
p_my_exp_solver
);
|
Name: WnSparseSolve__Exp__solve()Description: Solve a matrix equation dY/dt = AY by matrix exponentiation. Syntax:
gsl_vector *
WnSparseSolve__Exp__solve(
WnSparseSolve__Exp *self,
WnMatrix *p_matrix,
gsl_vector *p_initial_vector,
double d_time
);
Input:
Routine returns a gsl_vector with the solution (if solution successful) or NULL otherwise. Example: Solve the matrix equation dY/dt = AY, where A is stored as WnMatrix *p_my_matrix, over time 10. The solution is Y(t) = exp( A*10 ) Y(0). Y(0) is the initial vector stored in p_in. Use the exponentiation solver p_my_exp and store the result in the gsl_vector p_sol:
p_sol =
WnSparseSolve__Exp__solve(
p_my_exp, p_my_matrix, p_in, 10.
);
if( p_sol )
fprintf( stdout, "Solution succeeded!\n" );
|
Name: WnSparseSolve__Exp__updateMaximumIterations()Description: Update the maximum number of iterations allowed for an exponentation solver. Syntax:
void
WnSparseSolve__Exp__updateMaximumIterations(
WnSparseSolve__Exp *self,
int i_iter_max
);
Input:
Upon successful return, the maximum number of iterations has been updated to the input value. If the input is invalid, error handling is invoked. Example: Set the maximum number of iterations for WnSparseSolve__Exp *p_my_exp_solver to 50:
WnSparseSolve__Exp__updateMaximumIterations(
p_my_exp_solver, 50
);
|
Name: WnSparseSolve__Exp__updateTolerance()Description: Update the tolerance for an exponentiation solver. Syntax:
void
WnSparseSolve__Exp__updateTolerance
WnSparseSolve__Exp *self,
double d_tolerance
);
Input:
Upon successful return, the tolerance has been updated to the input value. If the input is invalid, error handling is invoked. Example: Set the tolerance for WnSparseSolve__Exp *p_my_exp_solver to 1.e-12:
WnSparseSolve__Exp__updateTolerance(
p_my_exp_solver, 1.e-12
);
|
Name: WnSparseSolve__Exp__updateWorkSpace()Description: Update the allowed workspace for an exponentation solver. Syntax:
void
WnSparseSolve__Exp__updateWorkSpace(
WnSparseSolve__Exp *self,
int i_workspace
);
Input:
Upon successful return, the workspace has been updated to the input value. If the input is invalid, error handling is invoked. Example: Set the workspace for WnSparseSolve__Exp *p_my_exp_solver to 10:
WnSparseSolve__Mat__updateWorkSpace(
p_my_exp_solver, 10
);
|
Name: WnSparseSolve__Mat__clearDebug()Description: Clear the debug flag for a sparse matrix solver. Syntax:
void
WnSparseSolve__Mat__clearDebug(
WnSparseSolve__Mat *self
);
Input:
Upon successful return, the debug flag has been cleared for the solver so that debugging information will no longer be printed to stdout during solution iterations. If the input is invalid, error handling is invoked. Example: Clear the debug flag for WnSparseSolve__Mat *p_my_solver:
WnSparseSolve__Mat__clearDebug(
p_my_solver
);
|
Name: WnSparseSolve__Mat__free()Description: Free the memory allocated for a WnSparseSolve__Mat structure. Syntax:
void
WnSparseSolve__Mat__free(
WnSparseSolve__Mat *self
);
Input:
Upon successful return, the solver has been freed. The solver pointer self is no longer available for use--it must be reallocated using WnSparseSolve__Mat__new(). Example: Free the memory for WnSparseSolve__Mat *p_my_solver:
WnSparseSolve__Mat__free(
p_my_solver
);
|
Name: WnSparseSolve__Mat__getSolverMethod()Description: Retrieve the current solver method. Syntax:
const char *
WnSparseSolve__Mat__getSolverMethod(
WnSparseSolve__Mat *self
);
Input:
The routine returns a string indicating the current solver method. If the input is invalid, error handling is invoked. Example: Print the current solver method for WnSparseSolve__Mat *p_my_solver:
printf(
"The current solver is %s\n",
WnSparseSolve__Mat__getSolverMethod(
p_my_solver
)
);
|
Name: WnSparseSolve__Mat__new()Description: Create a new sparse solver. Syntax:
WnSparseSolve__Mat *
WnSparseSolve__Mat__new( );
Output:Upon successful return, a new solver has been created. The default values for the solver are that the type is a biconjugate gradient solver, the maximum number of iterations allowed is 100, the absolute and relative tolerances are 1.e-8, the preconditioner matrix is simply the identity matrix, and debugging is turned off. These values can be updated by other API routines. Example: Create a new solver:
p_my_solver = WnSparseSolve__Mat__new();
|
Name: WnSparseSolve__Mat__setDebug()Description: Set the debug flag for a sparse matrix solver. Syntax:
void
WnSparseSolve__Mat__setDebug(
WnSparseSolve__Mat *self
);
Input:
Upon successful return, the debug flag has been set for the solver so that debugging information will be printed to stdout during solution iterations. If the input is invalid, error handling is invoked. Example: Set the debug flag for WnSparseSolve__Mat *p_my_solver:
WnSparseSolve__Mat__setDebug(
p_my_solver
);
|
Name: WnSparseSolve__Mat__solve()Description: Solve a matrix equation. Syntax:
gsl_vector *
WnSparseSolve__Mat__solve(
WnSparseSolve__Mat *self,
WnMatrix *p_matrix,
gsl_vector *p_rhs,
gsl_vector *p_guess
);
Input:
Routine returns a gsl_vector with the solution (if solution successful) or NULL otherwise. Example: Solve the matrix equation A x = b where A is stored as WnMatrix *p_my_matrix, b is stored in the gsl_vector p_rhs, and a guess for the solution is stored in p_guess. Use the solver WnSparseSolve__Mat *p_my_solver and store result in the gsl_vector p_sol:
p_sol =
WnSparseSolve__Mat__solve(
p_my_solver, p_my_matrix, p_rhs, p_guess
);
if( p_sol )
fprintf( stdout, "Solution succeeded!\n" );
|
Name: WnSparseSolve__Mat__updateAbsoluteTolerance()Description: Update the relative tolerance for a solver. Syntax:
void
WnSparseSolve__Mat__updateAbsoluteTolerance
WnSparseSolve__Mat *self,
double d_relative_tolerance
);
Input:
Upon successful return, the absolute tolerance has been updated to the input value. If the input is invalid, error handling is invoked. Example: Set the absolute tolerance for WnSparseSolve__Mat *p_my_solver to 1.e-6:
WnSparseSolve__Mat__updateAbsoluteTolerance(
p_my_solver, 1.e-6
);
|
Name: WnSparseSolve__Mat__updateConvergenceMethod()Description: Update the convergence method. Syntax:
void
WnSparseSolve__Mat__updateConvergenceMethod(
WnSparseSolve__Mat *self,
const char *s_method
);
Input:
Upon successful return, the solver method has been updated to the input value. If the input is invalid, error handling is invoked. Example: Set the solver method for WnSparseSolve__Mat *p_my_solver to use the rhs criterion:
WnSparseSolve__Mat__updateConvergenceMethod(
p_my_solver, "rhs"
);
|
Name: WnSparseSolve__Mat__updateConvergenceTester()Description: Set the convergence tester. Syntax:
void
WnSparseSolve__Mat__updateConvergenceTester(
WnSparseSolve__Mat *self,
WnSparseSolve__Mat__ConvergenceTester pf_convergence_tester
);
Input:
Upon successful return, the convergence tester has been updated to the input value. If the input is invalid, error handling is invoked. Example: Set the convergence tester for WnSparseSolve__Mat *p_my_solver to my_tester:
WnSparseSolve__Mat__updateConvergenceTester(
p_my_solver,
(WnSparseSolve__Mat__ConvergenceTester)
my_tester
);
|
Name: WnSparseSolve__Mat__updateConvergenceTesterUserData()Description: Set the user-supplied data to accompany the user's convergence tester. Syntax:
void
WnSparseSolve__Mat__updateConvergenceTesterUserData(
WnSparseSolve__Mat *self,
void *p_user_data
);
Input:
Upon successful return, the user data has been updated to the input value. If the input is invalid, error handling is invoked. Example: Set the extra data to be supplied by the user for the convergence tester (which is stored in the data structure my_data) for WnSparseSolve__Mat *p_my_solver:
WnSparseSolve__Mat__updateConvergenceTesterUserData(
p_my_solver,
&my_data
);
|
Name: WnSparseSolve__Mat__updateMaximumIterations()Description: Update the maximum number of iterations allowed for a solver. Syntax:
void
WnSparseSolve__Mat__updateMaximumIterations(
WnSparseSolve__Mat *self,
int i_iter_max
);
Input:
Upon successful return, the maximum number of iterations has been updated to the input value. If the input is invalid, error handling is invoked. Example: Set the maximum number of iterations for WnSparseSolve__Mat *p_my_solver to 50:
WnSparseSolve__Mat__updateMaximumIterations(
p_my_solver, 50
);
|
Name: WnSparseSolve__Mat__updatePreconditionerSolver()Description: Set the preconditioner solver. Syntax:
void
WnSparseSolve__Mat__updatePreconditionerSolver(
WnSparseSolve__Mat *self,
WnSparseSolve__Mat__PreconditionerSolver pf_preconditioner_solver
);
Input:
Upon successful return, the preconditioner solver has been updated to the input value. If the input is invalid, error handling is invoked. Example: Set the preconditioner solver for WnSparseSolve__Mat *p_my_solver to my_preconditioner_solver:
WnSparseSolve__Mat__updatePreconditionerSolver(
p_my_solver,
(WnSparseSolve__Mat__PreconditionerSolver)
my_preconditioner_solver
);
|
Name: WnSparseSolve__Mat__updatePreconditionerTransposeSolver()Description: Set the preconditioner transpose solver. Syntax:
void
WnSparseSolve__Mat__updatePreconditionerTransposeSolver(
WnSparseSolve__Mat *self,
WnSparseSolve__Mat__PreconditionerTransposeSolver
pf_preconditioner_transpose_solver
);
Input:
Upon successful return, the preconditioner transpose solver has been updated to the input value. If the input is invalid, error handling is invoked. Example: Set the preconditioner transpose solver for WnSparseSolve *p_my_solver to my_preconditioner_transpose solver:
WnSparseSolve__Mat__updatePreconditionerTransposeSolver(
p_my_solver,
(WnSparseSolve__Mat__PreconditionerTransposeSolver)
my_preconditioner_transpose_solver
);
|
Name: WnSparseSolve__Mat__updatePreconditionerUserData()Description: Set the user-supplied data to accompany the user's preconditioner solvers. Syntax:
void
WnSparseSolve__Mat__updatePreconditionerUserData(
WnSparseSolve__Mat *self,
void *p_user_data
);
Input:
Upon successful return, the user data has been updated to the input value. If the input is invalid, error handling is invoked. Example: Set the extra data to be supplied by the user (which is stored in the data structure my_data) for WnSparseSolve__Mat *p_my_solver:
WnSparseSolve__Mat__updatePreconditionerUserData(
p_my_solver,
&my_data
);
|
Name: WnSparseSolve__Mat__updateRelativeTolerance()Description: Update the relative tolerance for a solver. Syntax:
void
WnSparseSolve__Mat__updateRelativeTolerance
WnSparseSolve__Mat *self,
double d_relative_tolerance
);
Input:
Upon successful return, the relative tolerance has been updated to the input value. If the input is invalid, error handling is invoked. Example: Set the relative tolerance for WnSparseSolve__Mat *p_my_solver to 1.e-12:
WnSparseSolve__Mat__updateRelativeTolerance(
p_my_solver, 1.e-12
);
|
Name: WnSparseSolve__Mat__updateSolverMethod()Description: Update the solver method. Syntax:
void
WnSparseSolve__Mat__updateSolverMethod(
WnSparseSolve__Mat *self,
const char *s_method
);
Input:
Upon successful return, the solver method has been updated to the input value. If the input is invalid, error handling is invoked. Example: Set the solver method for WnSparseSolve__Mat *p_my_solver to the full orthogonalization method:
WnSparseSolve__Mat__updateSolverMethod(
p_my_solver, "fom"
);
|
Name: WnSparseSolve__Phi__clearDebug()Description: Clear the debug flag for a sparse matrix exponentiation plus constant solver. Syntax:
void
WnSparseSolve__Phi__clearDebug(
WnSparseSolve__Phi *self
);
Input:
Upon successful return, the debug flag has been cleared for the solver so that debugging information will no longer be printed to stdout during solution iterations. If the input is invalid, error handling is invoked. Example: Clear the debug flag for WnSparseSolve__Phi *p_my_phi_solver:
WnSparseSolve__Phi__clearDebug(
p_my_phi_solver
);
|
Name: WnSparseSolve__Phi__free()Description: Free the memory allocated for a WnSparseSolve__Phi structure. Syntax:
void
WnSparseSolve__Phi__free(
WnSparseSolve__Phi *self
);
Input:
Upon successful return, the solver has been freed. The solver pointer self is no longer available for use--it must be reallocated using WnSparseSolve__Phi__new(). Example: Free the memory for WnSparseSolve__Phi *p_my_phi_solver:
WnSparseSolve__Phi__free(
p_my_solver
);
|
Name: WnSparseSolve__Phi__new()Description: Create a new sparse exponentiation plus constant solver. Syntax:
WnSparseSolve__Phi *
WnSparseSolve__Phi__new( );
Output:Upon successful return, a new solver has been created. The default values for the solver are that the maximum number of iterations allowed is 100, the tolerances are 1.e-8, the workspace has size 40, and debugging is turned off. These values can be updated by other API routines. Example: Create a new exponentiation solver:
p_my_phi_solver = WnSparseSolve__Phi__new();
|
Name: WnSparseSolve__Phi__setDebug()Description: Set the debug flag for a sparse matrix exponentiation plus constant solver. Syntax:
void
WnSparseSolve__Phi__setDebug(
WnSparseSolve__Phi *self
);
Input:
Upon successful return, the debug flag has been set for the solver so that debugging information will be printed to stdout during solution iterations. If the input is invalid, error handling is invoked. Example: Set the debug flag for WnSparseSolve__Phi *p_my_phi_solver:
WnSparseSolve__Phi__setDebug(
p_my_phi_solver
);
|
Name: WnSparseSolve__Phi__solve()Description: Solve a matrix equation dY/dt = AY + P, where P is a constant vector, by matrix exponentiation. Syntax:
gsl_vector *
WnSparseSolve__Phi__solve(
WnSparseSolve__Phi *self,
WnMatrix *p_matrix,
gsl_vector *p_initial_vector,
gsl_vector *p_constant_vector
);
Input:
Routine returns a gsl_vector with the solution (if solution successful) or NULL otherwise. Example: Solve the matrix equation dY/dt = AY + P where A is stored as WnMatrix *p_my_matrix over time 1. Y(0) is the initial vector stored in p_in. The constant vector is p_constant. Use the exponentiation solver p_my_phi and store the result in the gsl_vector p_sol:
p_sol =
WnSparseSolve__Phi__solve(
p_my_phi, p_my_matrix, p_in, p_const, 1.
);
if( p_sol )
fprintf( stdout, "Solution succeeded!\n" );
|
Name: WnSparseSolve__Phi__updateMaximumIterations()Description: Update the maximum number of iterations allowed for an exponentation plus constant solver. Syntax:
void
WnSparseSolve__Phi__updateMaximumIterations(
WnSparseSolve__Phi *self,
int i_iter_max
);
Input:
Upon successful return, the maximum number of iterations has been updated to the input value. If the input is invalid, error handling is invoked. Example: Set the maximum number of iterations for WnSparseSolve__Phi *p_my_phi_solver to 50:
WnSparseSolve__Mat__updateMaximumIterations(
p_my_phi_solver, 50
);
|
Name: WnSparseSolve__Phi__updateTolerance()Description: Update the tolerance for an exponentiation plus constant solver. Syntax:
void
WnSparseSolve__Phi__updateTolerance
WnSparseSolve__Phi *self,
double d_tolerance
);
Input:
Upon successful return, the tolerance has been updated to the input value. If the input is invalid, error handling is invoked. Example: Set the tolerance for WnSparseSolve__Phi *p_my_phi_solver to 1.e-12:
WnSparseSolve__Phi__updateTolerance(
p_my_phi_solver, 1.e-12
);
|
Name: WnSparseSolve__Phi__updateWorkSpace()Description: Update the allowed workspace for an exponentation plus constant solver. Syntax:
void
WnSparseSolve__Phi__updateWorkSpace(
WnSparseSolve__Phi *self,
int i_workspace
);
Input:
Upon successful return, the workspace has been updated to the input value. If the input is invalid, error handling is invoked. Example: Set the workspace for WnSparseSolve__Phi *p_my_phi_solver to 10:
WnSparseSolve__Mat__updateWorkSpace(
p_my_phi_solver, 10
);
|