Main Page | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class Members | File Members | Related Pages
SAMRAI::solv::PVODESolver

SAMRAI::solv::PVODESolver Class Reference

Class PVODESolver serves as a C++ wrapper for the PVODE ordinary differential equation solver package. More...

#include <source/solvers/packages/pvode_trio/pvode/wrapper/PVODESolver.h>

List of all members.

Public Member Functions

 PVODESolver (const string &object_name, PVODEAbstractFunctions *my_functions, const bool uses_preconditioner)
 ~PVODESolver ()
void initialize (PVodeTrioAbstractVector *solution)
int solve ()
void setLogFileData (const string &log_fname=string())
void setPVODEFunctions (PVODEAbstractFunctions *my_functions, const bool uses_preconditioner)
PVODEAbstractFunctions * getPVODEFunctions () const
void setNumberOfEquations (int neq)
void setLinearMultistepMethod (int linear_multistep_method)
void setIterationType (int iteration_type)
void setToleranceType (int tolerance_type)
void setRelativeTolerance (double relative_tolerance)
void setAbsoluteTolerance (double absolute_tolerance)
void setAbsoluteTolerance (PVodeTrioAbstractVector *absolute_tolerance)
void setSteppingMethod (int stepping_method)
void setInitialValueOfIndependentVariable (double t_0)
void setFinalValueOfIndependentVariable (double t_f, bool pvode_needs_initialization)
void setInitialConditionVector (PVodeTrioAbstractVector *ic_vector)
void setMaximumLinearMultistepMethodOrder (int max_order)
void setMaximumNumberOfInternalSteps (int max_num_internal_steps)
void setMaximumNumberOfNilStepWarnings (int max_num_warnings)
void setInitialStepSize (double init_step_size)
void setMaximumAbsoluteStepSize (double max_step_size)
void setMinimumAbsoluteStepSize (double min_step_size)
void setPreconditioningType (int precondition_type)
void setGramSchmidtType (int gs_type)
void setMaxKrylovDimension (int max_krylov_dim)
void setCVSpgmrToleranceScaleFactor (double tol_scale_factor)
PVodeTrioAbstractVector * getSolutionVector () const
int getDkyVector (double t, int k, PVodeTrioAbstractVector *dky) const
double getActualFinalValueOfIndependentVariable () const
void turnOnPVODEStatisticsCollection ()
void printStatistics (ostream &os) const
void printPVODEStatistics (ostream &os) const
int getNumberOfInternalStepsTaken () const
int getNumberOfRHSFunctionCalls () const
int getNumberOfLinearSolverSetupCalls () const
int getNumberOfNewtonIterations () const
int getNumberOfNonlinearConvergenceFailures () const
int getNumberOfLocalErrorTestFailures () const
int getOrderUsedDuringLastInternalStep () const
int getOrderToBeUsedDuringNextInternalStep () const
int getPVODEMemoryUsageForDoubles () const
int getPVODEMemoryUsageForIntegers () const
double getStepSizeForLastInternalStep () const
double getStepSizeForNextInternalStep () const
double getCurrentInternalValueOfIndependentVariable () const
double getPVODESuggestedToleranceScalingFactor () const
void printCVSpgmrStatistics (ostream &os) const
int getNumberOfPreconditionerEvaluations () const
int getNumberOfLinearIterations () const
int getNumberOfPrecondSolveCalls () const
int getNumberOfLinearConvergenceFailures () const
int getCVSpgmrMemoryUsageForDoubles () const
int getCVSpgmrMemoryUsageForIntegers () const
void printClassData (ostream &os) const

Detailed Description

Class PVODESolver serves as a C++ wrapper for the PVODE ordinary differential equation solver package.

It is intended to be sufficiently generic to be used independently of the SAMRAI framework. This class declares one private static member function to link the user-defined routine for right-hand side function evaluation and two private statice member functions to link the user-defined preconditioner setup and solve routines. The implementation of these functions is defined by the user in a subclass of the abstract base class PVODEAbstractFunctions. The vector objects used within the solver are given in a subclass of the abstract class PVodeTrioAbstractVector. The PVodeTrioAbstractVector class defines the vector kernel operations required by the PVODE package so that they may be easily supplied by a user who opts not to use the vector kernel supplied by the PVODE package. (It should be noted that the vector kernel used by PVODE is the same as the one used by the other packages in the PVodeTrio of solvers).

Note that this class provides no input or restart capabilities and relies on PVODE for output reporting.

PVODESolver Usage:

PVODE was developed in the Center for Applied Scientific Computing (CASC) at Lawrence Livermore National Laboratory (LLNL). Many of the comments in this class were taken verbatim from PVODE header files. For more information about PVODE and a complete description of the operations and data structures used by this class, see S.D. Cohen and A.C. Hindmarsh, "PVODE User Guide", UCRL-MA-118618, Lawrence Livermore National Laboratory, 1994.

See also:
solv::PVODEAbstractFunctions

solv::PVodeTrioAbstractVector

Constructor & Destructor Documentation

SAMRAI::solv::PVODESolver::PVODESolver (  const string &  object_name,
PVODEAbstractFunctions *  my_functions,
const bool  uses_preconditioner
) 
 

Constructor for PVODESolver sets default PVODE parameters and initializes the solver package with user-supplied functions PVODESolver parameters may be changed later using member functions described below.

Notes:

  • The solution vector is not passed into the constructor. Before the solver can be used, the initialize() function must be called.

Assertion checks:

  • my_functions must not be null

  • object_name must not be empty.

SAMRAI::solv::PVODESolver::~PVODESolver (   ) 
 

Virtual destructor for PVODESolver closes the PVODE log file and frees the memory allocated for the PVODE memory record.

Member Function Documentation

void SAMRAI::solv::PVODESolver::initialize (  PVodeTrioAbstractVector *  solution  ) 
 

Initialize solver with solution vector. The solution vector is required to initialize the memory record used internally within PVODE. This routine must be called before the solver can be used.

Assertion checks:

  • the solution vector must not be null

  • the solution vector must not have already been set

int SAMRAI::solv::PVODESolver::solve (   ) 
 

Integrate ODE system specified t_f. The integer return value is a termination code defined by PVODE. The following is a table of termination codes and a brief description of their meanings.

PVODE Termination Codes:

  • SUCCESS (=0) CVode succeeded.

  • PVODE_NO_MEM (=-1) The cvode_mem argument was NULL.

  • ILL_INPUT (=-2) One of the inputs to CVode is illegal. This includes the situation when a component of the error weight vectors becomes < 0 during internal time-stepping. The ILL_INPUT flag will also be returned if the linear solver routine CV--- (called by the user after calling CVodeMalloc) failed to set one of the linear solver-related fields in cvode_mem or if the linear solver's init routine failed. In any case, the user should see the printed error message for more details.

  • TOO_MUCH_WORK (=-3) The solver took maxstep internal steps but could not reach t_f. The default value for mxstep is MXSTEP_DEFAULT = 500.

  • TOO_MUCH_ACC (=-4) The solver could not satisfy the accuracy demanded by the user for some internal step.

  • ERR_FAILURE (=-5) Error test failures occurred too many times (= MXNEF = 7) during one internal time step or occurred with |h| = hmin.

  • CONV_FAILURE (=-6) Convergence test failures occurred too many times (= MXNCF = 10) during one internal time step or occurred with |h| = hmin.

  • SETUP_FAILURE (=-7) The linear solver's setup routine failed in an unrecoverable manner.

  • SOLVE_FAILURE (=-8) The linear solver's solve routine failed in an unrecoverable manner.

See cvode.h header file for more information about return values.

If PVODE or CVSpgmr requires re-initialization, it is automatically done before the solve. This may be required if any of the PVODE or CVSpgmr data parameters have changed since the last call to the solver.

Assertion checks:

  • The user specified final value for the independent variable t must be greater than the specified initial value.

void SAMRAI::solv::PVODESolver::setLogFileData (  const string &  log_fname = string()  ) 
 

Accessor function for setting PVODE output log file name and output printing options. Output file name and options may be changed throughout run as desired.

If the file name string is empty the default file name "cvode.log" is used.

void SAMRAI::solv::PVODESolver::setPVODEFunctions (  PVODEAbstractFunctions *  my_functions,
const bool  uses_preconditioner
) 
 

Set PVODESolver to use my_functions as the concrete subclass of the PVODEAbstractFunctions class that defines the right-hand side evaluation and preconditioner functions. The uses_preconditioner argument indicates whether or not the the user has defined preconditioner routines in their concrete subclass of the PVODEAbstractFunctions class.

Assertion checks:

  • my_function must not be a null pointer

PVODEAbstractFunctions * SAMRAI::solv::PVODESolver::getPVODEFunctions (   )  const
 

Return pointer to object that provides user-defined functions for PVODE and CVSpgmr.

void SAMRAI::solv::PVODESolver::setNumberOfEquations (  int  neq  ) 
 

Set number of equations in system of ODEs to be solved.

Assertion checks:

  • neq must be positive

void SAMRAI::solv::PVODESolver::setLinearMultistepMethod (  int  linear_multistep_method  ) 
 

Set linear multistep method. The user can specify either ADAMS or BDF (backward differentiation formula) methods The BDF method is recommended for stiff problems, and the ADAMS method is recommended for nonstiff problems.

Assertion checks:

  • linear_multistep_method must be one of ADAMS or BDF.

Note: the enumeration constants ADAMS and BDF are defined in cvode.h.

void SAMRAI::solv::PVODESolver::setIterationType (  int  iteration_type  ) 
 

Set iteration type. The user can specify either FUNCTIONAL iteration, which does not require linear algebra, or a NEWTON iteration, which requires the solution of linear systems. In the NEWTON case, the user must also specify a PVODE linear solver. NEWTON is recommended in case of stiff problems.

Assertion checks:

  • iteration_type must be one of FUNCTIONAL or NEWTON

Note: the enumeration constants FUNCTIONAL and NEWTON are defined in cvode.h.

void SAMRAI::solv::PVODESolver::setToleranceType (  int  tolerance_type  ) 
 

Set tolerance type. This parameter specifies the relative and absolute tolerance types to be used. The SS tolerance type means a scalar relative and absolute tolerance, while the SV tolerance type means a scalar relative tolerance and a vector absolute tolerance (a potentially different absolute tolerance for each vector component).

Assertion checks:

  • tolerance_type must be one of SS or SV

Note: the enumeration constants SS and SV are defined in cvode.h.

void SAMRAI::solv::PVODESolver::setRelativeTolerance (  double  relative_tolerance  ) 
 

Set the relative tolerance level.

Assertion checks:

  • relative_tolerance must be greater than or equal to 0.0

Note that pure absolute tolerance can be used by setting the relative tolerance to 0. However, it is an error to simultaneously set relative and absolute tolerances to 0.

void SAMRAI::solv::PVODESolver::setAbsoluteTolerance (  double  absolute_tolerance  ) 
 

Set the scalar absolute tolerance level.

Assertion checks:

  • absolute_tolerance must be greater than or equal to 0.0

Note that pure relative tolerance can be used by setting the absolute tolerance to 0. However, it is an error to simultaneously set relative and absolute tolerances to 0.

void SAMRAI::solv::PVODESolver::setAbsoluteTolerance (  PVodeTrioAbstractVector *  absolute_tolerance  ) 
 

Set the vector absolute tolerance level.

Assertion checks:

  • absolute_tolerance must not be a null pointer

  • each component of absolute_tolerance must be greater than or equal to 0.0

Note that pure relative tolerance can be used by setting the absolute tolerance to 0. However, it is an error to simultaneously set relative and absolute tolerances to 0.

void SAMRAI::solv::PVODESolver::setSteppingMethod (  int  stepping_method  ) 
 

Set stepping method to use for integration. There are stepping methods: NORMAL and ONE_STEP. The NORMAL method has the solver take internal steps until it has reached or just passed the user specified t_f parameter. The solver then interpolates in order to return an approximate value of y(t_f). The ONE_STEP option tells the solver to just take one internal step and return the solution at the point reached by that step.

Assertion checks:

  • stepping_method must be one of NORMAL or ONE_STEP

Note: the enumeration constants NORMAL and ONE_STEP are defined in cvode.h.

void SAMRAI::solv::PVODESolver::setInitialValueOfIndependentVariable (  double  t_0  ) 
 

Set initial value for independent variable.

void SAMRAI::solv::PVODESolver::setFinalValueOfIndependentVariable (  double  t_f,
bool  pvode_needs_initialization
) 
 

Set final value for independent variable (i.e. the value of independent variable to integrate the system to). The boolean argument specifies whether PVODE should be re-initialized (i.e. on first step) or if we are taking subsequent steps in a sequence, in which case it is not initialized.

void SAMRAI::solv::PVODESolver::setInitialConditionVector (  PVodeTrioAbstractVector *  ic_vector  ) 
 

Set initial condition vector.

Assertion checks:

  • ic_vector must not be null

void SAMRAI::solv::PVODESolver::setMaximumLinearMultistepMethodOrder (  int  max_order  ) 
 

Set maximum order for the linear multistep method. By default, this is set to 12 for ADAMS methods and 5 for BDF methods.

Assertion checks:

  • max_order must be greater than or equal to 0

void SAMRAI::solv::PVODESolver::setMaximumNumberOfInternalSteps (  int  max_num_internal_steps  ) 
 

Set maximum number of internal steps to be taken by the solver in its attempt to reach t_f. By default, this is set to 500.

Assertion checks:

  • max_num_internal_steps must be greater than or equal to 0

void SAMRAI::solv::PVODESolver::setMaximumNumberOfNilStepWarnings (  int  max_num_warnings  ) 
 

Set maximum number of warning messages issued by the solver that (t + h == t) on the next internal step. By default, this is set to 10.

Assertion checks:

  • max_num_warnings must be greater than or equal to 0

void SAMRAI::solv::PVODESolver::setInitialStepSize (  double  init_step_size  ) 
 

Set initial step size.

Assertion checks:

  • init_step_size must be greater than or equal to 0.0

void SAMRAI::solv::PVODESolver::setMaximumAbsoluteStepSize (  double  max_step_size  ) 
 

Set maximum absolute value of step size allowed. By default, there is no upper bound on the absolute value of step size.

Assertion checks:

  • max_step_size must be greater than or equal to 0.0

void SAMRAI::solv::PVODESolver::setMinimumAbsoluteStepSize (  double  min_step_size  ) 
 

Set minimum absolute value of step size allowed. By default, this is set to 0.0.

Assertion checks:

  • min_step_size must be greater than or equal to 0.0

void SAMRAI::solv::PVODESolver::setPreconditioningType (  int  precondition_type  ) 
 

Set the preconditioning type to be used by CVSpgmr. This must be one of the four enumeration constants NONE, LEFT, RIGHT, or BOTH defined in iterativ.h. These correspond to no preconditioning, left preconditioning only, right preconditioning only, and both left and right preconditioning, respectively.

Assertion Checks:

  • precondition_type must be one of NONE, LEFT, RIGHT, or BOTH.

void SAMRAI::solv::PVODESolver::setGramSchmidtType (  int  gs_type  ) 
 

Set the Gram-Schmidt orthogonalization type to be used by CVSpgmr. This must be one of the two enumeration constants MODIFIED_GS or CLASSICAL_GS defined in iterativ.h. These correspond to using modified Gram-Schmidt and classical Gram-Schmidt, respectively.

Assertion Checks:

  • gs_type must be one of CLASSICAL_GS or MODIFIED_GS.

void SAMRAI::solv::PVODESolver::setMaxKrylovDimension (  int  max_krylov_dim  ) 
 

Set the maximum Krylov dimension to be used by CVSpgmr. This is an optional input to the CVSPGMR solver. Pass 0 to use the default value MIN(num_equations, CVSPGMR_MAXL=5).

Assertion Checks:

  • max_krylov_dim must be nonnegative

void SAMRAI::solv::PVODESolver::setCVSpgmrToleranceScaleFactor (  double  tol_scale_factor  ) 
 

Set the factor by which the tolerance on the nonlinear iteration is multiplied to get a tolerance on the linear iteration. This is an optional input to the CVSPGMR solver. Pass 0 to use the default value CVSPGMR_DELT = 0.05.

Assertion Checks:

  • tol_scale_factor must be nonnegative

PVodeTrioAbstractVector * SAMRAI::solv::PVODESolver::getSolutionVector (   )  const
 

Get solution vector.

int SAMRAI::solv::PVODESolver::getDkyVector (  double  t,
int  k,
PVodeTrioAbstractVector *  dky
)  const
 

Get k-th derivative vector at the specified value of the independent variable, t. The integer return value is return code the PVODE CVodeDky() function. The following is a table of termination codes and a brief description of their meanings.

CVodeDky Return Codes:

  • OKAY (=0) CVodeDky succeeded.

  • BAD_K (=-1)

  • BAD_T (=-2)

  • BAD_DKY (=-3)

  • DKY_NO_MEM (=-4)

Important Notes:

  • t must lie in the interval [t_cur - h, t_cur] where t_cur is the current internal time reached and h is the last internal step size successfully used by the solver.

  • k may take on value 0, 1, . . . q where q is the order of the current linear multistep method being used.

  • the dky vector must be allocated by the user.

  • it is only leagal to call this method after a successful return from the solve() method.

double SAMRAI::solv::PVODESolver::getActualFinalValueOfIndependentVariable (   )  const
 

Get actual value of the independent variable that PVODE integrated to (i.e. the value of t that actually corresponds to the solution vector y).

void SAMRAI::solv::PVODESolver::turnOnPVODEStatisticsCollection (   ) 
 

Set PVODE to collect statistics. This must be called before solve() is invoked.

void SAMRAI::solv::PVODESolver::printStatistics (  ostream &  os  )  const
 

Print PVODE and CVSpgmr statistics.

void SAMRAI::solv::PVODESolver::printPVODEStatistics (  ostream &  os  )  const
 

Print PVODE statistics to the stream.

The abbreviations printed out refer to the following quantities:

  • lenrw size (in double words) of memory used for doubles

  • leniw size (in integer words) of memory used for integers

  • nst cumulative number of internal steps taken by solver

  • nfe number of right-hand side function evaluations

  • nni number of NEWTON iterations performed

  • nsetups number of calls made to linear solver's setup routine

  • netf number of local error test failures

  • ncfn number of nonlinear convergence failures

  • qu order used during the last internal step

  • qcur order to be used on the next internal step

  • hu step size for the last internal step

  • hcur step size to be attempted on the next internal step

  • tcur current internal value of t reached by the solver

  • tolsf suggested tolerance scaling factor

int SAMRAI::solv::PVODESolver::getNumberOfInternalStepsTaken (   )  const
 

Return the cumulative number of internal steps taken by the solver.

Note: if the solver was not set to collect statistics, a value of -1 is returned.

int SAMRAI::solv::PVODESolver::getNumberOfRHSFunctionCalls (   )  const
 

Return the number of calls to the right-hand side function.

Note: if the solver was not set to collect statistics, a value of -1 is returned.

int SAMRAI::solv::PVODESolver::getNumberOfLinearSolverSetupCalls (   )  const
 

Return the number of calls made to linear solver setup routines.

Note: if the solver was not set to collect statistics, a value of -1 is returned.

int SAMRAI::solv::PVODESolver::getNumberOfNewtonIterations (   )  const
 

Return the number of NEWTON iterations performed.

Note: if the solver was not set to collect statistics, a value of -1 is returned.

int SAMRAI::solv::PVODESolver::getNumberOfNonlinearConvergenceFailures (   )  const
 

Return the number of nonlinear convergence failures that have occurred.

Note: if the solver was not set to collect statistics, a value of -1 is returned.

int SAMRAI::solv::PVODESolver::getNumberOfLocalErrorTestFailures (   )  const
 

Return the number of local error test failures.

Note: if the solver was not set to collect statistics, a value of -1 is returned.

int SAMRAI::solv::PVODESolver::getOrderUsedDuringLastInternalStep (   )  const
 

Return the order of the linear multistep method used during the last internal step.

Note: if the solver was not set to collect statistics, a value of -1 is returned.

int SAMRAI::solv::PVODESolver::getOrderToBeUsedDuringNextInternalStep (   )  const
 

Return the order of the linear multistep method to be used during the next internal step.

Note: if the solver was not set to collect statistics, a value of -1 is returned.

int SAMRAI::solv::PVODESolver::getPVODEMemoryUsageForDoubles (   )  const
 

Return the size (in LLNL_REAL words) of memory used for LLNL_REALS.

Note: if the solver was not set to collect statistics, a value of -1 is returned.

int SAMRAI::solv::PVODESolver::getPVODEMemoryUsageForIntegers (   )  const
 

Return the size (in integer words) of memory used for integers.

Note: if the solver was not set to collect statistics, a value of -1 is returned.

double SAMRAI::solv::PVODESolver::getStepSizeForLastInternalStep (   )  const
 

Return the step size for the last internal step.

Note: if the solver was not set to collect statistics, a value of -1 is returned.

double SAMRAI::solv::PVODESolver::getStepSizeForNextInternalStep (   )  const
 

Return the step size to be used in the next internal step.

Note: if the solver was not set to collect statistics, a value of -1 is returned.

double SAMRAI::solv::PVODESolver::getCurrentInternalValueOfIndependentVariable (   )  const
 

Return the current internal value of the independent variable reached by the solver.

Note: if the solver was not set to collect statistics, the minimum double value (as defined in float.h) is returned.

double SAMRAI::solv::PVODESolver::getPVODESuggestedToleranceScalingFactor (   )  const
 

Return the suggested tolerance scaling factor.

Note: if the solver was not set to collect statistics, a value of -1 is returned.

void SAMRAI::solv::PVODESolver::printCVSpgmrStatistics (  ostream &  os  )  const
 

Print CVSpgmr statistics to the stream.

The abbreviations printed out refer to the following quantities:

  • spgmr_lrw size (in double words) of memory used for doubles

  • spgmr_liw size (in integer words) of memory used for integers

  • nli number of linear iterations

  • ncfl number of linear convergence failures

  • npe number of preconditioner evaluations

  • nps number of calls to CVSpgmrPrecondSolve()

int SAMRAI::solv::PVODESolver::getNumberOfPreconditionerEvaluations (   )  const
 

Return the number of preconditioner evaluations.

int SAMRAI::solv::PVODESolver::getNumberOfLinearIterations (   )  const
 

Return the number of linear iterations.

int SAMRAI::solv::PVODESolver::getNumberOfPrecondSolveCalls (   )  const
 

Return the number of CVSpgmrPrecondSolve() calls.

int SAMRAI::solv::PVODESolver::getNumberOfLinearConvergenceFailures (   )  const
 

Return the number of linear convergence failures.

int SAMRAI::solv::PVODESolver::getCVSpgmrMemoryUsageForDoubles (   )  const
 

Return the size (in double words) of memory used for doubles.

int SAMRAI::solv::PVODESolver::getCVSpgmrMemoryUsageForIntegers (   )  const
 

Return the size (in integer words) of memory used for integers.

void SAMRAI::solv::PVODESolver::printClassData (  ostream &  os  )  const
 

Print out all data members for this object.

The documentation for this class was generated from the following files:
Generated on Fri Dec 2 11:30:30 2005 for SAMRAI by  doxygen 1.4.2