SAMRAI::solv::CVODESolver Class Reference

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

#include <source/solvers/packages/sundials/cvode/CVODESolver.h>

Detailed Description

Class CVODESolver serves as a C++ wrapper for the CVODE 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 CVODEAbstractFunctions. The vector objects used within the solver are given in a subclass of the abstract class SundialsAbstractVector. The SundialsAbstractVector class defines the vector kernel operations required by the CVODE package so that they may be easily supplied by a user who opts not to use the vector kernel supplied by the CVODE package. (It should be noted that the vector kernel used by CVODE is the same as the one used by the other packages in the Sundials of solvers).

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

CVODESolver Usage:

In order to use the CVODESolver, the user must provide a concrete subclass of CVODEAbstractFunctions abstract base class which defines the evaluateRHSFunction(), CVSpgmrPrecondSet(), and CVSpgmrPrecondSolve() methods.

Solving a system of ODEs using this CVODE C++ interface requires four main stages. First, a CVODESolver object is created with a user-specified name and CVODEAbstractFunctions object. Second, the user must specify the integration parameters that s/he wishes to use. Next, the user must call the CVODESolver method initialize(solution_vector) with the SundialsAbstractVector that s/he wants to put the solution in. Finally, the solve() method is invoked to solve the system of ODEs to the specified value of the independent variable.

The following is a list of integration parameters that must be specified by the user before calling the solve() method:

Either relative or absolute tolerance must be set - setRelativeTolerance(relative_tolerance), setAbsoluteTolerance(absolute_tolerance)

Initial value of independent variable - setInitialValueOfIndependentVariable(init_time)
Final value of independent variable - setFinalValueOfIndependentVariable(final_time cvode_needs_initialization)
Initial condition vector - setInitialConditionVector(ic_vector)

The following is a list of default values for integration parameters:

Linear Multistep Method BDF

Iteration Type FUNCTIONAL

Tolerance Type SS (scalar relative and scalar absolute tolerances)

Relative Tolerance 0.0

Scalar Absolute Tolerance 0.0

Vector Absolute Tolerance NULL

Stepping Method NORMAL

Maximum Order for Multistep Method 12 for ADAMS, 5 for BDF

Maximum Number of Internal Steps 500

Maximum Number of NIL Step Warnings 10

Initial Step Size determined by CVODE

Maximum Absolute Value of Step Size infinity

Minimum Absolute Value of Step Size 0.0

CVSpgmr Preconditioning Type NONE

CVSpgmr Gram Schmidt Algorithm MODIFIED_GS

CVSpgmr Maximum Krylov Dimension MIN(num_equations, CVSPGMR_MAXL=5)

CVSpgmr Tolerance Scale Factor CVSPGMR_DELT = 0.05.

CVODE 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 CVODE header files. For more information about CVODE and a complete description of the operations and data structures used by this class, see S.D. Cohen and A.C. Hindmarsh, "CVODE User Guide", UCRL-MA-118618, Lawrence Livermore National Laboratory, 1994.

See also:: solv::CVODEAbstractFunctions
solv::SundialsAbstractVector

Constructor & Destructor Documentation

SAMRAI::solv::CVODESolver::CVODESolver	(	const std::string &	object_name,
		CVODEAbstractFunctions *	my_functions,
		const bool	uses_preconditioner
	)

Constructor for CVODESolver sets default CVODE parameters and initializes the solver package with user-supplied functions CVODESolver 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::CVODESolver::~CVODESolver ( ) [virtual]

Virtual destructor for CVODESolver closes the CVODE log file and frees the memory allocated for the CVODE memory record.

Member Function Documentation

void SAMRAI::solv::CVODESolver::initialize ( SundialsAbstractVector * solution )

Initialize solver with solution vector. The solution vector is required to initialize the memory record used internally within CVODE. 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::CVODESolver::solve ( )

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

CVODE Termination Codes:

SUCCESS (=0) CVode succeeded.

CVODE_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 CVODE or CVSpgmr requires re-initialization, it is automatically done before the solve. This may be required if any of the CVODE 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::CVODESolver::setLogFileData ( const std::string & log_fname = std::string() )

Accessor function for setting CVODE 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::CVODESolver::setCVODEFunctions	(	CVODEAbstractFunctions *	my_functions,
		const bool	uses_preconditioner
	)

Set CVODESolver to use my_functions as the concrete subclass of the CVODEAbstractFunctions 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 CVODEAbstractFunctions class.

Assertion checks:

my_function must not be a null pointer

CVODEAbstractFunctions * SAMRAI::solv::CVODESolver::getCVODEFunctions ( ) const

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

void SAMRAI::solv::CVODESolver::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::CVODESolver::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 CVODE 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::CVODESolver::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::CVODESolver::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::CVODESolver::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::CVODESolver::setAbsoluteTolerance ( SundialsAbstractVector * 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::CVODESolver::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::CVODESolver::setInitialValueOfIndependentVariable ( double t_0 )

Set initial value for independent variable.

void SAMRAI::solv::CVODESolver::setFinalValueOfIndependentVariable	(	double	t_f,
		bool	cvode_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 CVODE 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::CVODESolver::setInitialConditionVector ( SundialsAbstractVector * ic_vector )

Set initial condition vector.

Assertion checks:

ic_vector must not be null

void SAMRAI::solv::CVODESolver::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::CVODESolver::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::CVODESolver::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::CVODESolver::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::CVODESolver::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::CVODESolver::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::CVODESolver::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::CVODESolver::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::CVODESolver::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::CVODESolver::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

SundialsAbstractVector * SAMRAI::solv::CVODESolver::getSolutionVector ( ) const

Get solution vector.

int SAMRAI::solv::CVODESolver::getDkyVector	(	double	t,
		int	k,
		SundialsAbstractVector *	dky
	)			const

Get k-th derivative vector at the specified value of the independent variable, t. The integer return value is return code the CVODE 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::CVODESolver::getActualFinalValueOfIndependentVariable ( ) const

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

void SAMRAI::solv::CVODESolver::printStatistics ( std::ostream & os ) const

Print CVODE and CVSpgmr statistics.

void SAMRAI::solv::CVODESolver::printCVODEStatistics ( std::ostream & os ) const

Print CVODE 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::CVODESolver::getNumberOfInternalStepsTaken ( ) const

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